DokuWiki のプラグイン開発に関する情報

DokuWiki をなるべくスマートにカスタマイズしようとすると（設定変更以上のことをやりたい場合です）、テンプレートかプラグインを自作せざるを得ません。他の方法があまり用意されていないためです。

テンプレートをカスタマイズするなら、デフォルトのテンプレート “dokuwiki” (lib/tpl/dokuwiki/ディレクトリ) をコピーして修正していくのが早いですが、プラグインの場合は簡単なものなら雛形に頼るほどでもありません。本ページに、最初の取っ掛かりになりそうな情報を書いておきます。

1. 公式ドキュメント

項目	URL
DokuWiki の開発について	development (日本語訳)
プラグインの開発	devel:plugins (日本語訳)
プラグイン情報 (plugin.info.txt)	devel:plugin_info (日本語訳)
プラグインのファイル構造	devel:plugin_file_structure (日本語訳)
Common Plugin Functions	devel:common_plugin_functions
Actionプラグイン	devel:action_plugins (日本語訳) Event System Event Reference List DokuWiki Event Handlers
Helperプラグイン	devel:helper_plugins (ja:devel:helper_plugins)
Syntax Plugins	devel:syntax_plugins (日本語訳)
Renderer Plugins	devel:renderer_plugins
Admin Plugins	devel:admin_plugins
Remote Plugins	devel:remote_plugins
Authentication Plugins	devel:auth_plugins
CLI Plugins	devel:cli_plugins
Tips for programming plugins	devel:plugin_programming_tips

2. プラグイン開発に関するメモ

1. プラグインには種類がある

DokuWiki のプラグインは5種類ありますが、取っ掛かりとしては以下の2つが分かりやすいと思いました。

2. プラグインを作るとは、PHP のクラスを実装することである

プラグインを作るには、予め用意されたクラスを継承したクラスを１つまたは複数実装します。

3. プラグインとして用意するディレクトリ・ファイルと PHPクラス

1つだけクラスを作る場合

ファイル・ディレクトリ

<dokuwiki>/lib/plugins/<plugin name>/<plugin type>.php

プラグインのクラス名

<plugin type>_plugin_<plugin name>

どのクラスを継承するのかについては、各プラグインのドキュメントに書いてあります。
（例えば、動作プラグインなら ja:devel:action_plugins [DokuWiki] に載っています）

複数のクラスを作る場合

ファイル・ディレクトリ

<dokuwiki>/lib/plugins/<plugin name>/<plugin type>/<filename>.php

プラグインのクラス名

<plugin type>_plugin_<plugin name>_<filename>

参考

• devel:plugin_file_structure [DokuWiki]

4. PHPクラスに実装するメソッド

これも、各プラグインのドキュメントに書いてあります。
（例えば、動作プラグインなら ja:devel:action_plugins [DokuWiki] に載っています）

5. 最低限必要なファイル

1つだけのクラスの動作プラグインを作る場合、必要最低限なファイルは以下となります。たったの2つです。

<plugin name>
  │
  ├── action.php
  └── plugin.info.txt

plugin.info.txt にはプラグインについてのメタ情報を書いておきます。
（参考：devel:plugin_info [DokuWiki]（日本語訳））

この他にも、JavaScript の処理も書きたいのであれば script.js ファイルを追加するだとか、内容によっては追加するファイルが決まっているものがあります。詳細は、devel:plugin_file_structure [DokuWiki] を参照してください。

3. Action Plugins

CSS_STYLES_INCLUDED イベント

CSSファイルを追加で読み込ませるコード例

 :
class action_plugin_xxxxx extends DokuWiki_Action_Plugin {
 :
    public function register(Doku_Event_Handler $controller) {
        $controller->register_hook(
            'CSS_STYLES_INCLUDED', 'BEFORE', $this, '_hookcss');
    }
 :
    public function _hookcss(&$event, $param) {
        $event->data['files'][DOKU_PLUGIN.'css/xxx.css'] = DOKU_BASE.'lib/plugins/xxxxx/';
    }
 :

• $event->data['files'] に対して、以下のようにして CSS ファイルを追加する。
  • キー：サーバー上でのファイルパス
  • 値：ドキュメントルートからこのプラグインまでのパス
• lib/exe/css.php により、他の CSS とファイルとまとめられ更に圧縮されて出力される。

読み込ませるCSSファイル内の画像URLの書き方

以下のような、url() の部分でのパスの書き方

 :
  background: url(images/xxx.png) left 48% no-repeat;
 :

• このプラグインディレクトリからの相対パスで画像ファイルを指定する。

JS_SCRIPT_LIST イベント

JavaScriptファイルを追加で読み込ませるコード例

 :
class action_plugin_xxxxx extends DokuWiki_Action_Plugin {
 :
    public function register(Doku_Event_Handler $controller) {
        $controller->register_hook(
            'JS_SCRIPT_LIST', 'BEFORE', $this, '_hookjs');
    }

    public function _hookjs(&$event, $param) {
        $event->data[] = DOKU_PLUGIN.'xxxxx/js/xxx.js';
    }
 :

• こちらは、$event->data 配列に、JavaScript ファイルパスを追加するだけ。
• lib/exe/js.php により、他の JavaScript とファイルとまとめられ更に圧縮されて出力される。

JavaScript の実行順

1. プラグインディレクトリ直下の script.js
2. JS_SCRIPT_LIST イベントで $event->data に追加する JavaScript
3. DOMCOntentLoaded イベントが発火
4. load イベントが発火