Plugins¶

A plugin is a Django app with extra Karaage specific features. It can defined extra settings, extra templates, extra URLS, and extra code.

For the purposes of this document, we assume the plugin is called kgplugin, and defines a Django app with a python module called kgplugin. You should change this name.

Settings¶

PLUGINS¶

Default: [] (Empty list)

A list of classes that define Karaage plugins.

Creating a plugin¶

A plugin needs to provide a urls.py file. This file can be empty if it doesn’t provide any urls. It can optionally provide values for urlpatterns and profile_urlpatterns.

A plugin needs to provide a plugin class that is derived from the BasePlugin class. It is configured with the PLUGINS setting.

class karaage.plugins.BasePlugin¶: Base class used for defining Karaage specific settings used to define plugins in Karaaage.

BasePlugin is derived from django.apps.AppConfig if Django 1.7 is detected.

Here is an example, taken from the legacy karaage-usage pugin:

from karaage.plugins import BasePlugin

 class plugin(BasePlugin):
     name = "karaage.plugins.kgusage"
     xmlrpc_methods = (
         ('karaage.plugins.kgusage.xmlrpc.parse_usage', 'parse_usage',),
     )
     settings = {
         'GRAPH_DEBUG': False,
         'GRAPH_DIR': 'kgusage/',
         'GRAPH_TMP': 'kgusage/',
     }
     depends = ("karaage.plugins.kgsoftware.plugin",)

The name value is required, all other attributes are optional.

The following attributes can be set:

BasePlugin.name¶

The python module for the Django app. This will be added to the INSTALLED_APPS Django setting.

If Django 1.7 is detected, the plugin class is added to INSTALLED_APPS, not this value. This setting is used by Django to locate the module.

BasePlugin.django_apps¶: A typle list of extra Django apps that are required for this plugin to work correctly. This will be added to the INSTALLED_APPS setting.

BasePlugin.xmlrpc_methods¶: A tuple list of extra methods to add to the XMLRPC_METHODS setting.

BasePlugin.settings¶: A dictionary of extra settings, and default values. These are added to the Django settings. If the setting is already defined, the value given here is ignored.

BasePlugin.depends¶: A tuple list of plugins this plugin requires to be installed for it to operate correctly.

Templates¶

The python module directory, can contain the templates directory. This can have custom templates under the kgplugin directory. In addition, Karaage will see the following extra files.

kgplugin/index_top.html: contains HTML code to add to the top of the top level Karaage page.
kgplugin/index_bottom.html: contains HTML code to add to the bottom of the top level Karaage page.
kgplugin/main_admin.html: Links to add to the admin menu.
kgplugin/main_profile.html: Links to add to the profile menu.
kgplugin/misc.html: Links to add to the misc menu.
emails/email_footer.txt: Footer to add to every outgoing email.

URLS¶

Extra URLS can be defined in the kgplugin.urls module, and should be called urlpatterns or profile_urlpatterns for URLS that should appear under the profile directory.