Creating repository for dokuwiki modifications for sudaraka.org
[sudaraka-org:dokuwiki-mods.git] / 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             $hook = reset($this->_hooks[$evt_name]);
162             do {
163                 //        list($obj, $method, $param) = $hook;
164                 $obj =& $hook[0];
165                 $method = $hook[1];
166                 $param = $hook[2];
167
168                 if (is_null($obj)) {
169                     $method($event, $param);
170                 } else {
171                     $obj->$method($event, $param);
172                 }
173
174             } while ($event->_continue && $hook = next($this->_hooks[$evt_name]));
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 }