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

[[devel: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.

===== Description =====

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.

===== Technical =====

Action plugins follow the same basic format and naming convention as the other DokuWiki plugin types.

  * each plugin is located in its own directory within ''lib/plugins''
  * an action plugin should be called ''action.php'', or if located in the sub-directory ''action'', it can be called anything, see [[devel:Plugin File Structure]].
  * an action plugin consists of a single class ''action_plugin_<plugin name>'' which extends the base class ''DokuWiki_Action_Plugin'', found in ''lib/plugins/action.php''. If the action plugin file is in the ''action'' sub-directory of the plugin folder then the class will need to be ''action_plugin_<plugin name>_<action plugin filename>'' (where action_plugin_filename does not include the '.php' extension).
  * the plugin is provided with standard introspection, localisation and configuration functions via the ultimate base class, ''DokuWiki_Plugin'', found in ''inc/plugin.php'', see [[devel:Common Plugin Functions]].
  * the plugin must declare two methods, ''getInfo()'' and ''register()''.
  * external libs must be loaded at the time the plugin needs them or in the constructor and not at the top of the file

==== getInfo() ====
**required**
<code php>
    function getInfo(){
      return array(
        'author' => '<plugin author name>',
        'email'  => '<plugin author contact email address>',
        'date'   => '<date applicable to this version of the plugin>',
        'name'   => '<the plugin\'s name',
        'desc'   => '<brief description of what the plugin does (multiline acceptable)',
        'url'    => '<plugin homepage: a URL to find more information on the plugin>',
      );
    }
</code>

==== register() ====
**required**
<code php>
    /**
     * plugin should use this method to register its handlers with the DokuWiki's event controller
     *
     * @param    $controller   DokuWiki's event controller object. Also available as global $EVENT_HANDLER
     *
     * @return   not required
     */
    function register(&$controller) {
      $controller->register_hook(<EVENT NAME>, <EVENT ADVISE>, $this, <event handler function>, <parameters to be passed to event handler>);
    }
</code>

==== <event handler>() =====
**optional** have as many as necessary, can be given any name not already in use in this plugin or its ancestor classes
<code php>
    /**
     * custom event handler
     *
     * @param    $param   (mixed)   the parameters passed to register_hook when this handler was registered
     * @param    $event   (object)  event object by reference
     *
     * @return   not required
     */
    function <event_handler>(&$event, $param) {
      // custom script statements ...
    }
</code>

===== Examples =====

Action plugins 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.

To learn more about events, read the following pages:

  * [[events]]
  * [[events list]]
  * [[event handlers]]


==== Sample action plugin 1 ====

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>
<?php
/**
 * Example Action Plugin:   Example Component.
 * 
 * @author     Samuele Tognini <samuele@cli.di.unipi.it>
 */
 
if(!defined('DOKU_INC')) die();
if(!defined('DOKU_PLUGIN')) define('DOKU_PLUGIN',DOKU_INC.'lib/plugins/');
require_once(DOKU_PLUGIN.'action.php');
 
class action_plugin_example extends DokuWiki_Action_Plugin {
 
  /**
   * return some info
   */
  function getInfo(){
    return array(
		 'author' => 'Me name',
		 'email'  => 'myname@example.org',
		 'date'   => '2006-12-17',
		 'name'   => 'Example (action plugin component)',
		 'desc'   => 'Example action functions.',
		 'url'    => 'http://www.example.org',
		 );
  }
    
  /**
   * Register its handlers with the DokuWiki's event controller
   */
  function register(&$controller) {
    $controller->register_hook('TPL_METAHEADER_OUTPUT', 'BEFORE',  $this, '_hookjs');
  }
  
  /**
   * Hook js script into page headers.
   *
   * @author Samuele Tognini <samuele@cli.di.unipi.it>
   */
  function _hookjs(&$event, $param) {
	$event->data["script"][] = array ("type" => "text/javascript",
                                          "charset" => "utf-8",
					  "_data" => "",
					  "src" => DOKU_BASE."lib/plugins/example/example.js"
				          );
  }
}
</code>




==== Sample Action Plugin 2 ====

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>
<?php
/**
 * Example Action Plugin: Inserts a button into the toolbar
 *
 * @author Gina Haeussge <osd@foosel.net>
 */

if (!defined('DOKU_INC')) die();
if (!defined('DOKU_PLUGIN')) define('DOKU_PLUGIN', DOKU_INC . 'lib/plugins/');
require_once (DOKU_PLUGIN . 'action.php');

class action_plugin_actionexample extends DokuWiki_Action_Plugin {

    /**
     * Return some info
     */
    function getInfo() {
        return array (
            'author' => 'Some name',
            'email' => 'foo@bar.org',
            'date' => '2007-04-05',
            'name' => 'Toolbar Action Plugin',
            'desc' => 'Inserts a button into the toolbar',
            'url' => 'http://www.example.com/plugin/toolbar',
        );
    }

    /**
     * Register the eventhandlers
     */
    function register(&$controller) {
        $controller->register_hook('TOOLBAR_DEFINE', 'AFTER', $this, 'insert_button', array ());
    }

    /**
     * Inserts the toolbar button
     */
    function insert_button(& $event, $param) {
        $event->data[] = array (
            'type' => 'format',
            'title' => $this->getLang('qb_abutton'),
            'icon' => '../../plugins/actionexample/abutton.png',
            'open' => '<abutton>',
            'close' => '</abutton>',
        );
    }

}
</code>