Defining a Plugin

The latest documentation can be found on the Project Wiki. The information below may be out of date.

User-defined plugins go in modules/plugins2.0. To get started, make a new directory there. This will contain your plugin. Inside that directory create a new PHP file to define your plugin. This definition tells Fannie a little information about your plugin. To do so, it needs to define a class extending FanniePlugin like this:

include_once(dirname(__FILE__).'/../../../config.php');

This line includes Fannie's global configuration file. It's almost always a good idea to do this first so all user-defined settings are accessible. Note that the path does not assume Fannie is in a particular directory like /var/www. This is important for compatibility with various systems. Using "dirname(__FILE__)" is preferred over using "__DIR__" since the latter is only available in relatively new versions of PHP.

if (!class_exists('FanniePlugin')) include($FANNIE_ROOT.'classlib2.0/FanniePlugin.php');

This line includes the definition for the base class FanniePlugin. The variable $FANNIE_ROOT is provided by Fannie's global configuration file. It points to the directory containing Fannie and can be used to reference paths without using lots of "../" strings.

class CalendarPlugin extends FanniePlugin {
}

Finally, define the plugin class. The name of the subclass should match the name of the PHP file. So, for example, in this case the file should be named CalendarPlugin.php. As a best practice, this applies to any PHP file that defines a class.

Further Options

At this point, the plugin definition is technically complete. Possible additions include:

A description of your plugin is generally a good idea.

public $plugin_description = 'Plugin for calendars';

If your plugin has any user-configurable settings, you can define them in the settings array. Each setting needs a name, default value, description, and label. Settings will be saved in the global configuration variable $FANNIE_PLUGIN_SETTINGS via the name key. An example setting like this:
```
public $plugin_settings = array(
'CalendarDatabase' => array('default'=>'core_calendar','label'=>'Database',
		'description'=>'Database to calendars. Can
				be one of the default CORE databases or a 
				separate one.')
);
```
would be saved as $FANNIE_PLUGIN_SETTINGS['CalendarDatabase'].
Define triggers. The FanniePlugin class includes methods named plugin_enable(), plugin_disable(), and setting_change(). These are called when the plugin is enabled, disabled, or its settings are updated (respectively).