Operators Guide to MediaCore CE Plugins

Posted:
by Felix Schwarz

This post aims to show MediaCore CE operators how to install/manage existing plugins and how to handle plugin upgrades. The post is not about creating new plugins although plugin developers should know about plugin installation.

MediaCore CE provides a lot of functionality out of the box but it is also very extensible by using plugins. A plugin is an add-on component which integrates with MediaCore CE without modifying its source code directly. In other software these components are sometimes called 'add-ons', 'extensions' or 'mods'. The advantage of a plugin over modifying the source code directly is that upgrades of MediaCore CE should be much simpler (because the plugin API is much more stable than the internal structure of MediaCore CE) and it's easier to develop because you have to look only at the (probably small) plugin code.

A plugin can really do a lot of things: Adding some simple fields to an existing form (e.g. view count plugin), integrating an video transcoding service (panda plugin) or adding extra data to existing pages (e.g. SEO plugin). But you can also create completely new pages, extend existing templates, inject custom CSS or JavaScript for a given page, add database tables or react on specific events. A plugin can even disable or replace existing functionality.

Installing Plugins

A plugin usually comes as a tar.gz or .zip file. To install a plugin you should install it in the virtualenv you're using for your MediaCore CE instance. MediaCore CE will load all installed plugins during its startup by default (but you can also choose to only activate some specific in the config file).

Let's take the "Edit Views Plugin" as example (use a shell to install the plugin similar to the actual install of MediaCore CE itself):

# download MediaCore-EditViews-0.9.0b1.zip, extract it and 'cd' into the new
# directory (replace '0.9.0b1' with the current version)
$ wget http://mediacorecommunity.org/releases/plugins/MediaCore-EditViews-0.9.0b1.zip
$ unzip MediaCore-EditViews-0.9.0b1.zip
$ cd MediaCore-EditViews-0.9.0b1

# activate your virtualenv
$ source /path/to/venv/bin/activate

# now let's install it (you can also use 'install' instead of 'develop')
$ python setup.py develop
# DONE

Now you just need to restart MediaCore CE (e.g. by restarting your web server) and the new plugin should be active. In the case of the "Edit Views Plugin" you should now see an extra field in the form when editing a media item via the admin interface.

In the instructions above I used 'python setup.py develop' instead of 'python setup.py install'. The difference is that the former just adds a link to the current source code while 'install' really copies the code into the virtualenv. Personally I prefer 'develop' because I can tweak the code without having to run 'python setup.py install' again each time.

Post-install Tasks

Some plugins may require DB changes. Prior to MediaCore CE 0.11 these were done automatically at startup. Since version 0.11 plugins should not do that anymore. We prefer to make DB changes explicit now so you can deal with potential errors. To start a DB upgrade with MediaCore CE 0.11 please run "paster setup-app /path/to/deployment.ini".

That will run all plugin migration scripts and regenerate your appearance.css. If there are no plugin migrations the command does nothing (besides regenerating appearance.css).

Enable only specific Plugins

By default MediaCore will enable all active plugins but you can also specify (since MediaCore CE 0.10) which plugins should be active (or disable plugins altogether). This is done in your deployment.ini.

In the "[app:main]" section you should see a line

plugins = *

To disable all plugins you can also just write

plugins =

If you want to enable only specific plugins you need to know the plugin id. The id is a short string. For example to enable the SEO plugin and the "Edit Views" plugin you should write:

plugins = editviews, seo

You can find the id the plugin's setup.py file. The important thing is the key for the 'mediacore.plugin' entrypoint.

In the following snippet the plugin id is 'editviews':

entry_points = {
    'mediacore.plugin': ['editviews = mediacore_editviews'],
},

Logging / Debugging

If MediaCore CE fails to load the plugin due to an exception in the plugin code you should see a traceback in your log file/on the console. Usually that's easy to fix because Python will tell you what went wrong.

But sometimes the issue is more subtle and MediaCore CE just starts fine but you can not see any trace of the new plugin. To debug that you should change your log settings in deployment.ini.

Towards the end of your config file there should be a [logger_root] section and you should add this new logger after that section:

[logger_plugins]
level = DEBUG
qualname=mediacore.plugin
handlers = console
propagate=0

You can set the 'handlers' value to (or a combination of) "console", "logfile" or "wsgierrors". Also you need to activate the logger by adding it to the list of loggers in your deployment.ini

[loggers]
keys = root, routes, mediacore, sqlalchemy, auth, plugins

Please note that the list of loggers might be different for you. The only important this is that the 'plugins' logger is in that list.