inc/events.php

   1 <?php
   2 /**
   3  * DokuWiki Events
   4  *
   5  * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
   6  * @author     Christopher Smith <chris@jalakai.co.uk>
   7  */
   8
   9 if(!defined('DOKU_INC')) die('meh.');
  10
  11 class Doku_Event {
  12
  13     // public properties
  14     var $name = '';                // READONLY  event name, objects must register against this name to see the event
  15     var $data = null;              // READWRITE data relevant to the event, no standardised format (YET!)
  16     var $result = null;            // READWRITE the results of the event action, only relevant in "_AFTER" advise
  17     //    event handlers may modify this if they are preventing the default action
  18     //    to provide the after event handlers with event results
  19     var $canPreventDefault = true; // READONLY  if true, event handlers can prevent the events default action
  20
  21     // private properties, event handlers can effect these through the provided methods
  22     var $_default = true;     // whether or not to carry out the default action associated with the event
  23     var $_continue = true;    // whether or not to continue propagating the event to other handlers
  24
  25     /**
  26      * event constructor
  27      */
  28     function Doku_Event($name, &$data) {
  29
  30         $this->name = $name;
  31         $this->data =& $data;
  32
  33     }
  34
  35     /**
  36      * advise functions
  37      *
  38      * advise all registered handlers of this event
  39      *
  40      * if these methods are used by functions outside of this object, they must
  41      * properly handle correct processing of any default action and issue an
  42      * advise_after() signal. e.g.
  43      *    $evt = new Doku_Event(name, data);
  44      *    if ($evt->advise_before(canPreventDefault) {
  45      *      // default action code block
  46      *    }
  47      *    $evt->advise_after();
  48      *    unset($evt);
  49      *
  50      * @return  results of processing the event, usually $this->_default
  51      */
  52     function advise_before($enablePreventDefault=true) {
  53         global $EVENT_HANDLER;
  54
  55         $this->canPreventDefault = $enablePreventDefault;
  56         $EVENT_HANDLER->process_event($this,'BEFORE');
  57
  58         return (!$enablePreventDefault || $this->_default);
  59     }
  60
  61     function advise_after() {
  62         global $EVENT_HANDLER;
  63
  64         $this->_continue = true;
  65         $EVENT_HANDLER->process_event($this,'AFTER');
  66     }
  67
  68     /**
  69      * trigger
  70      *
  71      * - advise all registered (<event>_BEFORE) handlers that this event is about to take place
  72      * - carry out the default action using $this->data based on $enablePrevent and
  73      *   $this->_default, all of which may have been modified by the event handlers.
  74      * - advise all registered (<event>_AFTER) handlers that the event has taken place
  75      *
  76      * @return  $event->results
  77      *          the value set by any <event>_before or <event> handlers if the default action is prevented
  78      *          or the results of the default action (as modified by <event>_after handlers)
  79      *          or NULL no action took place and no handler modified the value
  80      */
  81     function trigger($action=null, $enablePrevent=true) {
  82
  83         if (!is_callable($action)) $enablePrevent = false;
  84
  85         if ($this->advise_before($enablePrevent) && is_callable($action)) {
  86             if (is_array($action)) {
  87                 list($obj,$method) = $action;
  88                 $this->result = $obj->$method($this->data);
  89             } else {
  90                 $this->result = $action($this->data);
  91             }
  92         }
  93
  94         $this->advise_after();
  95
  96         return $this->result;
  97     }
  98
  99     /**
 100      * stopPropagation
 101      *
 102      * stop any further processing of the event by event handlers
 103      * this function does not prevent the default action taking place
 104      */
 105     function stopPropagation() { $this->_continue = false;  }
 106
 107     /**
 108      * preventDefault
 109      *
 110      * prevent the default action taking place
 111      */
 112     function preventDefault() { $this->_default = false;  }
 113 }
 114
 115 class Doku_Event_Handler {
 116
 117     // public properties:  none
 118
 119     // private properties
 120     var $_hooks = array();          // array of events and their registered handlers
 121
 122     /**
 123      * event_handler
 124      *
 125      * constructor, loads all action plugins and calls their register() method giving them
 126      * an opportunity to register any hooks they require
 127      */
 128     function Doku_Event_Handler() {
 129
 130         // load action plugins
 131         $plugin = null;
 132         $pluginlist = plugin_list('action');
 133
 134         foreach ($pluginlist as $plugin_name) {
 135             $plugin =& plugin_load('action',$plugin_name);
 136
 137             if ($plugin !== null) $plugin->register($this);
 138         }
 139     }
 140
 141     /**
 142      * register_hook
 143      *
 144      * register a hook for an event
 145      *
 146      * @param  $event   (string)   name used by the event, (incl '_before' or '_after' for triggers)
 147      * @param  $obj     (obj)      object in whose scope method is to be executed,
 148      *                             if NULL, method is assumed to be a globally available function
 149      * @param  $method  (function) event handler function
 150      * @param  $param   (mixed)    data passed to the event handler
 151      */
 152     function register_hook($event, $advise, $obj, $method, $param=null) {
 153         $this->_hooks[$event.'_'.$advise][] = array($obj, $method, $param);
 154     }
 155
 156     function process_event(&$event,$advise='') {
 157
 158         $evt_name = $event->name . ($advise ? '_'.$advise : '_BEFORE');
 159
 160         if (!empty($this->_hooks[$evt_name])) {
 161             foreach ($this->_hooks[$evt_name] as $hook) {
 162                 //        list($obj, $method, $param) = $hook;
 163                 $obj =& $hook[0];
 164                 $method = $hook[1];
 165                 $param = $hook[2];
 166
 167                 if (is_null($obj)) {
 168                     $method($event, $param);
 169                 } else {
 170                     $obj->$method($event, $param);
 171                 }
 172
 173                 if (!$event->_continue) break;
 174             }
 175         }
 176     }
 177 }
 178
 179 /**
 180  * trigger_event
 181  *
 182  * function wrapper to process (create, trigger and destroy) an event
 183  *
 184  * @param  $name               (string)   name for the event
 185  * @param  $data               (mixed)    event data
 186  * @param  $action             (callback) (optional, default=NULL) default action, a php callback function
 187  * @param  $canPreventDefault  (bool)     (optional, default=true) can hooks prevent the default action
 188  *
 189  * @return (mixed)                        the event results value after all event processing is complete
 190  *                                         by default this is the return value of the default action however
 191  *                                         it can be set or modified by event handler hooks
 192  */
 193 function trigger_event($name, &$data, $action=null, $canPreventDefault=true) {
 194
 195     $evt = new Doku_Event($name, $data);
 196     return $evt->trigger($action, $canPreventDefault);
 197 }