diff options
Diffstat (limited to 'plugins/dokuwiki/inc/events.php')
| -rw-r--r-- | plugins/dokuwiki/inc/events.php | 202 |
1 files changed, 202 insertions, 0 deletions
diff --git a/plugins/dokuwiki/inc/events.php b/plugins/dokuwiki/inc/events.php new file mode 100644 index 0000000..1231f4c --- /dev/null +++ b/plugins/dokuwiki/inc/events.php @@ -0,0 +1,202 @@ +<?php +/** + * DokuWiki Events + * + * @license GPL 2 (http://www.gnu.org/licenses/gpl.html) + * @author Christopher Smith <chris@jalakai.co.uk> + */ + +if(!defined('DOKU_INC')) define('DOKU_INC',realpath(dirname(__FILE__).'/../').'/'); +require_once(DOKU_INC.'inc/pluginutils.php'); + +class Doku_Event { + + // public properties + var $name = ''; // READONLY event name, objects must register against this name to see the event + var $data = NULL; // READWRITE data relevant to the event, no standardised format (YET!) + var $result = NULL; // READWRITE the results of the event action, only relevant in "_AFTER" advise + // event handlers may modify this if they are preventing the default action + // to provide the after event handlers with event results + var $canPreventDefault = true; // READONLY if true, event handlers can prevent the events default action + + // private properties, event handlers can effect these through the provided methods + var $_default = true; // whether or not to carry out the default action associated with the event + var $_continue = true; // whether or not to continue propagating the event to other handlers + + /** + * event constructor + */ + function __construct($name, &$data) { + + $this->name = $name; + $this->data =& $data; + + } + + /** + * advise functions + * + * advise all registered handlers of this event + * + * if these methods are used by functions outside of this object, they must + * properly handle correct processing of any default action and issue an + * advise_after() signal. e.g. + * $evt = new Doku_Event(name, data); + * if ($evt->advise_before(canPreventDefault) { + * // default action code block + * } + * $evt->advise_after(); + * unset($evt); + * + * @return results of processing the event, usually $this->_default + */ + function advise_before($enablePreventDefault=true) { + global $EVENT_HANDLER; + + $this->canPreventDefault = $enablePreventDefault; + $EVENT_HANDLER->process_event($this,'BEFORE'); + + return (!$enablePreventDefault || $this->_default); + } + + function advise_after() { + global $EVENT_HANDLER; + + $this->_continue = true; + $EVENT_HANDLER->process_event($this,'AFTER'); + } + + /** + * trigger + * + * - advise all registered (<event>_BEFORE) handlers that this event is about to take place + * - carry out the default action using $this->data based on $enablePrevent and + * $this->_default, all of which may have been modified by the event handlers. + * - advise all registered (<event>_AFTER) handlers that the event has taken place + * + * @return $event->results + * the value set by any <event>_before or <event> handlers if the default action is prevented + * or the results of the default action (as modified by <event>_after handlers) + * or NULL no action took place and no handler modified the value + */ + function trigger($action=NULL, $enablePrevent=true) { + + if (!is_callable($action)) $enablePrevent = false; + + if ($this->advise_before($enablePrevent) && is_callable($action)) { + if (is_array($action)) { + list($obj,$method) = $action; + $this->result = $obj->$method($this->data); + } else { + $this->result = $action($this->data); + } + } + + $this->advise_after(); + + return $this->result; + } + + /** + * stopPropagation + * + * stop any further processing of the event by event handlers + * this function does not prevent the default action taking place + */ + function stopPropagation() { $this->_continue = false; } + + /** + * preventDefault + * + * prevent the default action taking place + */ + function preventDefault() { $this->_default = false; } +} + +class Doku_Event_Handler { + + // public properties: none + + // private properties + var $_hooks = array(); // array of events and their registered handlers + + /** + * event_handler + * + * constructor, loads all action plugins and calls their register() method giving them + * an opportunity to register any hooks they require + */ + function __construct() { + + // load action plugins + $plugin = NULL; + $pluginlist = plugin_list('action'); + + foreach ($pluginlist as $plugin_name) { + $plugin =& plugin_load('action',$plugin_name); + + if ($plugin !== NULL) $plugin->register($this); + } + } + + /** + * register_hook + * + * register a hook for an event + * + * @PARAM $event (string) name used by the event, (incl '_before' or '_after' for triggers) + * @PARAM $obj (obj) object in whose scope method is to be executed, + * if NULL, method is assumed to be a globally available function + * @PARAM $method (function) event handler function + * @PARAM $param (mixed) data passed to the event handler + */ + function register_hook($event, $advise, &$obj, $method, $param=NULL) { + $this->_hooks[$event.'_'.$advise][] = array(&$obj, $method, $param); + } + + function process_event(&$event,$advise='') { + + $evt_name = $event->name . ($advise ? '_'.$advise : '_BEFORE'); + + if (!empty($this->_hooks[$evt_name])) { + $hook = reset($this->_hooks[$evt_name]); + do { +// list($obj, $method, $param) = $hook; + $obj =& $hook[0]; + $method = $hook[1]; + $param = $hook[2]; + + if (is_null($obj)) { + $method($event, $param); + } else { + $obj->$method($event, $param); + } + + } while ($event->_continue && $hook = next($this->_hooks[$evt_name])); + } + } +} + +/** + * trigger_event + * + * function wrapper to process (create, trigger and destroy) an event + * + * @PARAM $name (string) name for the event + * @PARAM $data (mixed) event data + * @PARAM $action (callback) (optional, default=NULL) default action, a php callback function + * @PARAM $canPreventDefault (bool) (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) { + + $evt = new Doku_Event($name, $data); + return $evt->trigger($action, $canPreventDefault); +} + +// create the event handler +global $EVENT_HANDLER; +$EVENT_HANDLER = new Doku_Event_Handler(); |