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