This is an old revision of the document!
Table of Contents
Event System
The event system allows custom handling in addition to or instead of the standard processing for any part of DokuWiki which signals its activity via the event system. The custom handlers, or hooks, can be included in any plugin or template script (or even in DokuWiki itself). Action Plugins are specifically designed to take advantage of the events system. They are guaranteed to be loaded at the start of processing and to have an opportunity to register for events before any events have taken place. Other parts of DokuWiki may not be executed immediately or at all for any given page and execution pathway.
It is also possible for custom DokuWiki content to create and signal events of their own.
The event system consists of three parts
- the event object.
- the main event handler or controller. This is a DokuWiki global,
$EVENT_HANDLER
. Scripts that wish to receive an event need to register their interest with this object. When an event is signalled it will cycle through all the registered hooks (or event handlers) passing them the event in turn. - 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.
Event Object
class name Doku_Event
An event object consists of:
- PUBLIC properties
name
, (READONLY) hooks must use this to register to process a particular eventdata
, (READ/WRITE) data pertaining to the event, hooks have an opportunity to inspect and modify thisresult
, (READ/WRITE) available after the default action has taken place to hooks that have registered for theafter
advise.canPreventDefault
, (READONLY) informs a hook whether or not the default action can be prevented
- PRIVATE properties
_default
(bool, inital valuetrue
), whether or not the default action associated with the event should be carried out. Interact with this property via thepreventDefault()
method._continue
(bool, initial valuetrue
), whether or not to continue sending the event to registered hooks that have yet to receive it. Interact with this property via thestopPropagation()
method.
- PUBLIC methods
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 placepreventDefault()
- 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.
Registering to Receive an Event
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
. As of 2006-04-26 the declaration is
/** * register_hook * * register a hook for an event * * @param string $event name used by the event * @param string $advise ''BEFORE'' or ''AFTER'', the advise the hook wished to receive * @param obj $obj object in whose scope method is to be executed, * if NULL, method is assumed to be a globally available function * @param function $method event handler function * @param mixed $param (optional) data to be passed to the event handler */ function register_hook($event, $advise, $obj, $method, $param)
Signalling an Event
An event can be signalled in three ways.
- 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.
/** * trigger_event * * function wrapper to process (create, trigger and destroy) an event * * @param string $name name for the event * @param mixed $data event data * @param callback $action (optional, default=null) default action, a php callback function * @param bool $canPreventDefault (optional, default=true) can hooks prevent the default action * * @return mixed the event results 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 handler hooks */ function trigger_event($name, &$data, $action=null, $canPreventDefault=true)
- managing the whole event signalling process. 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);
Examples
(these are examples only and may not exist in DokuWiki)
On Wiki page save
// 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
Additional/Replacement do
actions
// 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.
On handler instruction list completion
// 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