====== Plugins ======

See also [[:zim:usage:plugins]]

**Zim** has a simple plugin system to add extended functionality. Plugins are just perl scripts that are installed in a directory where **zim** can find them. If the user chooses to use the plugin the script is loaded during program initialization.

At the moment there is not yet a real plugin API, so plugins need to work directly with the internal structures of the program. This means that plugins often need to be updated for newer versions of **zim**.

==== Locations ====
Plugin scripts are looked for in ''XDG_DATA_DIR/zim/plugins/'' this means that by default they will be located in ''/usr/share/zim/plugins'' or ''/usr/local/zim/plugins''. Users can install their own plugins in ''~/.local/share/zim/plugins''.

For more information on this directory scheme have a look at the freedesktop [[http://freedesktop.org/wiki/Standards_2fbasedir_2dspec|basedir specification]].

==== API ====
See [[class diagram]] for a description of zim's object structure.

To get a reference to the main application object in your script use:

	my $app = Zim::GUI->current();

To add an object for your plugin you can either load it directly from your plugin script like this:

	my $object = FooBar->new();
	$app->{objects}{FooBar} = $object;

or you can have it autoloaded when needed like this:

	$app->{autoload}{FooBar} = 'FooBar';

When autoloaded the "new()" method is called on the given class with as argument a hash with a reference to the main application object.

In both cases you can get a reference to the object by calling

	$app->FooBar

The ''$app->{autoload}'' hash can also contain code references, which will be considered constructors for the object in question.
