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
devel:action_plugins [2017-08-18 17:47] – Correct misspelling 'class action_plugin_actionexample' 50.226.69.58devel:action_plugins [2023-09-01 23:52] (current) – Klap-in
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 [ //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.+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 in ascending order of the $seq number used to register them (Since release 2014-05-05 "Ponder Stibbons", before it was in no particular order) and passed the Event object. 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 12: Line 14:
 An Action Plugin //Example// needs: An Action Plugin //Example// needs:
   * class name  ''action_plugin_example''   * class name  ''action_plugin_example''
-  * which extends [[xref>DokuWiki_Action_Plugin]]((defined in ''lib/plugins/action.php'')). +  * which extends [[xref>ActionPlugin]]((defined in ''lib/Extension/ActionPlugin.php'', before called ''DokuWiki_Action_Plugin'' which is still available as alias)). 
   * to be stored in a file ''lib/plugins/example/action.php''.   * to be stored in a file ''lib/plugins/example/action.php''.
 Moreover, a [[plugin_info|plugin.info.txt]] file is needed. For full details of plugins and their files and how to create more action components refer to [[plugin file structure]]. Moreover, a [[plugin_info|plugin.info.txt]] file is needed. For full details of plugins and their files and how to create more action components refer to [[plugin file structure]].
Line 18: Line 20:
   * The plugin must declare one method ''register()'' and some handler that is registered there.   * The plugin must declare one method ''register()'' and some handler that is registered there.
   * External libs must be loaded at the time the plugin needs them or in the constructor and not at the top of the file   * External libs must be loaded at the time the plugin needs them or in the constructor and not at the top of the file
 +
 ==== Required methods ==== ==== Required methods ====
  
 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(EventHandler $controller)''** Use this method to register your handlers with the DokuWiki's event controller 
-  * **''<event handler>(Doku_Event $event, $param)''** Your event handler(s), that perform your actions when they are triggered.+  * **''<event handler>(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 33: Line 36:
 <code php> <code php>
 /** /**
- * plugin should use this method to register its handlers with the DokuWiki's event controller+ * plugin should use this method to register its handlers with the DokuWiki's  
 + * event controller
  *  *
- * @param Doku_Event_Handler $controller DokuWiki's event controller object. Also available as global $EVENT_HANDLER + * @param EventHandler $controller DokuWiki's event controller object.  
- * + *                                 Also available as global $EVENT_HANDLER 
- * @return not required+ * @return void not required
  */  */
-public function register(Doku_Event_Handler $controller) { +public function register(EventHandler $controller) { 
-    $controller->register_hook(<EVENT NAME>, <EVENT ADVISE>, $this, <event handler function>, <parameter to be passed to event handler>,<sequence number>);+    $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 56:
   - ''$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.
-  - ''<parameter>'': (optional) parameter will passed directly and unchanged to your ''<event handler function>''.+  - ''<parameter>'': (optional) parameter will passed directly and unchanged to your ''<event handler function>(Event $event, $parameter)'' as second argument.
   - ''<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:   - ''<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:
  
Line 65: Line 72:
  
 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. 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: 
-  - ''$event'': The event object. Further information on the passed event object can be found on the [[devel:events#event_object|Event page]]. 
-  - ''$param'': Data passed to the ''register_hook()'' function, when this handler was registered. 
  
 <code php> <code php>
Line 74: Line 77:
  * custom event handler  * custom event handler
  *  *
- * @param Doku_Event $event  event object by reference + * @param Event $event event object by reference 
- * @param mixed      $param  the parameters passed to register_hook when this  + * @param mixed $param (optional) the parameters passed to register_hook()  
- *                           handler was registered+ *                     when this handler was registered
  *  *
- * @return   not required+ * @return void not required
  */  */
-public function <event_handler>(Doku_Event $event, $param) {+public function <event_handler>(Event $event, $param) {
      // custom script statements ...      // custom script statements ...
 } }
 </code> </code>
 +The passed arguments are:
 +  - ''$event'': The event object. Further information on the passed event object can be found on the [[devel:events#event_object|Event page]].
 +  - ''$param'': Data passed to the ''register_hook()'' function, when this handler was registered. Can be left out if not used.
  
 ===== Further reading ===== ===== Further reading =====
Line 117: Line 123:
   * Add javascript information to "script" meta headers as array type.   * Add javascript information to "script" meta headers as array type.
  
-<code php action.php>+<code php lib/plugins/example/action.php>
 <?php <?php
 +
 +use dokuwiki\Extension\ActionPlugin;
 +use dokuwiki\Extension\EventHandler;
 +use dokuwiki\Extension\Event;
 +
 /** /**
- * Example Action Plugin:   Example Component.+ * Example Action Plugin: Example Component. 
  *  *
- * @author     Samuele Tognini <samuele@cli.di.unipi.it>+ * @author Samuele Tognini <samuele@cli.di.unipi.it>
  */  */
  
-if(!defined('DOKU_INC')) die(); +class action_plugin_example extends ActionPlugin {
- +
- +
-class action_plugin_example extends DokuWiki_Action_Plugin {+
  
     /**     /**
      * Register its handlers with the DokuWiki's event controller      * Register its handlers with the DokuWiki's event controller
 +     * 
 +     * @param EventHandler $controller event controller object
      */      */
-    public function register(Doku_Event_Handler $controller) { +    public function register(EventHandler $controller) { 
-        $controller->register_hook('TPL_METAHEADER_OUTPUT', 'BEFORE', $this, +        $controller->register_hook('TPL_METAHEADER_OUTPUT', 'BEFORE',  
-                                   '_hookjs');+                                   $this, 'hookJsScript');
     }     }
  
     /**     /**
      * Hook js script into page headers.      * Hook js script into page headers.
-     *+     *  
 +     * @param Event $event event object 
 +     * 
      * @author Samuele Tognini <samuele@cli.di.unipi.it>      * @author Samuele Tognini <samuele@cli.di.unipi.it>
      */      */
-    public function _hookjs(Doku_Event $event, $param) { +    public function hookJsScript(Event $event) { 
-        $event->data['script'][] = array( +        $event->data['script'][] = [ 
-                            'type'    => 'text/javascript', +            'type'    => 'text/javascript', 
-                            'charset' => 'utf-8', +            'charset' => 'utf-8', 
-                            '_data'   => '', +            '_data'   => '', 
-                            'src'     => DOKU_PLUGIN.'example/example.js');+            'src'     => DOKU_PLUGIN . 'example/example.js' 
 +        ];
     }     }
-}</code>+} 
 +</code>
  
 ==== Sample: add toolbar button ==== ==== Sample: add toolbar button ====
Line 159: Line 174:
   * adds a button definition to the event's ''data''   * adds a button definition to the event's ''data''
  
-<code php addbuton.php>+<code php lib/plugin/example/action.php>
 <?php <?php
 +
 +use dokuwiki\Extension\ActionPlugin;
 +use dokuwiki\Extension\EventHandler;
 +use dokuwiki\Extension\Event;
 +
 /** /**
  * Example Action Plugin: Inserts a button into the toolbar  * Example Action Plugin: Inserts a button into the toolbar
Line 167: Line 187:
  */  */
  
-if (!defined('DOKU_INC')) die(); +class action_plugin_example extends ActionPlugin {
- +
-class action_plugin_example extends DokuWiki_Action_Plugin {+
  
     /**     /**
-     * Register the eventhandlers+     * Register the event handlers 
 +     *  
 +     * @param EventHandler $controller DokuWiki's event controller object
      */      */
-    public function register(Doku_Event_Handler $controller) { +    public function register(EventHandler $controller) { 
-        $controller->register_hook('TOOLBAR_DEFINE', 'AFTER', $this, 'insert_button', array ());+        $controller->register_hook('TOOLBAR_DEFINE', 'AFTER',  
 +                                   $this, 'insert_button', []);
     }     }
  
     /**     /**
      * Inserts the toolbar button      * Inserts the toolbar button
 +     * 
 +     * @param Event $event event object
 +     * @param mixed $param [the parameters passed as fifth argument to 
 +     *                      register_hook() when this handler was registered, 
 +     *                      here just an empty array..] 
      */      */
-    public function insert_button(Doku_Event $event, $param) { +    public function insert_button(Event $event, $param) { 
-        $event->data[] = array (+        $event->data[] = [
             'type' => 'format',             'type' => 'format',
             'title' => $this->getLang('qb_abutton'),             'title' => $this->getLang('qb_abutton'),
Line 188: Line 214:
             'open' => '<abutton>',             'open' => '<abutton>',
             'close' => '</abutton>',             'close' => '</abutton>',
-        );+        ];
     }     }
  
devel/action_plugins.1503071276.txt.gz · Last modified: 2017-08-18 17:47 by 50.226.69.58
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