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 (日本語訳) |
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つが分かりやすいと思いました。
動作プラグイン (Action Plugins)
- DokuWikiの各動作で発生するイベントに独自の処理を追加することができる。
ヘルパープラグイン (Helper Plugins)
- 各プラグインから呼び出せる共通機能を実装する。
2. プラグインを作るとは、PHP のクラスを実装することである
プラグインを作るには、予め用意されたクラスを継承したクラスを1つまたは複数実装します。
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>
参考
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 の実行順
- プラグインディレクトリ直下の
script.js
JS_SCRIPT_LIST
イベントで$event->data
に追加する JavaScript- DOMCOntentLoaded イベントが発火
- load イベントが発火