Action Plugins

Les Action Plugins sont conçus de manière à travailler avec les events, afin de permettre la personnalisation ou l'extension de chaque partie de Dokuwiki signalant son activité par les événements.

Description

Les Plugins d'action sont chargés avant tout traitement de processus Dokuwiki. Suite à ce chargement, chaque plugin est appelé par sa méthode register(), pour lui permettre d'enregistrer chacun des gestionnaires d'événements ('event handlers'). Quand un des événements est signalé, tout les gestionnaire d'événements enregistrés pour cet événements sont appelés à leur tour (et sans ordre particulier), et font passer les objets 'événement' par leurs référence. Le gestionnaire a la possibilité d'exécuter des actions basées sur les données de l'événement, et de modifier soit les données de l'événement, soit les processus ultérieures de l'événement. Pour plus de détails concernant le fonctionnement du système et la liste des événements, veuillez vous référer à la page events.

Technique

Les Plugins d'actions suivent le même basic format and naming convention que les autres plugins Dokuwiki :

Chaque plugin est localisé dans son propre répertoire, dans lib/plugins.
Un plugin d'action (action.php) devrait être appelé , ou si celui-ci est localisé dans le sous répertoire action, il peut être appelé autrement (voir Plugin File Structure).
Un plugin d'action constitue une classe unique: action_plugin_<plugin name>, qui étend la base de classe DokuWiki_Action_Plugin, situé dans lib/plugins/action.php. Si le fichier du plugin d'action est dans le sous-répertoire action du dossier du plugin, alors la classe devra être action_plugin_<plugin name>_<action plugin filename> (ou les noms de fichier du plugin d'action n'incluent pas l'extension '.php').
Le plugin est fourni avec une introspection standard, une localisation et des fonctions de configuration via la dernière base de classes, DokuWiki_Plugin, située dans inc/plugin.php, voir Common Plugin Functions.
Le plugin doit déclarer une méthode register(), et certains gestionnaires qui y sont enregistrés.
les librairies externes doivent être chargés au moment où le plugin en a besoin ou dans le constructeur, et non pas en haut du fichier.

register()

requis

    /**
     * plugin should use this method to register its handlers with the DokuWiki's event controller
     *
     * @param    $controller   DokuWiki's event controller object. Also available as global $EVENT_HANDLER
     *
     * @return   not required
     */
    function register(&$controller) {
      $controller->register_hook(<EVENT NAME>, <EVENT ADVISE>, $this, <event handler function>, <parameters to be passed to event handler>);
    }

<event handler>()

optionnel ont autant que nécessaire, peut avoir n'importe quel nom du moment que celui-ci n'est pas déjà utilisé dans ce plugin ou dans une classe ancêtre.

    /**
     * custom event handler
     *
     * @param    $param   (mixed)   the parameters passed to register_hook when this handler was registered
     * @param    $event   (object)  event object by reference
     *
     * @return   not required
     */
    function <event_handler>(&$event, $param) {
      // custom script statements ...
    }

Exemple

les plugins d'action sont un moyen de modifier plusieurs aspects du comportement de Dokuwiki dans certains cas, indépendamment à la syntaxe de la page. Pour pouvoir modifier un comportement interne de Dokuwiki, il faut un déclenchement d'événement. Votre plugin d'action peut inscrire ce gestionnaire tel un événement et travailler avec les donnés données par cet événement. To learn more about events, read the following pages:

Sample Action Plugin 1

Inserer un lien Java Script dans toutes les pages

Enregistrer l'TPL_METAHEADER_OUTPUT évenement, avec un 'before EVENT_ADVISE'.
Ajouter des informations Java Script à un “script” meta headers comme à un type array .

action.php

<?php
/**
 * Example Action Plugin:   Example Component.
 *
 * @author     Samuele Tognini <samuele@cli.di.unipi.it>
 */
 
if(!defined('DOKU_INC')) die();
if(!defined('DOKU_PLUGIN')) define('DOKU_PLUGIN',DOKU_INC.'lib/plugins/');
require_once DOKU_PLUGIN.'action.php';
 
class action_plugin_example extends DokuWiki_Action_Plugin {
 
    /**
     * Register its handlers with the DokuWiki's event controller
     */
    function register(&$controller) {
        $controller->register_hook('TPL_METAHEADER_OUTPUT', 'BEFORE', $this,
                                   '_hookjs');
    }
 
    /**
     * Hook js script into page headers.
     *
     * @author Samuele Tognini <samuele@cli.di.unipi.it>
     */
    function _hookjs(&$event, $param) {
        $event->data['script'][] = array(
                            'type'    => 'text/javascript',
                            'charset' => 'utf-8',
                            '_data'   => '',
                            'src'     => DOKU_PLUGIN.'example/example.js');
    }
}

Sample Action Plugin 2

Inserts a button into the editor toolbar:

registers as handler for the TOOLBAR_DEFINE event with an AFTER advise
adds a button definition to the event's data

<?php
/**
 * Example Action Plugin: Inserts a button into the toolbar
 *
 * @author Gina Haeussge <osd@foosel.net>
 */
 
if (!defined('DOKU_INC')) die();
if (!defined('DOKU_PLUGIN')) define('DOKU_PLUGIN', DOKU_INC . 'lib/plugins/');
require_once (DOKU_PLUGIN . 'action.php');
 
class action_plugin_actionexample extends DokuWiki_Action_Plugin {
 
    /**
     * Register the eventhandlers
     */
    function register(&$controller) {
        $controller->register_hook('TOOLBAR_DEFINE', 'AFTER', $this, 'insert_button', array ());
    }
 
    /**
     * Inserts the toolbar button
     */
    function insert_button(& $event, $param) {
        $event->data[] = array (
            'type' => 'format',
            'title' => $this->getLang('qb_abutton'),
            'icon' => '../../plugins/actionexample/abutton.png',
            'open' => '<abutton>',
            'close' => '</abutton>',
        );
    }
 
}