Actionプラグイン

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

説明

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

技術的なこと

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

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

getInfo()

必須なメソッド

    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>',
      );
    }

register()

必須なメソッド

    /**
     * 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>);
    }

<event handler>()

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

    /**
     * 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 ...
    }

例

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

イベントについては、つぎのページを参照してください。

Sample action plugin 1

すべてのページにJavaScriptリンクを挿入するプラグインです。

TPL_METAHEADER_OUTPUTイベントにBEFOREで登録します。
JavaScript情報を“script”メタヘッダ配列に追加します。

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');
    }
}

Sample Action Plugin 2

編集時のツールバーにボタンを追加挿入します。

TOOLBAR_DEFINEイベントにAFTERで登録します。
ボタン定義をイベントデータに追加します。

<?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>',
        );
    }
 
}

目次