DokuWiki

It's better when it's simple

User Tools

Site Tools

Trace:
devel:events

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
devel:events [2014-05-06 19:51] – [Registering to Receive an Event] Klap-indevel:events [2023-09-02 13:58] (current) – [On Wiki page save] Klap-in
Line 14: Line 14:
 ===== Event Object ===== ===== Event Object =====
  
-**class name ''[[xref>Doku_Event]]''**+**Class name [[xref>dokuwiki\Extension\Event]]**
  
 An event object consists of: An event object consists of:
Line 22: Line 22:
     * ''result'', (read/write) available after the default action has taken place to hooks that have registered for the ''after'' advise.     * ''result'', (read/write) available after the default action has taken place to hooks that have registered for the ''after'' advise.
     * ''canPreventDefault'', (readonly) informs a hook whether or not the default action can be prevented     * ''canPreventDefault'', (readonly) informs a hook whether or not the default action can be prevented
-  * **Private** properties +  * **Protected** properties 
-    * ''_default'' (boolean, initial value ''true''), whether or not the default action associated with the event should be carried out.  Interact with this property via the ''preventDefault()'' method. +    * ''runDefault'' (boolean, initial value ''true''), whether or not the default action associated with the event should be carried out.  Interact with this property via the ''preventDefault()'' method. 
-    * ''_continue'' (boolean, initial value ''true''), whether or not to continue sending the event to registered hooks that have yet to receive it.  Interact with this property via the ''stopPropagation()'' method.+    * ''mayContinue'' (boolean, initial value ''true''), whether or not to continue sending the event to registered hooks that have yet to receive it.  Interact with this property via the ''stopPropagation()'' method.
  
   * **Public** methods   * **Public** methods
-    * ''[[xref>trigger()]]'' - automated signalling of events.  This method accepts two optional parameters, the default action (callback), and whether or not it may be prevented (bool) and returns the results of the event.  It looks after the whole event process, signalling the "_BEFORE" advise, triggering the default action and signalling the "_AFTER" advise.+    * ''[[xref>trigger()]]'' - automated signalling of events.  This method accepts two optional parameters, the default action (callback), and whether or not it may be prevented (bool) and returns the results of the event.  It looks after the whole event process, signalling the "BEFORE" advise, triggering the default action and signalling the "AFTER" advise.
     * ''[[xref>stopPropagation()]]'' - stop any further processing of the event by event handlers this function does not prevent the default action taking place     * ''[[xref>stopPropagation()]]'' - stop any further processing of the event by event handlers this function does not prevent the default action taking place
 +    * ''[[xref>mayPropagate()]]'' - may the event propagate to the next handler?
     * ''[[xref>preventDefault()]]'' - prevent the default action taking place     * ''[[xref>preventDefault()]]'' - prevent the default action taking place
 +    * ''[[xref>mayRunDefault()]]'' - should the default action be executed?
   * ''advise_*()'' methods - for use when the signalling script wishes to handle the complete event signalling process (perhaps when functionalising a default action is not appropriate).   * ''advise_*()'' methods - for use when the signalling script wishes to handle the complete event signalling process (perhaps when functionalising a default action is not appropriate).
-    * ''[[xref>advise_before()]]'' - accepts one parameter, a boolean indicating whether the default action can be prevented, issues the "_BEFORE" signal. +    * ''[[xref>advise_before()]]'' - accepts one parameter, a boolean indicating whether the default action can be prevented, issues the "BEFORE" signal. 
-    * ''[[xref>advise_after()]]'' - issues the "_AFTER" signal.+    * ''[[xref>advise_after()]]'' - issues the "AFTER" signal.
  
  
Line 44: Line 46:
 </code> </code>
  
-For up-to-date details of the [[xref>register_hook()]] function and its parameters refer to its declaration in ''[[xref>inc/events.php]]''. +For up-to-date details of the [[xref>register_hook()]] function and its parameters refer to its declaration. 
  
 Use ''register_hook($event, $advise, $obj, $method, $param=null, $seq=0)'' with the arguments: Use ''register_hook($event, $advise, $obj, $method, $param=null, $seq=0)'' with the arguments:
