====== TPL_ACTION_GET ======

---- dataentry event ----
Description:    Add or modify action link properties
DefaultAction:  Return properties of core action link or the notice that action is unknown
Preventable:    yes # can the event be prevented? yes or no
Added_dt:       2015-08-05
Removed_dt:     2017-09-01
----

This event is signalled by [[xref>tpl_get_action()]] in [[xref>inc/template.php]] when properties of core actions are collected just before the properties are returned to functions [[xref>tpl_button()]] or [[xref>tpl_actionlink()]] that generate the html of a button or action link respectively with these properties. The handlers can use it to allow custom actions and to modify the properties of the action link.

Note: this event was removed from the [[template:dokuwiki|DokuWiki Template]] at 2017-09-01 and replaced by [[MENU_ITEMS_ASSEMBLY]]. Other templates may still use this event.

===== Passed Data =====

The passed [[xref>Doku_Event]] object has the field ''$data''.

The ''$data'' field is an array with the entries:
  * $data['accesskey'] -- Character used for [[:accesskeys]]
  * $data['type'] -- Action name e.g. ''edit'', ''recent'', ''login'', etc
  * $data['id'] -- Page id (often current)
  * $data['method'] -- HTTP method: 'get' or 'post'
  * $data['params'] -- Associated array of url parameters
  * $data['nofollow'] -- Whether to set the rel='nofollow' attribute
  * $data['replacement'] -- Replacement for ''%s'' placeholder in the caption
For handling of these properties see ''tpl_button()'' or ''tpl_actionlink()''.

Use ''preventDefault()'' to skip DokuWiki's default notice about unknown action.
If the default properties are fine for a custom action, calling ''preventDefault()'' is enough to create your own link. But you could also modify the properties to your needs by changing the entries of the ''$data'' array.


=====Example=====
An use case is in combination with the pagetools/usertools/sitetools event. 

<code php>
<?php
// must be run within Dokuwiki
if(!defined('DOKU_INC')) die();

/**
 * Add link to sitetool
 */
class action_plugin_example extends DokuWiki_Action_Plugin {

    /**
     * Register its handlers with the DokuWiki's event controller
     * 
     * @param Doku_Event_Handler $controller
     */
    public function register(Doku_Event_Handler $controller) {
        $controller->register_hook('TEMPLATE_SITETOOLS_DISPLAY', 'BEFORE', $this, 'add_menu_item');
        $controller->register_hook('TPL_ACTION_GET', 'BEFORE', $this, 'define_action');
    }

    /**
     * Add an item to sitetools
     * Can use `tpl_action()` because dokuwiki accepts 'youraction' by the define_action() handler below.
     * 
     * @param Doku_Event $event
     * @param $param
     */
    public function add_menu_item(Doku_Event $event, $param) {
        global $lang;
        $lang['btn_youraction'] = $this->getLang('youraction');
        
        $event->data['items']['youraction'] = tpl_action('youraction', true, 'li', true);
    }

    /**
     * Accepts the 'youraction' action, while using the default action link properties.
     * Entries of $event->data can be modified eventually.
     * 
     * @param Doku_Event $event
     * @param $param
     */
    public function define_action(Doku_Event $event, $param) {
        if ($event->data['type'] != 'youraction') {
            return;
        }

        $event->preventDefault();
    }
}
</code>


===== See also =====

  * [[codesearch>TPL_ACTION_GET|Code related to this event]] used in any DokuWiki's files, plugins and templates
  * [[devel:Action Plugins]]
  * [[devel:Events]]
  * [[devel:event:TEMPLATE_PAGETOOLS_DISPLAY]], [[devel:event:TEMPLATE_SITETOOLS_DISPLAY]] and [[devel:event:TEMPLATE_USERTOOLS_DISPLAY]] let you modify pagetools, sitetools or usertools.