Skip to content
This repository
Newer
Older
100644 198 lines (163 sloc) 6.812 kb
f65bfee1 »
2006-04-14 action plugins
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
fa8adffe »
2008-12-13 removed some illogical path setups
9 if(!defined('DOKU_INC')) die('meh.');
f65bfee1 »
2006-04-14 action plugins
10
24bb549b »
2006-04-25 event system revision
11 class Doku_Event {
f65bfee1 »
2006-04-14 action plugins
12
49eb6e38 »
2010-01-15 some more coding standard compliance updates
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;
73ca7c9c »
2006-04-25 event (minor) update
97 }
c9570649 »
2006-11-16 two more event hooks
98
49eb6e38 »
2010-01-15 some more coding standard compliance updates
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; }
f65bfee1 »
2006-04-14 action plugins
113 }
114
24bb549b »
2006-04-25 event system revision
115 class Doku_Event_Handler {
f65bfee1 »
2006-04-14 action plugins
116
49eb6e38 »
2010-01-15 some more coding standard compliance updates
117 // public properties: none
f65bfee1 »
2006-04-14 action plugins
118
49eb6e38 »
2010-01-15 some more coding standard compliance updates
119 // private properties
120 var $_hooks = array(); // array of events and their registered handlers
f65bfee1 »
2006-04-14 action plugins
121
49eb6e38 »
2010-01-15 some more coding standard compliance updates
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() {
f65bfee1 »
2006-04-14 action plugins
129
49eb6e38 »
2010-01-15 some more coding standard compliance updates
130 // load action plugins
131 $plugin = null;
132 $pluginlist = plugin_list('action');
f65bfee1 »
2006-04-14 action plugins
133
49eb6e38 »
2010-01-15 some more coding standard compliance updates
134 foreach ($pluginlist as $plugin_name) {
135 $plugin =& plugin_load('action',$plugin_name);
f65bfee1 »
2006-04-14 action plugins
136
49eb6e38 »
2010-01-15 some more coding standard compliance updates
137 if ($plugin !== null) $plugin->register($this);
f65bfee1 »
2006-04-14 action plugins
138 }
49eb6e38 »
2010-01-15 some more coding standard compliance updates
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 */
3ab58ffe »
2012-04-17 no need to pass objects by reference
152 function register_hook($event, $advise, $obj, $method, $param=null) {
153 $this->_hooks[$event.'_'.$advise][] = array($obj, $method, $param);
49eb6e38 »
2010-01-15 some more coding standard compliance updates
154 }
f65bfee1 »
2006-04-14 action plugins
155
49eb6e38 »
2010-01-15 some more coding standard compliance updates
156 function process_event(&$event,$advise='') {
157
158 $evt_name = $event->name . ($advise ? '_'.$advise : '_BEFORE');
159
160 if (!empty($this->_hooks[$evt_name])) {
8cb3706d »
2012-05-11 Fix nested triggering of the same event
161 foreach ($this->_hooks[$evt_name] as $hook) {
49eb6e38 »
2010-01-15 some more coding standard compliance updates
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
8cb3706d »
2012-05-11 Fix nested triggering of the same event
173 if (!$event->_continue) break;
174 }
49eb6e38 »
2010-01-15 some more coding standard compliance updates
175 }
f65bfee1 »
2006-04-14 action plugins
176 }
177 }
178
73ca7c9c »
2006-04-25 event (minor) update
179 /**
49eb6e38 »
2010-01-15 some more coding standard compliance updates
180 * trigger_event
73ca7c9c »
2006-04-25 event (minor) update
181 *
49eb6e38 »
2010-01-15 some more coding standard compliance updates
182 * function wrapper to process (create, trigger and destroy) an event
73ca7c9c »
2006-04-25 event (minor) update
183 *
49eb6e38 »
2010-01-15 some more coding standard compliance updates
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
73ca7c9c »
2006-04-25 event (minor) update
188 *
49eb6e38 »
2010-01-15 some more coding standard compliance updates
189 * @return (mixed) the event results value after all event processing is complete
73ca7c9c »
2006-04-25 event (minor) update
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 */
49eb6e38 »
2010-01-15 some more coding standard compliance updates
193 function trigger_event($name, &$data, $action=null, $canPreventDefault=true) {
73ca7c9c »
2006-04-25 event (minor) update
194
49eb6e38 »
2010-01-15 some more coding standard compliance updates
195 $evt = new Doku_Event($name, $data);
196 return $evt->trigger($action, $canPreventDefault);
24bb549b »
2006-04-25 event system revision
197 }
Something went wrong with that request. Please try again.