Line 52: Line 54:
   * ''$method'' //function//, event handler function. More info at the [[Event handlers]] page.   * ''$method'' //function//, event handler function. More info at the [[Event handlers]] page.
   * ''$param'' //mixed// (optional), the data to be passed to the event handler. Default null.   * ''$param'' //mixed// (optional), the data to be passed to the event handler. Default null.
-  * ''$seq'' //int// (optional), sequence number used to control the order in which hooks are executed. Hooks are executed in ascending $seq order.  If two or more hooks have the same $seq value, their order (relative to each other) is undefined. Hooks can use ''-PHP_INT_MAX'' or ''[[http://www.php.net/manual/en/reserved.constants.php#constant.php-int-max|PHP_INT_MAX]]'', in an attempt to be first or last. Be aware that these values provide no guarantee of being first/last as more than one plugin can use them.+  * ''$seq'' //int// (optional), sequence number used to control the order in which hooks are executed. Hooks are executed in ascending $seq order.  If two or more hooks have the same $seq value, their order (relative to each other) is undefined. Hooks can use ''-PHP_INT_MAX'' or ''[[http://www.php.net/manual/en/reserved.constants.php#constant.php-int-max|PHP_INT_MAX]]'', in an attempt to be first or last, but that is not recommended. Be aware that these values provide no guarantee of being first/last as more than one plugin can use them. 
 ===== Signalling an Event ===== ===== Signalling an Event =====
  
 An event can be signalled in three ways.   An event can be signalled in three ways.  
  
-  - The simplest is to use the function wrapper ''[[xref>trigger_event()]]''. This function takes all the parameters necessary to create an event object and trigger it. \\ Use ''trigger_event($name, &$data, $action=null, $canPreventDefault=true)'' with the arguments:     +  - The simplest is to use the function wrapper [[xref>Event::createAndTrigger()]]. This function takes all the parameters necessary to create an event object and trigger it. \\ Use ''Event::createAndTrigger($name, &$data, $action=null, $canPreventDefault=true)'' with the arguments:     
      * ''$name'' //string//, name for the event      * ''$name'' //string//, name for the event
      * ''$data'' //mixed//, event data      * ''$data'' //mixed//, event data
      * ''$action'' //callback// (optional), default action given as php callback function. Default null.      * ''$action'' //callback// (optional), default action given as php callback function. Default null.
      * ''$canPreventDefault'' //boolean// (optional), can hooks prevent the default action. Default true.      * ''$canPreventDefault'' //boolean// (optional), can hooks prevent the default action. Default true.
-     * return //mixed//, the event result value after all event processing is complete. By default this is the return value of the default action. However it can be set or modified by event handlers hooks as it is stored in ''result'' attribute of the ''[[xref>Doku_Event]]'' object, where the Doku_Event is available in handlers. <code php> +     * return //mixed//, the event result value after all event processing is complete. By default this is the return value of the default action. However it can be set or modified by event handlers hooks as it is stored in ''result'' attribute of the ''[[xref>Event]]'' object, where the Event is available in handlers. <code php> 
-trigger_event(<EVENT_NAME>, <event data>, +Event::createAndTrigger(<EVENT_NAME>, <event data>, 
               <action callback>, <can prevent default>)                <action callback>, <can prevent default>) 
 </code> </code>
-  - using the [[xref>trigger()]] method.  This isn't recommended as it is better to use the ''trigger_event()'' function wrapper described above. <code php> +  - using the [[xref>trigger()]] method.  This isn't recommended as it is better to use the ''Event::createAndTrigger()'' function wrapper described above. <code php> 
-$evt = new Doku_Event(<EVENT_NAME>,<event_data>); +$event = new dokuwiki\Extension\Event(<EVENT_NAME>,<event_data>); 
-$evt->trigger(<default action>,<can prevent default>); +$event->trigger(<default action>,<can prevent default>); 
-unset($evt);+unset($event);
 </code> </code>
