PluginAPI Ideas

about this page
I was working on StormCatWiki for some time.
The only thing that I had finished was a PluginAPI and a small PlainText filesystem, like DokuWiki.

For some of my projects I'm using DokuWiki and I think it's much better than my wiki. So I thought about migrating my PluginAPI to DokuWiki.

At the moment a fork would be simpler, but I hope with a little help I can add my ideas to the DokuWiki.

Here what the system can do:

• Install Plugins packed in special Packages
• Remove installed Plugins
• Download Updates from a plublic Server

The whole data of the Wiki is writable by the wiki. So eihter chmod 777 or the wiki is owned by the webserver user.
Then there is the following directory tree:

/
  /data            all wiki data
  /conf            all config data
  /sys
    /bin           php files which can be executed by the user
    /lib           php files only for require() and include()
    /i18n          internationalisation files
    /l10n          localisation files
  /themes
    /templates     all templates, each in it's own folder
    /icons         all iconsets, each in it's own folder
  /res             other ressources

Each plugin can create own folders and files but they have to be declared to the plugin handler.
Inside the /sys folder is a package database which handles the plugin installation/deinstallation.

For each installed package the package system saves a filelist, so they can be removed savely.

Important: The package system can't handle dependences and will never be able to.
But it can download updates from internet servers.

This handler is a text file which is included in each plugin installer:

package {
    NAME:                  package-name
    VERSION:               1.0-internal
    AUTHOR:                Armin Ronacher <armin.ronacher@active-4.com>
    MAINTAINER:            Armin Ronacher <armin.ronacher@active-4.com>
}

handle register {
    #a handle call
}

handle setup {
    #a handle call
}

handle remove {
    #a handle call
}

files {
    #each file in a new file
    #if a file doesn't exists in the plugin installer the package
    #system creates a empty one
}

If the installer finds a file called SETUP this content will be shown before the installation.

Each Plugin can do some calls.

CONFIG::register(config-name, config-type)

creates a new configuration file, if there is a configuration file with the same name the handler skips the operation.
config-type specifies the type of the configuration file.
CONFIG_KEYTABLE - like python directory.
CONFIG_ASCIITABLE - ike these used for the smilies…
CONFIG_LINES - each line one value

CONFIG::add_key(config-name, key, value)

adds a new key to a CONFIG_KEYTABLE configuration file.
skips the operation if the key already exits

CONFIG::set_key(config-name, key, value)

like add_key but overwrites a key if already set

CONFIG::add_line(config-name, value [,value ..])

adds a new line to a CONFIG_LINEs configuration file, if more than one value the config-type must be CONFIG_ASCIITABLE

CONFIG::clear(config-name)

drops a configuration file of any type.

SYSTEM::execute(filename)

executes a php file

SYSTEM::delete(filename)

deletes a file

PLUGIN::register(filename, plugin-type, parameter)

registers a file as plugin handler.
plugin-type can be:
PLUGIN_ACTION - plugin reacts to a $_REQUEST[do] command
PLUGIN_PAGE - plugin is set as
PLUGIN_SYNTAX - plugin as parser plugin
PLUGIN_SAVE_HANDLER - executed when a page get saved

PLUGIN::unregister(filename, plugin-type)

unregisters a plugin handler for a file.

  function handle_action_PLUGINNAME(&$ID, &$REV, &$ACT, &$IDX, &$DATE, &$RANGE, &$HIGH, &$QUERY) {}

The plugin must return this array:

array(
   $OUTPUT,
   $AUTH_LEVEL,
   $RETURN_TYPE
)

$RETURN_TYPE can be:

• PLUGIN_OVERALL - inside the template, but not in the context of a wikipage¹⁾
• PLUGIN_INLINE - inside the template, like a normal wiki page
• PLUGIN_PLAIN - no template, $OUTPUT will be printed without header or other things

if the current users level is smaller than $AUTH_LEVEL DokuWiki will display an error message instead of the plugin output. If the plugin returns boolean false instead of an array dokuwiki will stop the execution and display an global error message with a debug output.

Like the current Syntax Plugins.

  function handle_action_PLUGINNAME(&$ID, &$REV, &$ACT, &$IDX, &$DATE, &$RANGE, &$HIGH, &$QUERY, &$NEW_CONTENT) {}

can be used to do notifications over mail, jabber etc.

All configuration files will be loaded once after editing and saved into a cached version.

#!CONFIG_KEYTABLE
# real configuration file
# this is the real file
KEY1:             Value1
KEY2:             Value2

Converted into:

<?php return array('KEY1'=>'Value1','KEY2'=>'Value2'); ?>

#!CONFIG_ASCIITABLE
# configuration file
col1row1          "col2 row1"       col3    col4
col2row1          "col2 row2"       col3    col4

Cached as:

<?php return array(array('col1row1','col2 row1','col3','col4'),array('col2row1','col2 row2','col3','col4')); ?>

and finally

#!CONFIG_LINES
# comment
line1
line 2
line3

cached as:

<?php return array('line1','line 2','line3'); ?>

Plugin install through a special Archive.
The maintainer of a plugin have to create a file inside the dokuwiki root folder with the name “PACKAGE”.
Inside this file he enters the package informations, mentioned above.

A small python script converts the listed files into handily archive.

1. First all files must move into the new folders.
2. Configuration Files (including dokuwiki.php) must converted to the new format
3. Templating splited into template and iconset
4. Templating Engine (like the new one from phpbb3)²⁾
5. Package Manager (frontend needed, maybe included in the new administraor interface)