Differences

This shows you the differences between two versions of the page.

--- devel:event_handlers [2023-09-02 01:12] – Klap-in
+++ devel:event_handlers [2023-09-02 13:37] (current) – Klap-in
@@ Line 37: / Line 37: @@
 ===== Registering an Event =====
-Event handlers are registered using the ''register_hook()'' function of the ''EVENT_HANDLER'' class, the specifications for which are found on Dokuwiki's [[events#registering_to_receive_an_event|events page]].
+Event handlers are registered using the [[xref>register_hook()]] function of the [[xref>EventHandler]] class, the specifications for which are found on Dokuwiki's [[events#registering_to_receive_an_event|events page]].
 The function definition for ''register_hook()'' is as follows:
 <code php>
@@ Line 52: / Line 52: @@
 ==== Global Scope ====
 To call ''register_hook()'' from the global scope, you set ''$obj'' to null and use
-the global variable ''$EVENT_HANDLER'':
+the global variable [[xref>$EVENT_HANDLER]]:
 <code php>
 $EVENT_HANDLER->register_hook( ... )
@@ Line 66: / Line 66: @@
 ...
 public function register(EventHandler $controller) {
-    $controller->register_hook('TPL_ACT_RENDER', 'AFTER', $this,'tpl_render');
+    $controller->register_hook('TPL_ACT_RENDER', 'AFTER', $this,
+                                                          'templateRender');
 }
 </code>
     * The event is [[devel:event:TPL_ACT_RENDER]], which is activated in ''[[xref>inc/template.php]]'' by the function which dispatches the page to be formatted and printed.
-    * The event handler is ''tpl_render()'', which will be found in the plugin object.
+    * The event handler is ''templateRender()'', which will be found in the plugin object.
     * The ''$this'' parameter, which points to the plugin object, will give DokuWiki's event module access to the handler.
     * Finally, the handler is to be called **after** DokuWiki formats the page content.
@@ Line 100: / Line 101: @@
     * ''name'': Event Name;
     * ''data'': Specific to each event, data may include, page content, headers, meta data, objects, the current action (e.g. edit, index), whatever is needed of for the execution of the event; it may also hold no data, and it has no fixed structure: it may be a string, array, multidimensional array, object.
-    * ''result'': First it holds the return value from the default handler, which can then be consulted by an ''AFTER'' handler. It can then be modified by an ''AFTER'' handler, in which case it might be information for any subsequent ''AFTER'' handlers. Ultimately, it will be returned to the ''[[#methods|Event::createAndTrigger()]]'' function. In most case this value is either ''true'', if the default action has taken place, or ''null'' if it hasn't.
+    * ''result'': First it holds the return value from the default handler, which can then be consulted by an ''AFTER'' handler. It can then be modified by an ''AFTER'' handler, in which case it might be information for any subsequent ''AFTER'' handlers. Ultimately, it will be returned to the [[#methods|Event::createAndTrigger()]] function. In most case this value is either ''true'', if the default action has taken place, or ''null'' if it hasn't.
     * ''canPreventDefault'':  ''true'' or ''false'', indicating whether or not the default action for this event can be stopped; this information is available from DokuWiki's [[events list]].
-    * protected ''runDefault'':  ''true'' or ''false'', indicating whether the default action for this event should be enabled; its default value is true but can be set to false by calling $event%%->%%preventDefault().
+    * protected ''runDefault'':  ''true'' or ''false'', indicating whether the default action for this event should be enabled; its default value is true but can be set to false by calling ''$event%%->%%preventDefault()''.
-    * protected ''mayContinue'':  This value defaults to ''true''. If ''$event%%->%%stopPropagation()'' is called, it is set to false, stopping "any further processing of the event by event handlers" but "this function does not prevent the default action taking place".((Comment from [[xref>dokuwiki\Extension\Event]]))
+    * protected ''mayContinue'':  This value defaults to ''true''. If ''$event%%->%%stopPropagation()'' is called, it is set to false, stopping any further processing of the event ''BEFORE'' or ''AFTER'' handlers registered for this event, but this function does not prevent the default action taking place.
 ==== Methods ====
@@ Line 111: / Line 112: @@
     - ''$event%%->%%[[xref>stopPropagation()]]''.
         * Calling this method sets ''$event%%->%%mayContinue'' to ''false'' and stops any further processing of the event by event handlers; it does not prevent the default action taking place. It comes into play where you have set more than one handler for the same event. If you have registered an event for both ''BEFORE'' and ''AFTER'' execution, canceling the ''BEFORE'' does not stop propagation of the ''AFTER'' events. (See the above section on the [[#the_event_loop|Event Loop]]).
-    - ''mixed [[xref>Event::createAndTrigger|Event::createAndTrigger($name, &$data, $action=null, $canPreventDefault=true)]]''
+    - ''mixed [[xref>Event::createAndTrigger|Event::createAndTrigger(string $name, mixed &$data, callable $action=null, bool $canPreventDefault=true)]]''
-        * This is a global function, not a method of the ''Doku_Event'' class. Calling this function enables the triggering of a user-defined event. Its parameters are as follows:
+        * This is a global function. Calling this function enables the triggering of a user-defined event. Its parameters are as follows:
              * ''$name'': This is the name of the event. If you implement your own event, then this is the name of that event.
              * ''$data'': Whatever is required for your data