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 [2013-11-06 00:26] – [Event Object] 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:
-  * **PUBLIC** properties +  * **Public** properties 
-    * ''name'', (READONLY) hooks must use this to register to process a particular event +    * ''name'', (readonly) hooks must use this to register to process a particular event 
-    * ''data'', (READ/WRITE) data pertaining to the event, hooks have an opportunity to inspect and modify this +    * ''data'', (read/write) data pertaining to the event, hooks have an opportunity to inspect and modify this 
-    * ''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'' (bool, inital 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'' (bool, 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. 
 + 
 ===== Registering to Receive an Event ===== ===== Registering to Receive an Event =====
  
 To register a hook to receive an event, call the ''register_hook()'' method of the ''$EVENT_HANDLER''.  Action plugins can do this using the ''$controller'' parameter from within their own ''register()'' method.  Other parts of DokuWiki should ensure they are either in global scope or declare $EVENT_HANDLER as a global. e.g. To register a hook to receive an event, call the ''register_hook()'' method of the ''$EVENT_HANDLER''.  Action plugins can do this using the ''$controller'' parameter from within their own ''register()'' method.  Other parts of DokuWiki should ensure they are either in global scope or declare $EVENT_HANDLER as a global. e.g.
  
-  global $EVENT_HANDLER; +<code php> 
-  $EVENT_HANDLER->register_hook( ... )+global $EVENT_HANDLER; 
 +$EVENT_HANDLER->register_hook( ... ) 
 +</code>
  
-For up-to-date details of the [[xref>register_hook()]] function and its parameters refer to its declaration in ''inc/events.php''.  As of 2006-04-26 the declaration is+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:
 +  * ''$event'' //string//,  name used by the event
 +  * ''$advise'' //string//, ''BEFORE'' or ''AFTER'', the advise the hook wished to receive
 +  * ''$obj'' //object//, object in whose scope method is to be executed. If ''null'' the method is assumed to be a globally available function
 +  * ''$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.
 +  * ''$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.
  
- 
-<code php> 
-/** 
- * register_hook 
- * 
- * register a hook for an event 
- * 
- * @param string   $event  name used by the event 
- * @param string   $advise ''BEFORE'' or ''AFTER'', the advise the hook wished to receive 
- * @param obj      $obj    object in whose scope method is to be executed,  
- *                         if NULL, method is assumed to be a globally available function 
- * @param function $method event handler function 
- * @param mixed    $param  (optional) data to be passed to the event handler 
- */  
-function register_hook($event, $advise, $obj, $method, $param) 
- 
-</code> 
 ===== 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. \\ <code php> + 
-/** +  - 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:      
- * trigger_event +     * ''$name'' //string//, name for the event 
- * +     * ''$data'' //mixed//, event data 
- * function wrapper to process (create, trigger and destroy) an event +     * ''$action'' //callback// (optional), default action given as php callback function. Default null. 
- * +     * ''$canPreventDefault'' //boolean// (optional), can hooks prevent the default action. Default true. 
- * @param string   $name              name for the event +     * 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> 
- * @param mixed    $data              event data +Event::createAndTrigger(<EVENT_NAME>, <event data>,  
- * @param callback $action            (optional, default=null) default action, a php callback function +              <action callback>, <can prevent default>) 
- * @param bool     $canPreventDefault (optional, default=true) can hooks prevent the default action +
- * +
- * @return mixed the event results 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 handler hooks +
- */ +
-function trigger_event($name, &$data, $action=null, $canPreventDefault=true)+
 </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.  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>
 +
 ===== Examples ===== ===== Examples =====
  
-(these are examples only and may not exist in DokuWiki)+(These are examples only and may not exist in DokuWiki.)
  
-** On Wiki page save **+==== On Wiki page save ====
  
 <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>
  
-possible handlers, indexers, translators +Possible handlers, indexers, translators.
-----+
  
-** Additional/Replacement ''do'' actions **+ 
 +==== Additional/Replacement ?do=... actions ====
  
 <code php> <code php>
-  // events:  'ACTION_ACT_PREPROCESS' & 'TPL_ACT_UNKNOWN' +// events:  'ACTION_ACT_PREPROCESS' & 'TPL_ACT_UNKNOWN' 
-  // data:    $ACT  (value of the ''do'' query string variable) +// data:    $ACT  (value of the ''do'' query string variable) 
-  // action:  none, handled by signalling script +// action:  none, handled by signalling script 
-   + 
-  // 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.
-----+
  
-** 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
-----+ 
 +=====See also===== 
 +  * [[Events List]] with existing events. 
 +  * Use [[devel:Action plugins]] to register handlers on events. 
 +  * More about [[Event handlers]] 
 +  * Examples of [[event handlers code]]
devel/events.1383693994.txt.gz · Last modified: 2013-11-06 00:26 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