Traduction en cours

Le système d'évènement permet une gestion personnalisée en plus ou à la place du fonctionnement standard de n'importe quel partie du moteur Dokuwiki qui signale son action par ce système d'évènement. Les gestionnaires personnalisés handlers, aussi appelés “hooks”, peuvent être utilisés dans n'importe quel plugin ou script de template (ou même dans Dokuwiki lui-même). Les plugins d'Action sont spécifiquement prévus pour traiter les événements. Ils sont assurés d'être chargés au début de l’exécution et ont ainsi la possibilité de s'enregistrer avant qu'aucun événement ne soit généré. Other parts of DokuWiki may not be executed immediately or at all for any given page and execution pathway.

Il est également permis à du contenu personnalisé de Dokuwiki de créé et généré un signal d'évènement le concernant.

Le système d'évènement est composé de trois parties

• L'Objet d'évènement.
• the main event handler or controller. This is a DokuWiki global, $EVENT_HANDLER. Les scripts qui souhaitent recevoir le signal d'un évènement doivent enregistrer leur intéret pour ce dernier. Lorsqu'un événement envoi son signal, les hooks (ou gestionnaires d'évènements) enregistrés sont exécutés les uns après les autres et reçoivent en paramètre l’évènement concerné.
• individual event handlers or hooks. These are functions that wish to receive a particular event. The Action Plugin is a vehicle specifically for these functions, however they can also be part of templates, plugins of other types or the main DokuWiki scripts.

Detailed information describing existing events and when they occur is provided in the events list.

Nom de la classe : Doku_Event

Un Objet d'évènement est constitué de :

• Propriétés publiques
  • name, (lecture seule) hooks must use this to register to process a particular event
  • data, (lecture/écriture) data pertaining to the event, hooks have an opportunity to inspect and modify this
  • result, (lecture/écriture) available after the default action has taken place to hooks that have registered for the after advise.
  • canPreventDefault, (lecture seule) informs a hook whether or not the default action can be prevented

• Propriétés privées
  • _default (booléen, initiée à true), whether or not the default action associated with the event should be carried out. Interact with this property via the preventDefault() method.
  • _continue (booléen, initiée à true), whether or not to continue sending the event to registered hooks that have yet to receive it. Interact with this property via the stopPropagation() method.

• Méthodes publiques
  • trigger() - automated signalling of events. This method accepts two optional parameters, the default action (callback), and whether or not it may be prevented (bool) and returns the results of the event. It looks after the whole event process, signalling the “_BEFORE” advise, triggering the default action and signalling the “_AFTER” advise.
  • stopPropagation() - stop any further processing of the event by event handlers this function does not prevent the default action taking place
  • preventDefault() - prevent the default action taking place
• advise_*() methods - for use when the signalling script wishes to handle the complete event signalling process (perhaps when functionalising a default action is not appropriate).
  • advise_before() - accepts one parameter, a boolean indicating whether the default action can be prevented, issues the “_BEFORE” signal.
  • advise_after() - issues the “_AFTER” signal.

To register a hook to receive an event, call the register_hook() method of the $EVENT_HANDLER. Action plugins can do this using the $controller parameter from within their own register() method. Other parts of DokuWiki should ensure they are either in global scope or declare $EVENT_HANDLER as a global. e.g.

global $EVENT_HANDLER;
$EVENT_HANDLER->register_hook( ... )

For up-to-date details of the register_hook() function and its parameters refer to its declaration in inc/events.php.

Use register_hook($event, $advise, $obj, $method, $param=null, $seq=0) with the arguments:

• $event string, name used by the event
• $advise string, BEFORE or AFTER, the advise the hook wished to receive
• $obj object, object in whose scope method is to be executed. If null the method is assumed to be a globally available function
• $method function, event handler function. More info at the Event handlers page.
• $param mixed (optional), the data to be passed to the event handler. Default null.
• $seq int (optional), [develonly] sequence number used to control the order in which hooks are executed. Hooks are executed in ascending $seq order. If two or more hooks have the same $seq value, their order (relative to each other) is undefined. Hooks can use -PHP_INT_MAX or PHP_INT_MAX, in an attempt to be first or last. Be aware that these values provide no guarantee of being first/last as more than one plugin can use them.

An event can be signalled in three ways.

1. The simplest is to use the function wrapper trigger_event(). This function takes all the parameters necessary to create an event object and trigger it.
   Use trigger_event($name, &$data, $action=null, $canPreventDefault=true) with the arguments:
   • $name string, name for the event
   • $data mixed, event data
   • $action callback (optional), default action given as php callback function. Default null.
   • $canPreventDefault boolean (optional), can hooks prevent the default action. Default true.
   • return mixed, the event result value after all event processing is complete. By default this is the return value of the default action. However it can be set or modified by event handlers hooks as it is stored in result attribute of the Doku_Event object, where the Doku_Event is available in handlers.

     trigger_event(<EVENT_NAME>, <event data>, 
                   <action callback>, <can prevent default>) 

2. using the trigger() method. This isn't recommended as it is better to use the trigger_event() function wrapper described above.

   $evt = new Doku_Event(<EVENT_NAME>,<event_data>);
   $evt->trigger(<default action>,<can prevent default>);
   unset($evt);

3. managing the whole event signalling process with advise_before($enablePreventDefault = true) and advise_after() on the Doku_Event object. Use this method when there is a default action but it not possible to package it as a PHP callback function.

   $evt = new Doku_Event(<EVENT_NAME>, <event data>);
   if ($evt->advise_before(<can prevent default>)) {
     // default action code block
   }
   $evt->advise_after();
   unset($evt);

(These are examples only and may not exist in DokuWiki.)

// event:  'IO_WIKIPAGE_SAVE'
// data:   array(file name, the raw wiki page)
// action: save the raw wiki page to file name
// return: bool, page saved
$data = array($id,$wikitext);
$ok = trigger_event('SAVE_WIKIPAGE', $data, io_savewikipage);

Possible handlers, indexers, translators.

// events:  'ACTION_ACT_PREPROCESS' & 'TPL_ACT_UNKNOWN'
// data:    $ACT  (value of the ''do'' query string variable)
// action:  none, handled by signalling script
 
// in ''inc/actions.php act_dispatch()''
$evt = new Doku_Event('ACTION_ACT_PREPROCESS', $ACT);  
if ($evt->advise_before()) { 
    /* process $ACT normally */ 
}
$evt->advise_after();
unset($evt);
 
// in ''inc/template.php tpl_content()''
default: /* unrecognised $ACT value */
$evt = new Doku_Event('TPL_ACT_UNKNOWN', $ACT);
if ($evt->advise_before()) { 
    print "unknown action"; 
}
$evt->advise_after();
unset($evt);

Possible handlers, customer form processing, additional do commands from template UI.

  // event:  ''PARSER_HANDLER_DONE''
  // data:   the handler, including the completed instruction list
  // action: none
 
  // in ''inc/parser/handler.php  _finalize()
  trigger_event('PARSER_HANDLER_DONE',$this);

possible handlers, footnote replacement plugins, enhanced TOC handlers

• Events List with existing events.
• Use Action plugins to register handlers on events.
• More about Event handlers
• Examples of event handlers code