diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/Howto_Write_Plugins | 73 |
1 files changed, 16 insertions, 57 deletions
diff --git a/doc/Howto_Write_Plugins b/doc/Howto_Write_Plugins index 6f58de5..bb63120 100644 --- a/doc/Howto_Write_Plugins +++ b/doc/Howto_Write_Plugins @@ -1,67 +1,26 @@ HowTo Write A Plugin For Portato ================================= -(NOTE: The XML schema is likely to change in the future.) +Writing plugins for Portato is quite easy: (Nearly) all you have to do is to write a plain Python module :). -Writing a plugin is (quite) simple. You have to provide a XML file which tells portato how to communicate with the plugin and in most cases a Python module doing the actual work. This howto is not going to cover the writing of the plugin, but only the XML. +A plugin has two more builtins than a normal Python module: -General -------- + ``Plugin`` + This is a class representing a plugin. -So - how is a plugin is working in general? Portato defines a set of hooks (see the Hooks file for a complete list) to which your plugin can connect. For each hook you have three choices: To connect before, after or instead of the function being hooked. (Of course you can connect several times to one hook ...) The latter one should be used only if you really know what you are doing as it is likely that Portato won't work any longer after this. Also have in mind, that only one plugin can override. Thus: if several plugins want to override one hook, a randomly chosen one will get the allowance. + ``register`` + A function which you have to call to get the your plugin added to Portato. -For each of the "before" and "after" mode a queue exists, holding the plugins to execute. A plugin is allowed to state another plugin which should be executed after (in "before" mode) or before (in "after" mode) your plugin. The star * exists to note that this should be applied to ALL other plugins. (And "-*" does exactly the opposite.) Portato TRIES to satisfy your request... +In this module you need to have at least one class, which inherits from ``Plugin``. This class does all the handling you want your plugin to do. If you want, you can implement more classes - from Portato's view they are handled as different plugins. Thus: It is not the module hierarchy, but the classes that count. +Add the end you only call ``register`` once for each class and are done :). -When you now have chosen the connect(s) to chose you write an appropriate function (or better: a Python callable) which will be given in the XML-definition to be called by Portato with the hook's arguments. (Hint: All arguments will be passed as keyword parameters. So you can easily pick the ones you need and add a "**kwargs" argument, which will take the rest. As a nice side effect you do not have to reflect any API changes which will come with additional parameters :)). +Of course there are some things you should bare in mind: + + 1. Do not use the ``__init__`` method, but ``init``. + 2. Do not use a member which shadows one from the original class: + ``description``, ``author``, ``status``, ``menus``, ``name``, ``calls``, ``deps``, ``enabled``, ``add_menu``, ``add_call`` + 3. Of course you can *use* the members mentioned under point 2. -Finally: Add an import tag stating the module to import to execute the function(s) given - and you are done. +For the details, please see the source code at the moment or write your question to portato@necoro.net -If you are finished with your plugin, you can check if it complies with the XML Schema by doing: "portato -x $PLUGIN_FILE". - -Sample XML ----------- - -<?xml version="1.0" encoding="UTF-8" ?> -<plugin xmlns="http://portato.sourceforge.net/plugin" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://portato.sourceforge.net/plugin http://portato.sourceforge.net/plugin.xsd"> - <author>Joe Smith</author> - <name>Some small sample plugin</name> - - <import>plugins.sample.small</import> - - <hooks> - <hook type = "a_hook" call = "the_calling_function"> - <connect type="after" /> - </hook - </hooks> - - <options> - <option>disabled</option> - </options -</plugin> - -Notes: - -- If you want to specify a dependency plugin the connect tag has to be like: <connect type = "after"> The other plugin we depend on </connect>. -- The "connect"-tag can be omitted. It then defaults to "<connect type='before' />". -- It is possible of course to have more than one "hook" tag. -- The options tag is optional. For a complete list of options, see below. - -Additional Tags ---------------- - -Menu: - It is possible, that your plugin gets an entry in the "Plugin"-menu. Therefore you have to provide a "menu" tag and one or more "item" tags: - - <menu> - <item call = "the_calling_menu_function"> - A small _Plugin - </item> - </menu> - - Note, that the underscore in front of a character will make it be underlined in the menu and thus accessible by a shortcut. - -Options --------- - -disabled: - Disable the plugin by default, i.e. the user has to enable it, if he wants to use it. +.. vim: ft=rst |