DokuWiki

It's better when it's simple

User Tools

Site Tools

Trace:
devel:action_plugins

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
Next revisionBoth sides next revision
devel:action_plugins [2013-11-01 19:09] – Klap-indevel:action_plugins [2017-08-18 17:47] – Correct misspelling 'class action_plugin_actionexample' 50.226.69.58
Line 6: Line 6:
 ===== Working principle ===== ===== Working principle =====
  
-Action plugins are loaded before any significant DokuWiki processing takes place. Immediately after loading, each plugin is called by its ''register()'' method to give it the opportunity to register any of its event handlers.  When an event is signaled all event handlers registered for that event are called in turn (and in no particular order) and passed the event object by reference.  The handler has the opportunity to take action based on the event data and to alter either the event data or the event's subsequent processing.  For more details of how the events system works and lists of events refer to the [[devel:events]] page.+Action plugins are loaded before any significant DokuWiki processing takes place. Immediately after loading, each plugin is called by its ''register()'' method to give it the opportunity to register any of its event handlers.  When an event is signaled all event handlers registered for that event are called in turn (and in no particular order [ //Since release 2014-05-05 "Ponder Stibbons" - and in ascending order of the $seq number used to register them// ]) and passed the event object by reference.  The handler has the opportunity to take action based on the event data and to alter either the event data or the event's subsequent processing.  For more details of how the events system works and lists of events refer to the [[devel:events]] page.
  
 ===== Synopsis ===== ===== Synopsis =====
Line 22: Line 22:
 An action plugin requires at least two methods: An action plugin requires at least two methods:
   * **''register(Doku_Event_Handler $controller)''** Use this method to register your handlers with the DokuWiki's event controller   * **''register(Doku_Event_Handler $controller)''** Use this method to register your handlers with the DokuWiki's event controller
-  * **''<event handler>(&$event, $param)''** Your event handler(s), that perform your actions when they are triggered.+  * **''<event handler>(Doku_Event $event, $param)''** Your event handler(s), that perform your actions when they are triggered.
  
 You can register multiple events in a single action plugin. When doing this you may need multiple ''<event handler>()'' functions. You can register multiple events in a single action plugin. When doing this you may need multiple ''<event handler>()'' functions.
Line 30: Line 30:
  
 ===== register() method===== ===== register() method=====
-The ''register()'' method is used to subscribe an event. The following code shows a generic version to register an event.+The ''[[xref>register()]]'' method is used to subscribe an event. The following code shows a generic version to register an event.
 <code php> <code php>
 /** /**
Line 39: Line 39:
  * @return not required  * @return not required
  */  */
-function register(Doku_Event_Handler $controller) { +public function register(Doku_Event_Handler $controller) { 
-    $controller->register_hook(<EVENT NAME>, <EVENT ADVISE>, $this, <event handler function>, <parameters to be passed to event handler>);+    $controller->register_hook(<EVENT NAME>, <EVENT ADVISE>, $this, <event handler function>, <parameter to be passed to event handler>,<sequence number>);
 } }
 </code> </code>
Line 49: Line 49:
   - ''$this'': An object reference to your action class containing the ''<event handler function>'', usually ''$this''.   - ''$this'': An object reference to your action class containing the ''<event handler function>'', usually ''$this''.
   - ''<event handler function>'': Name of the function to handle the event as string.   - ''<event handler function>'': Name of the function to handle the event as string.
-  - ''<parameters>'': this will passed directly and unchanged to your ''<event handler function>''.+  - ''<parameter>'': (optional) parameter will passed directly and unchanged to your ''<event handler function>''. 
 +  - ''<sequence number>'': (optional) used to affect the order in which hooks are executed. Defaults to 0. It is recommended to use ranges of sequence numbers and avoid +/- PHP_INT_MAX: 
 + 
 +|  -3999 - -3000  | for "very early" | 
 +|  -2999 - -2000  | for "earlier" | 
 +|  -1999 - -1000  | for "early" | 
 +|  -999 - -1  | for "earlier than default" | 
 +|  0  | default | 
 +|  1 - 999  | for "later than default" | 
 +|  1000 - 1999  | for "late" | 
 +|  2000 - 2999  | for "later" | 
 +|  3000 - 3999  | for "very late" | 
 ===== <event handler>() method ===== ===== <event handler>() method =====
  
