Content-Type: text/x-zim-wiki
Wiki-Format: zim 0.4
Creation-Date: Wed, 24 Jun 2009 23:42:30 +0200

====== Writing plugins ======
This page collects random notes on writing plugins.

**NOTE:** Under the GPL license used for distributing this program all plugins should also be licensed under the GPL. A closed source plugin extension is not allowed. A plugin is allowed to call any non-GPL program as long as the plugin itself is under GPL and the non-GPL program runs as a separate process with a clearly defined inter process communication interface.

===== Writing a new plugin =====
See the module documentation in ''zim.plugins'' for documentation of the plugin framework.

===== How to package =====
Plugins are simply sub-modules of the "zim.plugins" python package. So installing your plugin module in the same folder as the zim modules would do the trick to have zim find the plugin.

However to make it easier to install local plugins, also the ''$XDG_DATA_HOME/zim/plugins'' folder and all ''$XDG_DATA_DIRS/zim/plugins'' are add to the search path. By default the home folder would be ''~/.local/share/zim/plugins''.

The best for packaging is then is to organize your plugin as a folder with a "''__init__.py''" containing the main plugin class. Users can then directly unpack this folder to "''~/.local/share/zim/plugins''" or directly branch your github or bazaar branch to this location.

===== Manual page =====
Each plugin should have it's own page in the user manual that explains what it does and how to use it. Please write it before proposing your plugin to be included in the main package.

===== Unit testing =====
As stated in the guidelines [[Test Suite|unittesting]] is good. Please try to write some test cases for your plugin before proposing it to be included in the main package. Other developers may not use your plugin, so if it breaks later on it may go undetected unless there is a test case for it.
