event system revision

This is a major revision of DokuWiki's event system.  There are changes to class names,
function names, function parameters and their order and event names.

For action plugin writers the following changes are important:

- <event_name> is no longer signalled, only <event_name>_BEFORE and <event_name>_AFTER.
- note the case change for _BEFORE and _AFTER
- calling stopPropagation while processing a _BEFORE signal no longer prevents an
  _AFTER signal. The events _continue value is reset before the _AFTER signal is made.
- events have a new readonly property, canPreventDefault. This lets the event handling
  hook know whether or not the event honours preventDefault calls.

- parameters have changed for the register_hook method, parameters are now
  $event_name,
  $advise (can be 'BEFORE' or 'AFTER')
  $object
  $method
  $param  (this parameter is now optional)
- parameter order has changed for the hook event handler callback functions
  &$event
  $param  (can now be left off)

Event names have changed, they are now structured
  <dokuwiki name>_<event data name>_<action_name or state if no action>

DOKUWIKI_START

darcs-hash:20060424220152-9b6ab-00e366288f7ec8a85b85dc83694a5f43a07aa082.gz

1 files changed, 69 insertions, 43 deletions

diff --git a/inc/events.php b/inc/events.php
index 59c1d904d..f42acab0f 100644
--- a/inc/events.php
+++ b/inc/events.php
@@ -8,75 +8,94 @@
 
 if(!defined('DOKU_INC')) define('DOKU_INC',realpath(dirname(__FILE__).'/../').'/');
 require_once(DOKU_INC.'inc/pluginutils.php');
-class event {
 
-  // public properties
-  var $name = '';           // event name, objects must register against this name to see the event
-  var $data = NULL;         // data relevant to the event, no standardised format (YET!)
-  var $result = NULL;       // the results of the event action, only relevant in "*_after" advise
+class Doku_Event {
 
-  // private properties
+  // 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
-  var $_action = NULL;      // the function executed to carry out the event
 
   /**
    * event constructor
    */
-  function event($name, &$data, $fn=NULL) {
+  function Doku_Event($name, &$data) {
 
     $this->name = $name;
     $this->data =& $data;
-    $this->_action = $fn;
 
   }
 
   /**
-   * advise
+   * advise functions
    *
    * advise all registered handlers of this event
-   * any processing based on the event's _default property to be determined by the caller
+   *
+   * 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() {
+  function advise_before($enablePreventDefault=true) {
     global $EVENT_HANDLER;
 
-    return $EVENT_HANDLER->process_event($this,'');
+    return $EVENT_HANDLER->process_event($this,'BEFORE');
+  }
+
+  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 $this->_default, all of which
-   * may have been modified by the event handlers
-   * if the action was carried out, advise all registered (<event>_after) handlers that the
-   * event has taken place
+   * - 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() {
-    global $EVENT_HANDLER;
-
-    $EVENT_HANDLER->process_event($this,'before');
-    if ($this->_continue) $EVENT_HANDLER->process_event($this,'');
-
-    if ($this->_default && is_callable($this->_action)) {
-		  if (is_array($this->_action)) {
-        list($obj,$method) = $this->_action;
-        $this->result = $obj->$method($this->data);
-			} else {
-        $fn = $this->_action;
-        $this->result = $fn($this->data);
-			}
-
-      $EVENT_HANDLER->process_event($this,'after');
+  function trigger($action=NULL, $enablePrevent=true) {
+
+    if (!is_callable($action)) $enablePrevent = false;
+    $this->canPreventDefault = $enablePrevent;
+    
+    $this->advise_before($enablePrevent);
+
+    if (is_callable($action)) {
+      if (!$enablePrevent || $this->_default) {
+        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;
   }
 
@@ -96,7 +115,7 @@ class event {
   function preventDefault() { $this->_default = false;  }
 }
 
-class event_handler {
+class Doku_Event_Handler {
 
   // public properties:  none
 
@@ -109,7 +128,7 @@ class event_handler {
    * constructor, loads all action plugins and calls their register() method giving them
    * an opportunity to register any hooks they require
    */
-  function event_handler() {
+  function Doku_Event_Handler() {
 
     // load action plugins
     $plugin = NULL;
@@ -133,22 +152,22 @@ class event_handler {
    * @PARAM  $method  (function) event handler function
    * @PARAM  $param   (mixed)    data passed to the event handler
    */ 
-  function register_hook($event, &$obj, $method, $param) {
-    $this->_hooks[$event][] = array($obj, $method, $param);
+  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 : '');
+    $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;
         if (is_null($obj)) {
-          $method($param, $event);
+          $method($event, $param);
         } else {
-          $obj->$method($param, $event);
+          $obj->$method($event, $param);
         }
 
       } while ($event->_continue && $hook = next($this->_hooks[$evt_name]));
@@ -158,5 +177,12 @@ class event_handler {
   }
 }
 
+// function wrapper to enable one line event triggering
+function trigger_event($name, &$data, $action=NULL, $canPreventDefault=true) {
+  
+  $evt = new Doku_Event($name, $data);
+  return $evt->trigger($action, $canPreventDefault);
+}
+
 // create the event handler
-$EVENT_HANDLER = new event_handler();
+$EVENT_HANDLER = new Doku_Event_Handler();