View source for PluginsTips

==Quickstart==
In the [https://gitorious.org/mediagoblin mediagoblin repository], there's a sample plugin under mediagoblin/plugins/sampleplugin that you can use to get started with plugin creation. The simplest way to get up and running is to 
# Follow [[HackingHowto#How_to_set_up_and_maintain_an_environment_for_hacking_with_virtualenv]] to set up a local virtualenv mediagoblin instance 
#* run it with ./lazyserver.sh so you get debug output (if you run celeryd separately, you won't see logging.info from stuff run in celery tasks)
# <tt>cp -r mediagoblin/plugins/sampleplugin mediagoblin/plugins/myplugin</tt> (where "myplugin" is your plugin name)
# <tt>cp mediagoblin.ini mediagoblin_local.ini</tt>
# edit <tt>mediagoblin_local.ini</tt> and add <nowiki>[[mediagoblin.plugins.myplugin]]</nowiki> under the <nowiki>[plugins]</nowiki> section to enable your plugin

Now you can look at e.g. other core or non-core plugins for inspiration. See [[Available Plugins]] for non-core plugins.


The way you change things in plugins is by use of '''hooks'''. At certain points in the mediagoblin code, a function will say "run all hooks with name XYZ", and if you've defined a hook with such a name in a plugin you've enabled, it'll get run there. The [http://mediagoblin.readthedocs.org/en/latest/pluginwriter/api.html documentation on Plugin API] is your friend for defining hooks. The sample plugin shows a use of the 'setup' hook.

Note: templates are hooked with a call to pluginapi.register_template_hooks, instead of adding to the hooks variable.

==Making an installable plugin==
If you followed the steps above, you can use your plugin by copying it into the plugins folder; however, to get a plugin that is easily installable by users (e.g. with <tt>pip install myplugin</tt>), it should have a certain folder layout. 

A good example is the [https://github.com/commonsmachinery/mg-rdfa/ RDFa plugin]. This uses a setup.py file to install the files under the mediagoblin_rdfa folder into the lib/ folder of your mediagoblin installation. If you've checked out both mediagoblin and mg-rdfa in the same folder, e.g. ~/src/, you can do <pre>cd ~/src/mg-rdfa/
../mediagoblin/bin/python setup.py build
../mediagoblin/bin/python setup.py install</pre> to install it to your mediagoblin instance.

The file layout of the repo is:
<pre>
setup.py
MANIFEST.in
README.md
mediagoblin_rdfa/
                 __init.py__
                 templates/
                           mediagoblin/
                                       plugins/
                                               rdfa/
                                                    metadata.html
</pre>

The setup.py file defines an option include_package_data=True, which makes it read the file MANIFEST.in; MANIFEST.in contains rules for which files to include when installing. In this case, rule <tt>recursive-include mediagoblin_rdfa *.html</tt> makes it include the HTML template file (and any other you put under mediagoblin_rdfa), retaining the folder layout.

==Referencing the mediagoblin test set in a plugin==

The tests in mediagoblin define a nice "test_app" and functions for logging in and posting and so on. You can use this in your installable plugin.

From your plugin (assuming a layout like mg-rdfa described above), doing

    cp -r ../mediagoblin/mediagoblin/tests .

lets you run

    ../mediagoblin/bin/py.test tests --boxed               

In fact, the only files you need are `conftest.py` and `pytest.ini`, and then you can copy over a single `test_foo.py` (only making sure import statements are absolute) and it should run fine.

You also need to call setup_plugins() in your setup() function for your plugin to be properly loaded before testing.

An example of this test method is in the [https://gitorious.org/mediagoblin-stock/mediagoblin-hidden_original/ "hidden original" plugin], which subclasses the submission tests.


See also [http://mediagoblin.readthedocs.org/en/latest/pluginwriter/tests.html Writing unit tests for plugins] in the docs.