Plugin Howto

Introduction

A plugin allow one to create new functionalities for Wiclear without hacking inside the main engine.

A plugin can :

Currently, a plugin cannot add/modify controls in existing forms, but hey I guess we can do it !

Anatomy of a plugin

A plugin has a public part and an admin part.

Public part

The public part goes into /tools

The public part must contain at least the following files :

The public part may also contain an i18n directory to provide translations to its internal strings.

Basically, the public part is what is seen by users and what is available to template makers.

Wiclear, with the PluginManager will load hooks.inc.php, so all template callable functions should be put here.

You should also put hooks into PluginManager to tell it to which page you will react.

For example, let's look at the trackback plugin. Here are the first lines of the plugin :

 $> cat tools/trackback/hooks.inc.php

 global $pluginManager;
 $pluginManager->addContentBoxHandle("trackback_add_ping",       "addPing");
 $pluginManager->addUserActionHandle("trackback_discover",       "onTrackbackDiscover");
 $pluginManager->addUserActionHandle("trackback_do_ping",        "onTrackbackPing");
 $pluginManager->addUserActionHandle("trackback_del",            "onTrackbackDelete");
 $pluginManager->addBrowserTitlePageHandle("trackback_add_ping", "browserAddTrackback");
 $pluginManager->addPluginACL(acl_plugin_start, "Trackback");
 

The plugin has added one hook to the global content area. Each time the mode "trackback_add_ping" will be handled, wiclear will call back the method "addPing".

The plugin has added several hooks to the "userActionHandle" which roles is to react to user submission *before* starting to display something.

In our cases, when mode trackback_discover, trackback_do_ping, or trackback_del will be handled, the PluginManager will call back given onTracback* functions.

We also have added one hook to the browserTitlePageHandle hook to be able to customize browser's title in mode trackback_add_ping

Finally, we have added a new acl type. For that we reserve value acl_plugin_start, and we give a string id. The core of wiclear will integrate this new value so that admin/moderators can set this new acl. All we have to do in the plugin is to check wether this acl is set before modifying our data.

In the same file, we see several functions that can be called in user's template :


The rest of the plugin is located into the index.php file that will be loaded only when :

The second case allow one to display complex control (see wiki_blog plugin for example)

A user may also force the PluginManager to load only i18n strings by calling $pluginManager->loadI18N('trackback').

Of course, you're free to create more files and include them as needed in index.php

It is also possible to add callback from Wiclear core forms.

 $pluginManager->addPluginCallback("simpleToolbarCallback");
 

For this to work, the forms must add a call to pluginManager to allow a plugin to intercept the call. For now, only the edition form has a hook.

We must define a new method named "simpleToolbarCallback" that has this signature :

 function simpleToolbarCallback($where, &$extra) {}
 

This callback will receive all callback from all form, it will then have to filter which callback he wants. For example, the edition form send the string : "content_edit_form"

The extra argument is the Form object that has been filled by the edition form. You can do what you want with it

You can also add a callback to integrate into the validation of Wiclear core form.

 $pluginManager->addOnPluginCallback("onMyFormEdit")
 

The idea is the same, you will have to provide a callback called onMyFormEdit having signature :

 function onMyFormEdit($where) {}
 

This will allow you to react on user submitting a core form. It is up to you to properly decode GET/POST/COOKIE/SESSION whatever variables you want to perform your action.

Admin part

The admin part goes into /admin/tools

The admin part must contain at least one file : index.php

If the plugin does not have a public section it must contain a desc.conf file.

The admin part is incorporated into the "Tools" section of the admin panel and can be executed there.

For this to work, the special file desc.conf must be found. It will be looked first in public part and if not found in admin part.

This file is a metadata file describing the plugin and easying its incorporation into the admin panel.

Here are the syntax and the mandatory part of such a file.

The file is a text file having the same syntax as translations files : it is organized in blocks of 3 lines following each other.

example :

 $>cat tools/trackback/desc.conf

 [Name]
 Trackbacks

 [Author]
 David Jobet

 [Description]
 A tool to handle trackbacks

 [Icon]
 icon.png

 

Those 4 keys are mandatory :

It is also possible to have an i18N dir into your admin part to translate your plugin in the admin panel as well


Generated on Mon Feb 19 19:11:58 2007 for Wiclear by  doxygen 1.4.7