====== Action Plugins ======

[[plugintype>4#extension__table|Action plugins]] are designed to work with DokuWiki [[devel:events]] to allow for customisation/extension of any part of DokuWiki that signals its activity using events.
They are a way to modify many aspects of how DokuWiki behaves in certain cases independent of a page's syntax. To be able to modify a DokuWiki internal behavior it needs to trigger an event. Your action plugin can register as a handler for such an event and then work with the given event data.

===== 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 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 =====

An Action Plugin //Example// needs:
  * class name  ''action_plugin_example''
  * 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''.
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]].

  * 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

==== Required methods ====

An action plugin requires at least two methods:
  * **''register(EventHandler $controller)''** Use this method to register your handlers with the DokuWiki's event controller
  * **''<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.

==== Inherited methods ====
  * See [[devel:common plugin functions]] for inherited function available to all plugins. e.g. localisation, configuration and introspection.

===== register() method=====
The ''[[xref>register()]]'' method is used to subscribe an event. The following code shows a generic version to register an event.
<code php>
/**
 * plugin should use this method to register its handlers with the DokuWiki's 
 * event controller
 *
 * @param EventHandler $controller DokuWiki's event controller object. 
 *                                 Also available as global $EVENT_HANDLER
 * @return void not required
 */
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>);
}
</code>

The ''[[xref>register_hook|$controller->register_hook()]]'' function is used to register the event. The parameters are:
  - ''<EVENT NAME>'': Name of the event. All available events can be found at [[devel:events_list|the Event Reference List]].
  - ''<EVENT ADVISE>'': can be either ''BEFORE'' or ''AFTER''. This determines when you want to invoke the given event.
  - ''$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.
  - ''<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:

|  -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 =====

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.

<code php>
/**
 * custom event handler
 *
 * @param Event $event event object by reference
 * @param mixed $param (optional) the parameters passed to register_hook() 
 *                     when this handler was registered
 *
 * @return void not required
 */
public function <event_handler>(Event $event, $param) {
     // custom script statements ...
}
</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 =====

  * [[Events]]
  * [[Events list]]
  * [[Event handlers]]
  * [[plugintype>4#extension__table|Available action plugins]]
  * [[Plugin programming tips]]
  * [[plugins|Plugin Development]]


===== Examples =====

Here some examples:
  * Below: [[#Sample: Add always a JavaScript file |Sample Action Plugin]] -- include javascript file in all pages
  * Below: [[#Sample: Add toolbar button|Sample Action Plugin]] -- insert button in toolbar
  * Examples of [[Event handlers code]] 
    * [[event_handlers_code#eventCheck Plugin]] -- plugin to register all event and call them
    * [[event_handlers_code#Caching]] -- selective disabling
    * [[event_handlers_code#Headers and Footers]] -- add your own stuff to top and bottom of page
    * [[event_handlers_code#Content Modification]] -- points event that handles directly wikicontent
  * Dumps of [[Event Objects]] -- examples of event objects for some events
  * Implementation of a custom [[Section Editor]]
  * [[devel:plugin_programming_tips#Handle JSON ajax request]]


==== Sample: add always a JavaScript file ====

Insert a javascript script link in all pages.

  * Register the [[events_list#TPL_METAHEADER_OUTPUT]] event, with a before EVENT_ADVISE.
  * Add javascript information to "script" meta headers as array type.

<code php lib/plugins/example/action.php>
<?php

use dokuwiki\Extension\ActionPlugin;
use dokuwiki\Extension\EventHandler;
use dokuwiki\Extension\Event;

/**
 * Example Action Plugin: Example Component.

 *
 * @author Samuele Tognini <samuele@cli.di.unipi.it>
 */

class action_plugin_example extends ActionPlugin {

    /**
     * Register its handlers with the DokuWiki's event controller
     * 
     * @param EventHandler $controller event controller object
     */
    public function register(EventHandler $controller) {
        $controller->register_hook('TPL_METAHEADER_OUTPUT', 'BEFORE', 
                                   $this, 'hookJsScript');
    }

    /**
     * Hook js script into page headers.
     * 
     * @param Event $event event object
     * 
     * @author Samuele Tognini <samuele@cli.di.unipi.it>
     */
    public function hookJsScript(Event $event) {
        $event->data['script'][] = [
            'type'    => 'text/javascript',
            'charset' => 'utf-8',
            '_data'   => '',
            'src'     => DOKU_PLUGIN . 'example/example.js'
        ];
    }
}
</code>

==== Sample: add toolbar button ====

Inserts a button into the editor toolbar:

  * registers as handler for the [[events_list#toolbar_define|TOOLBAR_DEFINE]] event with an AFTER advise
  * adds a button definition to the event's ''data''

<code php lib/plugin/example/action.php>
<?php

use dokuwiki\Extension\ActionPlugin;
use dokuwiki\Extension\EventHandler;
use dokuwiki\Extension\Event;

/**
 * Example Action Plugin: Inserts a button into the toolbar
 *
 * @author Gina Haeussge <osd@foosel.net>
 */

class action_plugin_example extends ActionPlugin {

    /**
     * Register the event handlers
     * 
     * @param EventHandler $controller DokuWiki's event controller object
     */
    public function register(EventHandler $controller) {
        $controller->register_hook('TOOLBAR_DEFINE', 'AFTER', 
                                   $this, 'insert_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(Event $event, $param) {
        $event->data[] = [
            'type' => 'format',
            'title' => $this->getLang('qb_abutton'),
            'icon' => '../../plugins/actionexample/abutton.png',
            'open' => '<abutton>',
            'close' => '</abutton>',
        ];
    }

}
</code>

==== Sample: handle ajax requests ====
See [[devel:plugin_programming_tips#Handle JSON ajax request]]