====== 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 = Foo::Bar->new();
	$app->add_object(FooBar => $object);

or you can have it autoloaded when needed like this:

	$app->add_object(FooBar => 'Foo::Bar');

or like this :

	$app->add_object(FooBar => sub { return Foo::Bar->new(@args) });

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

	$app->FooBar()

You can get references to the other objects that make up the application in a similar way.

==== Menu Items ====
**Zim** uses ''Gtk2::UIManager'' to load the content of the menubar and toolbar. See the "ui" and "action" functions in [[:man:Zim::GUI::Component|Zim::GUI::Component]].

Any custom icons you need should be put in ''XDG_DATA_DIR/pixmaps/zim/'', they will be loaded automatically. You can use the basename if the icon file as the stock name for an action.
