Quick Start

This is a quick start. It’s not comprehensive, but it walks through writing a basic plugin called “sampleplugin” which logs “I’ve been started!” when setup_plugin() has been called.

Step 1: Files and directories

GNU MediaGoblin plugins are Python projects at heart. As such, you should use a standard Python project directory tree:

sampleplugin/
 |- README
 |- LICENSE
 |- setup.py
 |- sampleplugin/
    |- __init__.py

The outer sampleplugin directory holds all the project files.

The README should cover what your plugin does, how to install it, how to configure it, and all the sorts of things a README should cover.

The LICENSE should have the license under which you’re distributing your plugin.

The inner sampleplugin directory is the Python package that holds your plugin’s code.

The __init__.py denotes that this is a Python package. It also holds the plugin code and the hooks dict that specifies which hooks the sampleplugin uses.

Step 2: README

Here’s a rough README. Generally, you want more information because this is the file that most people open when they want to learn more about your project.

README
======

This is a sample plugin. It logs a line when ``setup__plugin()`` is
run.

Step 3: LICENSE

GNU MediaGoblin plugins must be licensed under the AGPLv3 or later. So the LICENSE file should be the AGPLv3 text which you can find at http://www.gnu.org/licenses/agpl-3.0.html

Step 4: setup.py

This file is used for packaging and distributing your plugin.

We’ll use a basic one:

from setuptools import setup, find_packages

setup(
    name='sampleplugin',
    version='1.0',
    packages=find_packages(),
    include_package_data=True,
    install_requires=[],
    license='AGPLv3',
    )

See http://docs.python.org/distutils/index.html#distutils-index for more details.

Step 5: the code

The code for __init__.py looks like this:

import logging
from mediagoblin.tools.pluginapi import PluginManager, get_config


# This creates a logger that you can use to log information to
# the console or a log file.
_log = logging.getLogger(__name__)


# This is the function that gets called when the setup
# hook fires.
def setup_plugin():
    _log.info("I've been started!")
    config = get_config('sampleplugin')
    if config:
        _log.info('%r' % config)
    else:
        _log.info('There is no configuration set.')


# This is a dict that specifies which hooks this plugin uses.
# This one only uses one hook: setup.
hooks = {
    'setup': setup_plugin
    }

Line 12 defines the setup_plugin function.

Line 23 defines hooks. When MediaGoblin loads this file, it sees hooks and registers all the callables with their respective hooks.

Step 6: Installation and configuration

To install the plugin for development, you need to make sure it’s available to the Python interpreter that’s running MediaGoblin.

There are a couple of ways to do this, but we’re going to pick the easy one.

Use python from your MediaGoblin virtual environment and do:

python setup.py develop

Any changes you make to your plugin will be available in your MediaGoblin virtual environment.

Then adjust your mediagoblin.ini file to load the plugin:

[plugins]

[[sampleplugin]]

Step 7: That’s it!

When you launch MediaGoblin, it’ll load the plugin and you’ll see evidence of that in the log file.

That’s it for the quick start!

Where to go from here

See the documentation on the Plugin API for code samples and other things you can use when building your plugin. If your plugin needs its own database models, see Database models for plugins.

See Hitchhiker’s Guide to Packaging for more information on packaging your plugin.