-  - managing the whole event signalling process with [[xref>advise_before()|advise_before($enablePreventDefault = true)]] and [[xref>advise_after()|advise_after()]] on the [[xref>Doku_Event]] object.  Use this method when there is a default action but it not possible to package it as a PHP callback function. <code php> +  - managing the whole event signalling process with [[xref>advise_before($enablePreventDefault = true)]] and [[xref>advise_after()]] on the [[xref>Event]] object.  Use this method when there is a default action but it not possible to package it as a PHP callback function. <code php> 
-$evt = new Doku_Event(<EVENT_NAME>, <event data>); +$event = new dokuwiki\Extension\Event(<EVENT_NAME>, <event data>); 
-if ($evt->advise_before(<can prevent default>)) {+if ($event->advise_before(<can prevent default>)) {
   // default action code block   // default action code block
 } }
-$evt->advise_after(); +$event->advise_after(); 
-unset($evt);+unset($event);
 </code> </code>
  
Line 87: Line 90:
  
 <code php> <code php>
 +use dokuwiki\Extension\Event;
 +
 // event:  'IO_WIKIPAGE_SAVE' // event:  'IO_WIKIPAGE_SAVE'
 // data:   array(file name, the raw wiki page) // data:   array(file name, the raw wiki page)
 // action: save the raw wiki page to file name // action: save the raw wiki page to file name
 // return: bool, page saved // return: bool, page saved
-$data = array($id,$wikitext); +$data = [$id, $wikitext]; 
-$ok = trigger_event('SAVE_WIKIPAGE', $data, io_savewikipage);+$ok = Event::createAndTrigger('SAVE_WIKIPAGE', $data, io_savewikipage);
 </code> </code>
  
Line 106: Line 111:
  
 // in ''inc/actions.php act_dispatch()'' // in ''inc/actions.php act_dispatch()''
-$evt = new Doku_Event('ACTION_ACT_PREPROCESS', $ACT);   +$event = new dokuwiki\Extension\Event('ACTION_ACT_PREPROCESS', $ACT);   
-if ($evt->advise_before()) { +if ($event->advise_before()) { 
     /* process $ACT normally */      /* process $ACT normally */ 
 } }
-$evt->advise_after(); +$event->advise_after(); 
-unset($evt);+unset($event);
  
 // in ''inc/template.php tpl_content()'' // in ''inc/template.php tpl_content()''
-default: /* unrecognised $ACT value */ +// default: unrecognised $ACT value 
-$evt = new Doku_Event('TPL_ACT_UNKNOWN', $ACT); +$event = new dokuwiki\Extension\Event('TPL_ACT_UNKNOWN', $ACT); 
-if ($evt->advise_before()) { +if ($event->advise_before()) { 
     print "unknown action";      print "unknown action"; 
 } }
-$evt->advise_after(); +$event->advise_after(); 
-unset($evt);+unset($event);
 </code> </code>
 Possible handlers, customer form processing, additional ''do'' commands from template UI. Possible handlers, customer form processing, additional ''do'' commands from template UI.
Line 127: Line 132:
 ==== On handler instruction list completion ==== ==== On handler instruction list completion ====
 <code php> <code php>
-  // event:  ''PARSER_HANDLER_DONE'' +use dokuwiki\Extension\Event; 
-  // data:   the handler, including the completed instruction list + 
-  // action: none+// event:  ''PARSER_HANDLER_DONE'' 
 +// data:   the handler, including the completed instruction list 
 +// action: none
      
-  // in ''inc/parser/handler.php  _finalize() +// in ''inc/parser/handler.php  _finalize() 
-  trigger_event('PARSER_HANDLER_DONE',$this);+Event::createAndTrigger('PARSER_HANDLER_DONE', $this);
 </code> </code>
 possible handlers, footnote replacement plugins, enhanced TOC handlers possible handlers, footnote replacement plugins, enhanced TOC handlers
devel/events.1399398707.txt.gz · Last modified: 2014-05-06 19:51 by Klap-in
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki

Global DokuWiki Links