====== Actionプラグイン======
[[devel:Action Plugins]] はDokuWikiの[[devel:events|イベント]]処理ができるプラグインで、DokuWiki内で発生するイベントを捕捉し、どんな部分でもカスタマイズ／拡張したりできるように設計されています。

===== 説明 =====

Actionプラグインは、DokuWiki内の主要な処理が行われる前にロードされます。ロードされるとそのプラグインの''register()''が呼び出され、これによってさまざまなイベントにイベントハンドラーに登録する機会が与えられます。あるイベントが発生すると、そのイベントに登録されたすべてのイベントハンドラーが（順不同で）呼び出され、そのイベントオブジェクトの参照が渡されます。そのイベントハンドラーはそのイベントデータに基づいた処理（Action)を行うことができます。処理としては、そのイベントオブジェクトを変更したり、イベント後に必要な処理を行ったりできます。イベントシステムについて詳しく知るには、[[devel:events]]ページを参照してください。

===== 技術的なこと=====

Actionプラグインは、他のプラグイン型同様、基本的なフォーマットや命名法に従います。

  * プラグインは''lib/plugins''の中のプラグインディレクトリに配置する。
  * actionプラグインは、''action.php''という名前で配置しなければならない。もしくは、''action''というサブディレクトリを作成して、その中に配置する。これについては[[ja:devel:Plugin File Structure|プラグインのファイル構造]]を参照。
  * Actionプラグインは一つのクラスから成り、''action_plugin_<プラグイン名>''という一つのクラスで、基底クラス''DokuWiki_Action_Plugin''を継承する。（このクラスは''lib/plugins/action.php''にある）　Actionプラグインが''action''サブディレクトリにある場合はクラスの名前は''action_plugin_<プラグイン名>_<actionプラグインのファイル名>''(ファイル名は.phpを除いた部分）となる。
  * プラグインは最も基本と成る基底クラス''DokuWiki_Plugin''を継承しているので、プラグイン情報やローカライズといったメカニズムはすべて利用できる。
  * プラグインは２つのメソッド、''getInfo()''と''register()''を必ず実装していなければならない。
  * 外部のライブラリはプラグインが必要とするときかコンストラクタでロードされなければならない。（クラス定義外の）ファイルの先頭においてはいけない。

==== getInfo() ====
**必須なメソッド**
<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() ====
**必須なメソッド**
<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(Doku_Event_Handler $controller) {
      $controller->register_hook(<EVENT NAME>, <EVENT ADVISE>, $this, <event handler function>, <parameters to be passed to event handler>);
    }
</code>

==== <event handler>() =====
**オプション** 
これは必要な分だけ用意し、このプラグインや親クラスで使われていない名前で定義する。

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

===== 例 =====

ActionプラグインはDokuWikiの挙動を多くの面から変更し、場合によってはページの構文とは独立した処理もできます。DokuWikiの挙動を変更するために、DokuWiki内部ではさまざまなイベントを発生させます。あなたのActionプラグインはそのDokuWiki内部で発生したイベントにイベントハンドラーとしてメソッドを登録し、そのデータを取得・変更することができるのです。


イベントについては、つぎのページを参照してください。
  * [[events]]
  * [[events list]]
  * [[event handlers]]


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

すべてのページにJavaScriptリンクを挿入するプラグインです。
  * [[events_list#TPL_METAHEADER_OUTPUT]]イベントに''BEFORE''で登録します。
  * JavaScript情報を"script"メタヘッダ配列に追加します。

<code php action.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(Doku_Event_Handler $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_PLUGIN.'example/example.js');
    }
}</code>

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

編集時のツールバーにボタンを追加挿入します。
  * [[events_list#toolbar_define|TOOLBAR_DEFINE]]イベントに''AFTER''で登録します。
  * ボタン定義をイベントデータに追加します。

<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(Doku_Event_Handler $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>