activeXML Plugin System

The range of plugins available in activeXML can be extended with plugins. These can be installed by the user, and loaded and used by a script. It is recommended that platform specific actions, such as registry access, be placed in functions.

Installing plugins

A list of directories containing plugins is loaded from the configuration files on start. Each plugin must be installed as a .py file in one of these directories. The name must be made up only of characters a-z (not A-Z), and _. While other characters may not cause problems, it is recommended that they are avoided. Besides this, the filename doesn't matter, as the name is loaded from within the plugin.

Using Plugins from a script

To use a plugin, it must first be loaded with:

<plugin name="pluginname"/>

Then, all actions contained within the plugin will be loaded in the form "pluginname.actionname". This means that actions can be called normally:

<action type="pluginname.actionname">
    [parameters here]
</action>

This example script loads the "fileprint" plugin, which contains the "go" action. This action is then called, with the path to a file as its first parameter.

<?xml version="1.0"?>
<activexml name="fileprint_plugin" version="1.0" app="Vim" author="drigz"
        security="3">
    <description> simple example application to test the test 'fileprint' plugin</description>
    <plugin name="fileprint"/>

    <action type="fileprint.go">
        <parameter index="1" type="literal" value="C:\testfile"/>
    </action>
</activexml>

Writing plugins

From hereon, it is assumed that you have a basic knowledge of Python, as this is the language used to write plugins.
Each plugin must contain two variables; 'name' and 'map'. 'name' must be a string containing the name of the plugin ([a-z_]+). 'map' must be a dictionary, where each entry has the action name ([a-z_]+) as the key, and another dictionary as the value. This second dictionary should have three key, value pairs:

Key	Value
fn	The function which corresponds to this action
sl	An integer, [1-5], which gives the security level of the action
np	An integer, which contains the number of parameters that the action accepts.

The plugin will also contain a number of functions. It is recommended that these are named in the format 'action_actionname', although this not required. Each function should take a list of values as its first and only argument. pars[0] contains the running output, and pars[n] contains the parameter with index n. The function should return the (possibly modified) list of parameters.

This example plugin, called 'fileprint', contains one action, 'go', with a security level of 3, and which takes 1 parameter (the name of the file to print). Note that here, print means print to stdout, as opposed to a printer device.

def action_go(pars):
    pars[0] = None
    try:
        f = open(pars[1])
    except IOError:
        print "Failed to open file"
        return
    print f.read()
    f.close()
    return pars

name = "fileprint"
map = {
"go": {"fn": action_go, "sl": 3, "np": 1}
}