This module implements the plugin api bits.
Two things about things in this module:
Plugins are structured like any Python project. You create a Python package. In that package, you define a high-level __init__.py module that has a hooks dict that maps hooks to callables that implement those hooks.
Additionally, you want a LICENSE file that specifies the license and a setup.py that specifies the metadata for packaging your plugin. A rough file structure could look like this:
myplugin/
|- setup.py # plugin project packaging metadata
|- README # holds plugin project information
|- LICENSE # holds license information
|- myplugin/ # plugin package directory
|- __init__.py # has hooks dict and code
Retrieves the configuration for a specified plugin by key
Example:
>>> get_config('mediagoblin.plugins.sampleplugin')
{'foo': 'bar'}
>>> get_config('myplugin')
{}
>>> get_config('flatpages')
{'directory': '/srv/mediagoblin/pages', 'nesting': 1}}
Registers one or more routes
If your plugin handles requests, then you need to call this with the routes your plugin handles.
A “route” is a routes.Route object. See the routes.Route documentation for more details.
Example passing in a single route:
>>> register_routes(('about-view', '/about',
... 'mediagoblin.views:about_view_handler'))
Example passing in a list of routes:
>>> register_routes([
... ('contact-view', '/contact', 'mediagoblin.views:contact_handler'),
... ('about-view', '/about', 'mediagoblin.views:about_handler')
... ])
Note
Be careful when designing your route urls. If they clash with core urls, then it could result in DISASTER!
Registers a path for template loading
If your plugin has templates, then you need to call this with the absolute path of the root of templates directory.
Example:
>>> my_plugin_dir = os.path.dirname(__file__)
>>> template_dir = os.path.join(my_plugin_dir, 'templates')
>>> register_template_path(template_dir)
Note
You can only do this in setup_plugins(). Doing this after that will have no effect on template loading.
Register a dict of template hooks.
Takes template_hooks as an argument, which is a dictionary of template hook names/keys to the templates they should provide. (The value can either be a single template path or an iterable of paths.)
Example:
{"media_sidebar": "/plugin/sidemess/mess_up_the_side.html",
"media_descriptionbox": ["/plugin/sidemess/even_more_mess.html",
"/plugin/sidemess/so_much_mess.html"]}
Get a list of hook templates for this hook_name.
Note: for the most part, you access this via a template tag, not this method directly, like so:
{% template_hook "media_sidebar" %}
... which will include all templates for you, partly using this method.
However, this method is exposed to templates, and if you wish, you can iterate over templates in a template hook manually like so:
{% for template_path in get_hook_templates("media_sidebar") %}
<div class="extra_structure">
{% include template_path %}
</div>
{% endfor %}