-Have as many as necessary, can be given any name not already in use in this plugin or its ancestor classes. This function must be public. It will be called by DokuWikis event controller.+Have as many as necessary, can be given any name not already in use in this plugin or its ancestor classes. This function must be public. It will be called by DokuWiki's event controller.
  
 The passed arguments are: The passed arguments are:
Line 68: Line 80:
  * @return   not required  * @return   not required
  */  */
-public function <event_handler>(Doku_Event &$event, $param) {+public function <event_handler>(Doku_Event $event, $param) {
      // custom script statements ...      // custom script statements ...
 } }
Line 86: Line 98:
  
 Here some examples: Here some examples:
-  * Below: [[#Sample Action Plugin - add always a JavaScript file |Sample Action Plugin]] -- include javascript file in all pages +  * Below: [[#Sample: Add always a JavaScript file |Sample Action Plugin]] -- include javascript file in all pages 
-  * Below: [[#Sample Action Plugin - add toolbar button|Sample Action Plugin]] -- insert button in toolbar+  * Below: [[#Sample: Add toolbar button|Sample Action Plugin]] -- insert button in toolbar
   * Examples of [[Event handlers code]]    * Examples of [[Event handlers code]] 
     * [[event_handlers_code#eventCheck Plugin]] -- plugin to register all event and call them     * [[event_handlers_code#eventCheck Plugin]] -- plugin to register all event and call them
Line 95: Line 107:
   * Dumps of [[Event Objects]] -- examples of event objects for some events   * Dumps of [[Event Objects]] -- examples of event objects for some events
   * Implementation of a custom [[Section Editor]]   * Implementation of a custom [[Section Editor]]
 +  * [[devel:plugin_programming_tips#Handle JSON ajax request]]
  
  
Line 120: Line 133:
      * Register its handlers with the DokuWiki's event controller      * Register its handlers with the DokuWiki's event controller
      */      */
-    function register(Doku_Event_Handler $controller) {+    public function register(Doku_Event_Handler $controller) {
         $controller->register_hook('TPL_METAHEADER_OUTPUT', 'BEFORE', $this,         $controller->register_hook('TPL_METAHEADER_OUTPUT', 'BEFORE', $this,
                                    '_hookjs');                                    '_hookjs');
Line 130: Line 143:
      * @author Samuele Tognini <samuele@cli.di.unipi.it>      * @author Samuele Tognini <samuele@cli.di.unipi.it>
      */      */
-    function _hookjs(&$event, $param) {+    public function _hookjs(Doku_Event $event, $param) {
         $event->data['script'][] = array(         $event->data['script'][] = array(
                             'type'    => 'text/javascript',                             'type'    => 'text/javascript',
Line 156: Line 169:
 if (!defined('DOKU_INC')) die(); if (!defined('DOKU_INC')) die();
  
-class action_plugin_actionexample extends DokuWiki_Action_Plugin {+class action_plugin_example extends DokuWiki_Action_Plugin {
  
     /**     /**
      * Register the eventhandlers      * Register the eventhandlers
      */      */
-    function register(Doku_Event_Handler $controller) {+    public function register(Doku_Event_Handler $controller) {
         $controller->register_hook('TOOLBAR_DEFINE', 'AFTER', $this, 'insert_button', array ());         $controller->register_hook('TOOLBAR_DEFINE', 'AFTER', $this, 'insert_button', array ());
     }     }
Line 168: Line 181:
      * Inserts the toolbar button      * Inserts the toolbar button
      */      */
-    function insert_button(& $event, $param) {+    public function insert_button(Doku_Event $event, $param) {
         $event->data[] = array (         $event->data[] = array (
             'type' => 'format',             'type' => 'format',
devel/action_plugins.txt · Last modified: 2023-09-01 23:52 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