Plugin API

pluginapi Module

This module implements the plugin api bits.

Two things about things in this module:

  1. they should be excessively well documented because we should pull from this file for the docs
  2. they should be well tested

How do plugins work?

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

Lifecycle

  1. All the modules listed as subsections of the plugins section in the config file are imported. MediaGoblin registers any hooks in the hooks dict of those modules.
  2. After all plugin modules are imported, the setup hook is called allowing plugins to do any set up they need to do.
mediagoblin.tools.pluginapi.get_config(key)

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}}
mediagoblin.tools.pluginapi.register_routes(routes)

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!

mediagoblin.tools.pluginapi.register_template_path(path)

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.

mediagoblin.tools.pluginapi.register_template_hooks(template_hooks)

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"]}
mediagoblin.tools.pluginapi.get_hook_templates(hook_name)

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 %}
Returns:
A list of strings representing template paths.

Table Of Contents

Previous topic

Database

Next topic

Codebase Documentation

This Page