113 lines
3.3 KiB
ReStructuredText
113 lines
3.3 KiB
ReStructuredText
.. MediaGoblin Documentation
|
|
|
|
Written in 2013 by MediaGoblin contributors
|
|
|
|
To the extent possible under law, the author(s) have dedicated all
|
|
copyright and related and neighboring rights to this software to
|
|
the public domain worldwide. This software is distributed without
|
|
any warranty.
|
|
|
|
You should have received a copy of the CC0 Public Domain
|
|
Dedication along with this software. If not, see
|
|
<http://creativecommons.org/publicdomain/zero/1.0/>.
|
|
|
|
|
|
==========
|
|
Plugin API
|
|
==========
|
|
|
|
This documents the general plugin API.
|
|
|
|
Please note, at this point OUR PLUGIN HOOKS MAY AND WILL CHANGE.
|
|
Authors are encouraged to develop plugins and work with the
|
|
MediaGoblin community to keep them up to date, but this API will be a
|
|
moving target for a few releases.
|
|
|
|
Please check the release notes for updates!
|
|
|
|
:mod:`pluginapi` Module
|
|
-----------------------
|
|
|
|
.. automodule:: mediagoblin.tools.pluginapi
|
|
:members: get_config, register_routes, register_template_path,
|
|
register_template_hooks, get_hook_templates,
|
|
hook_handle, hook_runall, hook_transform
|
|
|
|
Configuration
|
|
-------------
|
|
|
|
Your plugin may define its own configuration defaults.
|
|
|
|
Simply add to the directory of your plugin a config_spec.ini file. An
|
|
example might look like::
|
|
|
|
[plugin_spec]
|
|
some_string = string(default="blork")
|
|
some_int = integer(default=50)
|
|
|
|
This means that when people enable your plugin in their config you'll
|
|
be able to provide defaults as well as type validation.
|
|
|
|
|
|
Context Hooks
|
|
-------------
|
|
|
|
View specific hooks
|
|
+++++++++++++++++++
|
|
|
|
You can hook up to almost any template called by any specific view
|
|
fairly easily. As long as the view directly or indirectly uses the
|
|
method ``render_to_response`` you can access the context via a hook
|
|
that has a key in the format of the tuple::
|
|
|
|
(view_symbolic_name, view_template_path)
|
|
|
|
Where the "view symbolic name" is the same parameter used in
|
|
``request.urlgen()`` to look up the test. So say we're wanting to add
|
|
something to the context of the user's homepage. We look in
|
|
mediagoblin/user_pages/routing.py and see::
|
|
|
|
add_route('mediagoblin.user_pages.user_home',
|
|
'/u/<string:user>/',
|
|
'mediagoblin.user_pages.views:user_home')
|
|
|
|
Aha! That means that the name is ``mediagoblin.user_pages.user_home``.
|
|
Okay, so then we look at the view at the
|
|
``mediagoblin.user_pages.views:user_home`` method::
|
|
|
|
@uses_pagination
|
|
def user_home(request, page):
|
|
# [...] whole bunch of stuff here
|
|
return render_to_response(
|
|
request,
|
|
'mediagoblin/user_pages/user.html',
|
|
{'user': user,
|
|
'user_gallery_url': user_gallery_url,
|
|
'media_entries': media_entries,
|
|
'pagination': pagination})
|
|
|
|
Nice! So the template appears to be
|
|
``mediagoblin/user_pages/user.html``. Cool, that means that the key
|
|
is::
|
|
|
|
("mediagoblin.user_pages.views:user_home",
|
|
"mediagoblin/user_pages/user.html")
|
|
|
|
The context hook uses ``hook_transform()`` so that means that if we're
|
|
hooking into it, our hook will both accept one argument, ``context``,
|
|
and should return that modified object, like so::
|
|
|
|
def add_to_user_home_context(context):
|
|
context['foo'] = 'bar'
|
|
return context
|
|
|
|
hooks = {
|
|
("mediagoblin.user_pages.views:user_home",
|
|
"mediagoblin/user_pages/user.html"): add_to_user_home_context}
|
|
|
|
|
|
Global context hook
|
|
+++++++++++++++++++
|
|
|
|
|