Introduction
************

Plugins are central to KForge and the main way it can be extended. This document introduces you to the KForge plugin system and explains how to write your own plugins.

System Design
*************

Please take a look at the (ascii) UML diagram in plugin_system_diagram.txt (in this directory).

Domain objects: the central part of the KForge system is the domain model (see system_overview.txt). In relation to plugins the domain model has a Plugin object and a Service object (instances of Plugins associated with a project, for example a subversion instance). The relationships here are illustrated in the above diagram. The domain object plugin object is simply a representation for the system of the actual plugin package.

The actual plugin, which we term, the **system** Plugin (to differentiate from the domain object plugin) is the main object a plugin developer must create. The details of how to do this is the subject of the next section.

When a plugin is installed a corresponding instance of a domain object Plugin is created for the system Plugin. This one to one correspondence is how the KForge core (which uses the Dom) can interfaces with plugins (via a PluginController).

Domain Object          Plugin System
(kforge.dom)           kforge.plugin

   Plugin <>---------<> PluginBase

Plugin Development
******************

The main way the plugin gets to do things is:
  1. A plugin is notified of **events**
  2. A plugin may insert configuration into apache

You create a plugin by inheriting from kforge.plugin.PluginBase and then overriding methods. The best way to understand how this works and how to use it is:
  1. Read documentation of methods on kforge.plugin.PluginBase to understand what you can override
  2. Look at an existing plugin, many of which already exist in the kforge/plugin/ directory.

The Simplest Possible Plugin
============================

import kforge.plugin

class Plugin(kforge.plugin.PluginBase):
  """
  Class must be called Plugin
  """
  pass

Well obviously this isn't very exciting because it does *literally* nothing but it will work.

The Example Plugin
==================

The Example plugin is still very simple but it at least does something: it acts on an event. Rather than go through the plugin take a look at the code which is heavily documented.

More Complex Plugins
====================

TODO


Plugin Packaging
****************

If the plugin is a single python module it may be named::

    <plugin_name>.py

Otherwise it must come as a python package (in which case it can also include the above mentioned files).

A plugin should provide full documentation regarding installation (including any required external packages) in its main docstring.


Plugin Installation and Removal
*******************************

Please see the KForge Guide.
