Ceci est une ancienne révision du document !
Table des matières
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é, tous les gestionnaires d'événements enregistrés pour cet événement sont appelés chacun leur tour (et sans ordre particulier), et font passer les objets 'événement' par leur 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érieurs de celui-ci. 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 devrait être appelé
action.php
, ou si celui-ci est situé dans le sous-répertoireaction
, il peut être être nommé avec n'importe quel nom (voir Plugin File Structure). - Un plugin d'action est constitué d'une classe unique:
action_plugin_<plugin name>
, qui étend la classe de base DokuWiki_Action_Plugin, située danslib/plugins/action.php
. Si le fichier du plugin d'action est dans le sous-répertoireaction
du dossier du plugin, alors la classe devra êtreaction_plugin_<plugin name>_<action plugin filename>
(où 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 classe de base suprême, DokuWiki_Plugin, située dans
inc/plugin.php
, cf. 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ées au moment où le plugin en a besoin ou alors dans le constructeur, et non pas en début 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 aussi nombreux que nécessaire, peuvent 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 et cela, dans certains cas, indépendamment de 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. Pour en savoir d'avantage sur les événements, consulter les pages suivantes:
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 pour 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
Inserer un bouton dans la barre d'outils 'éditeur';
- Enregistrer tel un gestionaire pour l' TOOLBAR_DEFINE évenement avec un 'AFTER advise'
- Ajouter une définition de bouton au
data
de l'évenement.
<?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>', ); } }
vois aussi plugin_programming_tips