プラグイン API 2005年7月27日
訳者注：

- このドキュメントの原文は以下のURLにあります。
  http://nucleuscms.org/documentation/devdocs/plugins.html
- 誤訳にお気づきの方はこちらへご連絡いただけると助かります。

注：

- このドキュメントは基本的なプラグインの書き方についての情報を提供しています。さらに質問がある方は Plugin Development Forum （日本語フォーラム）をご覧ください。
- Nucleusバージョン1.5以降に導入されたメソッドとイベントには、導入時のバージョン情報を付記しています。それらの機能を利用するときは、`getMinNucleusVersion` を適切に設定するのを忘れないでください。

# はじめに

開発者向けドキュメントの目次へ戻る

このドキュメントはNucleusプラグインの作り方についての解説です。

# 目次

- イントロダクション
- はじめてプラグインを書いてみる
- `NucleusPlugin` クラスの概要
- `<%plugin(...)%>` スキン変数
- `<%plugin(...)%>` テンプレート変数
- `action.php` を使ったアクション
- イベントとイベント登録の仕方
- オプションを保存する
- データベース・テーブル
- プラグイン管理エリアの提供
- ヘルプページの提供
- プラグイン依存チェック

# イントロダクション

Nucleusプラグインによって、誰もがNucleusの提供する機能を、Nucleus内部のPHPコードを変更することなく拡張することができます。プラグインはあるメソッドを実装したシンプルなPHPスクリプトで、Nucleusユーザー同士で簡単に交換することができます。インストールは簡単で、プラグインディレクトリにファイルをアップし、Nucleusにそれを認識させるだけです。

プラグインの利点は以下のとおりです。

- 実装について詳しくしらなくてもNucleusフレームワークに簡単に機能を追加できる
- 必要なプラグインだけをインストールでき、ページ生成にかかる時間を節約できる

すべてのプラグインファイルは `config.php` に記述されたディレクトリに置く必要があります。一般的に、それは `/your/path/nucleus/plugins/` になるでしょう。プラグインファイル名は `NP_name.php` という形式を用いることにより認識されます。プラグインによっては、追加ファイルを格納する同名のサブディレクトリや、管理エリアを必要とします。

注： プラグイン名は大文字・小文字を識別しますので、`Np_` や `np_` ではなく、`NP_` で始まることに気をつけてください。またプラグインがサブディレクトリを使用する場合は、サブディレクトリの名称はすべて小文字にします。

# はじめてプラグインを書いてみる

では、シンプルなプラグインを書いてみましょう。基本的にプラグインは、あらかじめ定義された `NucleusPlugin` クラスを継承したPHPクラスです。以下は`HelloWorld`プラグインの例です。

    <?

    class NP_HelloWorld extends NucleusPlugin
    {

    	// プラグインの名前
    	function getName()
    	{
    		return 'Hello World';
    	}

    	// プラグインの作者
    	function getAuthor()
    	{
    		return 'Wouter Demuynck';
    	}

    	// プラグインのサイトURL
    	// mailto:foo@bar.com の形式も可
    	function getURL()
    	{
    		return '../../index.html';
    	}

    	// プラグインのバージョン
    	function getVersion()
    	{
    		return '1.0';
    	}

    	// インストール済みのプラグインリストに表示される説明文
    	function getDescription()
    	{
    		return 'Just a sample plugin.';
    	}

    	function doSkinVar($skinType)
    	{
    		echo 'Hello World!';
    	}

    	function supportsFeature ($what)
    	{
    		switch ($what)
    		{
    			case 'SqlTablePrefix':
    				return 1;
    			default:
    				return 0;
    		}
    	}

    }
    ?>

1. このコードをコピーし、 `NP_HelloWorld.php` と名づけて保存し、プラグインディレクトリに置きます。最後の `?>` の後や、最初の `<?` の前にスペースがないことを確認しましょう。ところでNP は "Nucleus Plugin" って意味ですよ :-) 念のため。
2. Nucleusの管理画面を開き、Nucleusの管理＞プラグインの管理にいきます。
3. HelloWorld プラグインがインストール可能な状態になっているはずですので、インストールします。すべてがうまくいけば、インストール済みプラグインリストに追加されます。
4. あなたのスキンの１つを編集し、実際のページに表示する箇所に次の文を挿入します。

       <%HelloWorld%>

   注意：カッコ内の名称 (`HelloWorld`) は大文字小文字を識別します！
5. さて、編集したスキンから生成されるページを見てみましょう。プラグイン変数を追加した場所に "Hello World" と見えますね？

ここまではそれほど難しくなかったと思います。さらに読み進めて理解してください。

# NucleusPlugin クラスの概要

すべてのプラグインは、`NucleusPlugin` というPHPクラスを継承しなければなりません。難しそうに聞こえても心配ご無用、大丈夫です。このPHPクラスの継承によって、プラグインに必要なメソッドだけを実装でき、いくつかの補助ファンクションにアクセスでき、つまりはあなたの人生はよりラクになります。

下記は `NucleusPlugin` が提供する、再実装可能なメソッドの概要です。このクラス自身のソースコードを見たければ、`nucleus/libs/PLUGIN.php`にあります。

`NucleusPlugin` クラスの概要（再定義可能なメソッド）
メソッド名 | 説明
--- | ---
`getName()` | プラグイン名を返します。インストール済みプラグインリストに表示されます。デフォルトの実装では `Undefined` を返すため、必ず再定義されないといけません。
`getAuthor()` | プラグインの作者名を返します。インストール済みプラグインリストに表示されます。デフォルトの実装では `Undefined` を返すため、必ず再定義されないといけません。
`getURL()` | プラグインをダウンロード可能な、またはプラグインの追加情報のあるサイトのURLを返します。そのようなサイトがない場合は作者のメールアドレスへの mailto:リンクが適切です。デフォルトの実装では `Undefined` を返すため、必ず再定義されないといけません。
`getDescription()` | プラグインに関する説明文（長文）を返します。インストール済みプラグインリストに表示されます。デフォルトの実装では `Undefined` を返します。
`getVersion()` | プラグインの現在のバージョンを返します。デフォルトは `0.0` を返します。
`getMinNucleusVersion()` | (v2.0b) 最低限必要なNucleusのバージョンを返します。デフォルトは `155` (v1.55)を返します。後に導入されたプラグイン関連機能を利用している場合は、このファンクションを実装するようお願いします（例： v2.0 => 200）。ただし、Nucleus v1.55 はこのファンクションを使用しないため、新機能を利用したプラグインが（対応する前のシステムに）インストールされる可能性が残っています。
`getMinNucleusPatchLevel()` | (v3.1) 最低限必要なNucleusのバージョン(`getMinNucleusVersion`)での、最低限必要なパッチレベルを返します。デフォルトは `0` を返します。このファンクションは主に新しいプラグインの機能がNucleusの最新版のパッチによって可能になる場合に用いられます。
`init()` | プラグインを初期化します。このメソッドはプラグインオブジェクトが生成された直後に呼び出され、`plugid`属性がセットされます。デフォルトではこのメソッドは何もしません。
`doSkinVar($skinType)` | `<%plugin(...)%>` スキン変数によってプラグインが呼び出されたときにこのメソッドが呼ばれます。`$skinType` パラメータはプラグインが呼ばれた場所のスキンタイプに該当します（`item`, `archive`, ...）。パラメータが一つしかないことに混乱しないでください。複数パラメータを渡すことも可能です。`doSkinVar` メソッドの実装に関する詳細情報はこちら。デフォルトではこのメソッドはなにも出力しません。
`doTemplateVar(&$item)` | 基本的に `doSkinVar` と同じですが、今度はテンプレート内（`item header/body/footer` と `dateheader/footer`）での`<%plugin(...)%>` 変数からの呼び出しになります。デフォルトではこのメソッドはテンプレートをスキンタイプとみなして `doSkinVar` メソッドに処理を渡します。`doTemplateVar` メソッドの実装に関する詳細情報はこちら
`doTemplateCommentsVar(&$item, &$comment)` | (v2.0b) 基本的に `doSkinVar` と同じですが、今度はテンプレート内（コメント部分）での`<%plugin(...)%>` 変数からの呼び出しになります。デフォルトではこのメソッドはテンプレートをスキンタイプとみなして `doSkinVar` メソッドに処理を渡します。`doTemplateCommentsVar` メソッドの実装に関する詳細情報はこちら
`doAction($type)` | プラグインがユーザーインタラクションを求めたとき、 `action.php`を介してこのメソッドがそれを与えます。. これはNucleus自身が新しいコメントや投票を処理するのに使用するスクリプトです。正しいパラメータを用いることで、プラグインからの `doAction` メソッドを呼び出せます。`$type` はオプションのメッセージタイプに該当します。`doAction` メソッド内で、リクエストからの追加の変数にアクセスできます。デフォルトではこのメソッドがエラーメッセージをトリガーすると`'No Such Action'`という文字列を返します。`doAction` に関する詳細情報はこちら
`install()` | このメソッドはプラグインがインストールされた際に呼ばれます。データベース・テーブルの生成やプラグインオプションの生成などの初期化作業を行うことができます。デフォルトではこのメソッドは何もしません。
`unInstall()` | プラグインがアンインストールされた際に呼ばれます。この時点でデータベースに作られたプラグイン情報を消去すると良いです。デフォルトではこのメソッドは何もしません。
`getEventList()` | プラグインはイベント登録が可能です。イベントはNucleusが何かアクションを起こすたびに生成されます。たとえば、`AddItem` イベントは、このイベントを登録しているすべてのプラグインを呼び出します。呼び出されるメソッドは `event_AddItem($params)`になります。 `$params` パラメータは、例えば `AddItem` の `itemid` のような、情報フィールドを複数持つ連想配列です。デフォルトではどのイベントにも登録されていないことを示す空の配列を返します。イベントに関する詳細情報 はこちら
`getTableList()` | このメソッドはプラグインが生成したデータベース・テーブルの配列を返します。これはNucleusが提供するバックアップ機能で利用されるので、プラグインテーブルをバックアップに含めることができます。デフォルトでは空の配列を返します。
`hasAdminArea()` | プラグインが独自の管理エリアをもつ場合 1 を、そうでない場合 0 を返します。デフォルトでは `0` を返します。
`getPluginDep()` | (v3.2) プラグイン名の配列を返します。Nucleusはこれらのプラグインが前もってインストールされてない場合、プラグインのインストールを拒否します。デフォルトでは空の配列が返されます。プラグイン依存に関する詳細情報はこちら

実装可能なメソッドの次は、`NucleusPlugin` クラスが提供する、再実装すべきでない幾つかの特殊メソッドです。これらはプラグイン内で、`$this->functionName()`シンタックスを利用して呼び出します。

`NucleusPlugin` クラスの概要（再定義不可能なメソッド）
メソッド名 | 説明
--- | ---
`createOption(...)` `createBlogOption(...)`(v2.2) `createCategoryOption(...)`(v2.2) `createMemberOption(...)`(v2.2) `createItemOption(...)`(v3.2) | 新しいオプションを生成します。
`deleteOption(...)` `deleteBlogOption(...)`(v2.2) `deleteCategoryOption(...)`(v2.2) `deleteMemberOption(...)`(v2.2) `deleteItemOption(...)`(v3.2) | オプションを削除します。
`setOption(...)` `setBlogOption(...)`(v2.2) `setCategoryOption(...)`(v2.2) `setMemberOption(...)`(v2.2) `setItemOption(...)`(v3.2) | オプションに値をセットします。
`getOption(...)` `getBlogOption(...)`(v2.2) `getCategoryOption(...)`(v2.2) `getMemberOption(...)`(v2.2) `getItemOption(...)`(v3.2) | オプションの値を取得します。
`getAllBlogOptions(...)`(v2.2) `getAllCategoryOptions(...)`(v2.2) `getAllMemberOptions(...)`(v2.2) `getAllItemOptions(...)`(v3.2) | 与えられたオプションにより、すべての値（コンテクストごとの一つの値）の連想配列を返します。
`getBlogOptionTop(...)`(v3.2) `getMemberOptionTop(...)`(v3.2) `getCategoryOptionTop(...)`(v3.2) `getItemOptionTop(...)`(v3.2) | 与えられたオプションにより、すべての値のうちの最初の値を返します。
`getID()` | このプラグインのIDを返します（このIDはNucleus内部で利用されるものです）。
`getAdminURL()` | プラグインの管理エリアが置かれたURLを返します（そのような管理エリアがない場合は、この情報は無効です）。
`getDirectory()` | プラグインの追加ファイルが格納されたサーバーのファイルシステムのパスを返します（そのようなファイルがない場合は、この情報は無効です）。結果は"`.../nucleus/plugins/plugname/`"のようになります。
`getShortName()` | "NP_"部分を省き、全てを小文字にしたプラグインのクラス名を返します。この情報は `getAdminURL` と `getDirectory` で使用されます。

# スキン変数

## 解説

独自のスキン変数を生成し、`<%plugin(PlugName,parameters)%>` または `<%PlugName(parameters)%>`で呼び出すことが出来ます（すでに存在するスキン変数とかぶらない場合）。パラメータはカンマ区切りです。

スキン変数を扱うには、`doSkinVar` メソッドを実装する必要があります。いくつかの例を以下に示します。

    function doSkinVar($skinType)
    function doSkinVar($skinType, $param1, $param2)
    function doSkinVar($skinType, $skinVar, $param1, $param2)
    function doSkinVar($skinType, $skinVar, $param1 = 'default value')

- `$skinType` パラメータは、'index', 'item', 'archive', 'archivelist', 'member', 'error', 'search', 'imagepopup', 'template'のうちの一つを取ります
- `$skinVar` は、スキン変数のタイプとして解釈される実質的に最初のパラメータになります（例：`<%plugin(PlugName,VarType)%>`）。
- `doSkinVar()`（パラメータ無し）を使い、PHPファンクションの`func_get_args()`を用いてパラメータを取得することができます。引数の数の異なる、タイプの違うスキン変数を扱うときに便利です。

## ノート

- (v2.0b) グローバル変数としてパースされている `$currentSkinName` を使ってスキンの名前を取得できます。

# テンプレート変数

## 解説

テンプレートプラグイン変数はスキンプラグイン変数と同様に働きますが以下の2点が異なります。

1. スキン内ではなくテンプレート内から呼ばれます。
2. $skinTypeパラメータを取りません。代わりに現在パースされているアイテムやコメントの情報付きの追加パラメータを取ります。
   - `doTemplateVar` メソッドは `&$item` パラメータを取ります。
   - `doTemplateCommentsVar` メソッドは `&$item` と `&$comment` パラメータを取ります。
   &マークに注意！

テンプレート変数はスキン変数と同じ要領で呼ばれます（`<%plugin(PlugName,parameters)%>` または `<%PlugName(parameters)%>`）。

デフォルトでは、全てのテンプレート変数は'`template`'を`skintype`パラメータとして、`doSkinVar` メソッドに渡ります。

独自の実装を提供したい場合は、`doTemplateVar` メソッドや `doTemplateCommentsVar` メソッドを再定義する必要があります。`skintype`パラメータが無くなる以外はdoSkinVarと同様に働きます。

    function doTemplateVar(&$item)
    function doTemplateVar(&$item, $param1, $param2)
    function doTemplateVar(&$item, $type, $param1, $param2)
    function doTemplateVar(&$item, $type, $param1 = 'default value')
    function doTemplateCommentsVar(&$item, &$comment)
    function doTemplateCommentsVar(&$item, &$comment, $param1, $param2)
    function doTemplateCommentsVar(&$item, &$comment, $type, $param1, $param2)
    function doTemplateCommentsVar(&$item, &$comment, $type, $param1 = 'default value')

## ノート

- (v2.0b) グローバル変数として内部で利用される `$currentSkinName` を使ってテンプレートの名前を取得できます。

# アクション

プラグインは `action.php` を通してアクションを行うことができ、同様のスクリプトがコメントや投票の受け取りにも使用されてます。GETまたはPOSTのどちらかを通して呼び出せます。必要なパラメータは `action`（'plugin'と指定）、`name`（プラグイン名）、`type`（リクエストされたアクションの種類）です。

これらのアクションを有効にするために、`doAction($actionType)` メソッドをプラグイン内で実装する必要があります。リクエストからの追加パラメータは `requestVar('name')` で取得できます（`requestVar` はPHPが付加する magic_quotes_gpc に配慮しています）。

`doAction` メソッドが文字列を返すとき、エラーとして解釈され、エラーメッセージが表示されます。

# イベント

Nucleusプラグインはなにか重要なことが起きたときに発生するイベントに登録可能です。プラグインはイベント発生の際にアクションを実行したり、テキストを出力したりできます。

## 例

下記は `PreAddComment` イベント（blogにコメントが追加される直前に生成されるイベント）にプラグインが登録する例です。

    class NP_Acronyms extends NucleusPlugin {
      ...
      function getEventList() { return array('PreAddComment'); }
      ...
      function event_PreAddComment(&$data) {
        // 頭字語 HTML を置き換え
        $data['comment']['body'] =
            strreplace('HTML',
                       '<acronym title="HyperText Markup Language">HTML</acronym>',
                       $data['comment']['body']);
      }
    }

このプラグインはコメント中の'HTML'というテキストを'`<acronym title="HyperText Markup Language">HTML</acronym>`'に置き換えます。acronymタグはHTMLタグで、頭字語についての追加情報を提供します。

## イベント登録の仕方

イベント登録に必要なステップは以下になります。

1. `getEventList` メソッドから返る配列にイベント名を追加します。
2. `event_EventName($data)` という形でメソッドを生成し、この中でイベントを処理します。

複数のプラグインが同じイベントに登録できます。管理エリアのプラグインリストの順序に従ってプラグインに通知が行きます。リストの上にあるプラグインほど早く通知されます。

## パラメータ

`event_EventName` メソッドはひとつだけ `$data` パラメータを持ち、それはイベントごとに内容が異なります。これは連想配列です。この連想配列に渡されたオブジェクトや配列は参照形式で渡されるため、これらに加えた変更は記憶されます。

以下のイベントリストは、パラメータ変更がNucleusに知られるかどうかを示すために色を使い分けています。

- 参照渡し（緑）: この種のパラメータに変更を加えるとNucleusに知られます。
- 値渡し（赤）: プラグインイベントハンドラに渡される前に値がコピーされます。これらの変数への変更は自動的に破棄されます。.

パラメータとして渡されるオブジェクトはobject.として示されます。ほとんどのオブジェクトは参照渡しで、object by refのように示されます。

## イベントリスト

プラグインが登録できるイベント
名前 | いつ | パラメータ
--- | --- | ---
InitSkinParse | スキンの初期化の直前 | skin パースする`SKIN`オブジェクト type スキンタイプ（'index', 'item', 'archive', 'archivelist', 'member', 'error', 'search', 'imagepopup', 'fileparser'のいずれか)
PreSkinParse | スキンのパースの直前 | skin パースする`SKIN`オブジェクト type スキンタイプ（'index', 'item', 'archive', 'archivelist', 'member', 'error', 'search', 'imagepopup', 'fileparser'のいずれか） contents スキンの内容
PostSkinParse | スキンのパースの直後 | skin パースする`SKIN`オブジェクト type スキンタイプ（'index', 'item', 'archive', 'archivelist', 'member', 'error', 'search', 'imagepopup', 'fileparser'のいずれか）
PreItem | アイテムのパース前、ただしアイテムヘッダーのパース後 | blog `BLOG` オブジェクト item アイテムデータを持つオブジェクト
PostItem | アイテムのパース後、ただしアイテムフッターのパース前 | blog `BLOG` オブジェクト item アイテムデータを持つオブジェクト
PreComment | コメントの表示前 | comment コメントデータを持つ連想配列
PostComment | コメントの表示後 | comment コメントデータを持つ連想配列
PreDateHead | 日付ヘッダーのパース前 | blog `BLOG` オブジェクト timestamp 日付ヘッダーのタイムスタンプ
PostDateHead | 日付ヘッダーのパース後 | blog `BLOG` オブジェクト timestamp 日付ヘッダーのタイムスタンプ
PreDateFoot | 日付フッターのパース前 | blog `BLOG` オブジェクト timestamp 日付フッターのタイムスタンプ
PostDateFoot | 日付フッターのパース後 | blog `BLOG` オブジェクト timestamp 日付フッターのタイムスタンプ
LoginSuccess | ログイン成功後 | member `MEMBER` オブジェクト
LoginFailed | ログイン失敗後 | username ログイン時に使われたユーザー名
Logout | ログアウト後 | username ログアウト時のユーザー名
PreBlogContent | blogの内容がスキン変数を通して挿入される前 | blog `BLOG` オブジェクト type 呼び出されたスキン変数 ('blog', 'otherblog', 'archive', 'archivelist', 'item', 'searchresults', 'othersearchresults', 'categorylist', 'otherarchive', 'otherarchivelist')
PostBlogContent | blogの内容がスキン変数を通して挿入された後 | blog `BLOG` オブジェクト type 呼び出されたスキン変数 ('blog', 'otherblog', 'archive', 'archivelist', 'item', 'searchresults', 'othersearchresults', 'categorylist', 'otherarchive', 'otherarchivelist')
PreAddComment | コメントがデータベースに追加される前 | comment コメントデータ（連想配列）
PostAddComment | コメントがデータベースに追加された後 | comment コメントデータ（連想配列） commentid コメントのID
PostRegister | 新規ユーザーの登録後 | member 新しい`MEMBER` オブジェクト
PostAddItem | アイテムがデータベースに追加された後 | itemid データベースに出来た新しい itemid
PostUpdateItem | アイテムがデータベースにアップデートされた直後 | itemid アイテムのID
PreAddItem | アイテムがデータベースに追加される直前 | title タイトル body 本文 more 拡張テキスト blog `BLOG` オブジェクト authorid 執筆者ID timestamp UNIX タイムスタンプ closed 1 （コメント不可） or 0 （コメント可） draft 1 （ドラフト） or 0 （非ドラフト） catid カテゴリーID
PreUpdateItem | データベースにあるアイテムが更新される直前 | itemid アイテム ID title タイトル body 本文 more 拡張テキスト blog `BLOG オブジェクト` object closed 1 （コメント不可） or 0 （コメント可） catid カテゴリーID
PrepareItemForEdit | アイテムをデータベースから取得した直後で、編集のためにユーザーに表示される前 | item アイテムデータを持つ連想配列
PreUpdateComment | コメントが更新され、データベースに保存される直前 | body コメント本文
PrepareCommentForEdit | コメントをデータベースから取得した直後で、編集のためにユーザーに表示される前 | comment コメントデータ（連想配列）
PrePluginOptionsEdit | (v2.0b) 'プラグインオプションの編集'フォームが生成される前 (v2.2) パラメータ追加 (v3.2) 各オプションにパラメータ追加 | context (v2.2) `global`, `blog`, `member`, `item`, `category`のいずれか options 次のインデックスをもつ連想配列： `name`, `value`, `oid`, `description`, `type`, `typeinfo`, `contextid`, `extra` 。追加オプションをここに加えることも可能（それらで何かの処理をするときはPostPluginOptionsUpdateの記述も必要） `extra`フィールドを用いて、オプションに追加HTML（たとえばフォームのコントロール）を追加できます。もしそうする場合、 `extra` に追加する前に `pid` と `getID()` を比較し、さらに `name` をチェックすべきです。 plugid プラグイン ID （これが気になるなら、`GetID()`を見ると理解できる）（コンテクストがglobalのときのみ存在） contextid コンテクスト ID (blogid, memberid, catid, itemid コンテクストによる)
PrePluginOptionsUpdate | (v3.2) プラグインオプションが更新される前。（このイベントを使ってオプションの新しい値を評価したり変更したりできます） | context (v2.2) `global`, `member`, `blog`, `item`, `category`のいずれか plugid プラグイン ID （これが気になるなら、`GetID()`を見ると理解できる） optionname オプション名 contextid コンテクスト ID (blogid, memberid, catid, itemid コンテクストによる) value そのオプションの新しい値
PostPluginOptionsUpdate | (v2.0b) プラグインオプションの更新後 (v2.2) コンテクストによって異なるパラメータ | context (v2.2) `global`, `member`, `blog`, `item`, `category`のいずれか plugid プラグイン ID （これが気になるなら、`GetID()`を見ると理解できる）（globalコンテクスト） blogid (v2.2) blog ID (blog コンテクスト) blog (v2.2) BLOG オブジェクト (blog コンテクスト) memberid (v2.2) member ID (member コンテクスト) member (v2.2) MEMBER オブジェクト (member コンテクスト) catid (v2.2) category ID (category コンテクスト) itemid (v2.2) item ID (item コンテクスト) member (v2.2) ITEM オブジェクト (item コンテクスト)
PostAuthentication | (v2.0b) ログイン処理の完了後。ページリクエストごとに発生 | loggedIn `$member->isLoggedIn()`の戻り値
PreAddItemForm | (v2.0b) アイテム追加フォーム（ブックマークレットまたは管理エリア）が生成される直前 | contents 連想配列への参照。そのうちの'title', 'body', 'more'にはフォームフィールドへの初期値を与えることができます。複数のプラグイン間でこれらの値の変更を避けるには、処理後に'hasBeenSet'の値を1にセットします（かつ処理前にこの値をチェックするようにします） blog `BLOG` オブジェクトへの参照
AddItemFormExtras | (v2.0b) アイテム追加ページまたはブックマークレット内部のどこか。`template` ファイルの類を別に用意しなくても、ここでプラグインがカスタムフィールドを追加できる。 | blog `BLOG` オブジェクトへの参照
EditItemFormExtras | (v2.0b) アイテム編集ページまたはブックマークレット内部のどこか。`template` ファイルの類を別に用意しなくても、ここでプラグインがカスタムフィールドを追加できる。 あまり多くのデータを追加しないこと。また以下のように正しいXHTMLを生成してください。
    <h3>プラグイン名</h3>
    <p>追加フォームの内容</p>
このようにして、正しい構造を保ちつつ複数のプラグインがオプションを保持できます。またフィールド名の重複を避けるためにプレフィックスを用いてください（例 `plug_tb_url`）。 | blog `BLOG` オブジェクトへの参照 variables (read-only) 編集されるアイテムに関する全ての情報を持つ連想配列： 'itemid', 'draft', 'closed', 'title', 'body', 'more', 'author', 'authorid', 'timestamp', 'karmapos', 'karmaneg', 'catid' itemid アイテム IDへのショートカット
BlogSettingsFormExtras | (v2.0) blog設定ページにフォームを追加可能 あまり多くのデータを追加しないこと。また以下のように正しいXHTMLを生成してください。
    <h4>プラグイン名</h4>
    <form method="post" action="..."><p>
    追加フォームの内容</p></form>
このようにして、正しい構造を保ちつつ複数のプラグインがオプションを保持できます。またフィールド名の重複を避けるためにプレフィックスを用いてください（例 `plug_tb_url`）。 | blog `BLOG` オブジェクトへの参照
PreDeleteItem | (v2.0) アイテムがデータベースから削除される直前 | itemid 削除されるアイテムID
PostDeleteItem | (v2.0) アイテムがデータベースから削除された直後 | itemid 削除されたアイテムID
PreDeleteCategory | (v2.0) カテゴリーがデータベースから削除される直前 | catid 削除されるカテゴリー ID
PostDeleteCategory | (v2.0) カテゴリーがデータベースから削除された直後 | catid 削除されたカテゴリー ID
PreDeleteBlog | (v2.0) blogがデータベースから削除される直前 | blogid 削除されるblogID
PostDeleteBlog | (v2.0) blogがデータベースから削除された直後 | blogid 削除されたblogID
PreDeleteMember | (v2.0) メンバーがデータベースから削除される直前 | member `削除されるメンバーに関するMEMBER` オブジェクトへの参照
PostDeleteMember | (v2.0) メンバーがデータベースから削除された直後 | member `削除されるメンバーに関するMEMBER` オブジェクトへの参照
PreDeleteTeamMember | (v2.0) メンバーがweblogチームから削除される直前 | member `MEMBER` オブジェクトへの参照 blogid blogID
PostDeleteTeamMember | (v2.0) メンバーがweblogチームから削除された直後 | member `MEMBER` オブジェクトへの参照 blogid blogID
PreDeleteComment | (v2.0) コメントがデータベースから削除される直前 | commentid 削除されるコメントID
PostDeleteComment | (v2.0) コメントがデータベースから削除された直後 | commentid 削除されたコメントID
ActionLogCleared | (v2.0) アクションログが消去された後 | なし
PreDeleteTemplate | (v2.0) テンプレートがデータベースから削除される直前 | templateid 削除されるテンプレートID
PostDeleteTemplate | (v2.0) テンプレートがデータベースから削除された直後 | templateid 削除されたテンプレートID
PreDeleteSkin | (v2.0) スキンがデータベースから削除される直前 | skinid 削除されるスキンID
PostDeleteSkin | (v2.0) スキンがデータベースから削除された直後 | skinid 削除されたスキンID
PreDeletePlugin | (v2.0) プラグインがデータベースから削除される直前 | plugid 削除されるプラグインID
PostDeletePlugin | (v2.0) プラグインがデータベースから削除された直後 | plugid 削除されたプラグインID
PreDeleteBan | (v2.0) 禁止IPがデータベースから削除される直前 | blogid 禁止IPが削除されるblogのID iprange 禁止されたIPレンジ
PostDeleteBan | (v2.0) 禁止IPがデータベースから削除された直後 | blogid 禁止IPが削除されたblogのID iprange 禁止されたIPレンジ
PreAddCategory | (v2.0) 新しいカテゴリーがデータベースに生成される直前 | blog `BLOG` オブジェクトの参照 name 新しいカテゴリー名 description 新しいカテゴリーの説明
PostAddCategory | (v2.0) 新しいカテゴリーがデータベースに生成された直後 | blog `BLOG` オブジェクトへの参照 name 新しいカテゴリー名 description 新しいカテゴリーの説明 catid 新しいカテゴリー ID
PreAddBlog | (v2.0) 新しいblogが生成される直前 | name 新しい blog名 shortname 新しい blogの短縮名 timeoffset 新しい blogのタイムオフセット description 新しい blogの説明 defaultskin 新しいblogのデフォルトスキンのID
PostAddBlog | (v2.0) 新しいblogが生成された直後 | blog 新しい`BLOG` オブジェクト
PreAddPlugin | (v2.0) プラグインが追加される直前 | file 新しいプラグインのファイル名
PostAddPlugin | (v2.0) プラグインが追加された直後 | plugin 新しく追加されたプラグインのオブジェクト
PreAddTeamMember | (v2.0) メンバーがblogチームに追加される直前 | blog `BLOG` オブジェクト member `MEMBER` オブジェクト admin 新しく追加されたメンバーが管理権限を持っているかどうかを示すブール値
PostAddTeamMember | (v2.0) メンバーがblogチームに追加された直後 | blog `BLOG` オブジェクト member `MEMBER` オブジェクト admin 新しく追加されたメンバーが管理権限を持っているかどうかを示すブール値
PreAddTemplate | (v2.0) 新しいテンプレートが生成される直前（注：テンプレートが複製されたときも呼ばれる） | name 新しいテンプレート名 description 新しいテンプレートの説明
PostAddTemplate | (v2.0) 新しいテンプレートが生成された直後 | name 新しいテンプレート名 description 新しいテンプレートの説明 templateid 新しいテンプレートID
PreAddSkin | (v2.0) 新しいスキンが生成される直前（注：スキンが複製されたときも呼ばれる） | name 新しいスキン名 description 新しいスキン名の説明 type スキンのコンテントタイプ includeMode 新しいスキンのインクルードモード includePrefix 新しいスキンのインクルードプレフィックス
PostAddSkin | (v2.0) 新しいスキンが生成された直後 | name 新しいスキン名 description 新しいスキンの説明 type スキンのコンテントタイプ includeMode 新しいスキンのインクルードモード includePrefix 新しいスキンのインクルードプレフィックス skinid 新しいスキンID
PreAddBan | (v2.0) 新しい禁止IPが追加される直前 | blogid blogID iprange 禁止されたIPレンジ reason 禁止された理由を記述したテキストメッセージ
PostAddBan | (v2.0) 新しい禁止IPが追加された直後 | blogid blogID iprange 禁止されたIPレンジ reason 禁止された理由を記述したテキストメッセージ
PreMoveItem | (v2.0) アイテムが他のblog/カテゴリーに移される直前 | itemid アイテムID destblogid 移動先のblogID destcatid 移動先のカテゴリーID
PostMoveItem | (v2.0) アイテムが他のblog/カテゴリーに移された直後 | itemid アイテムID destblogid 新しいblogID destcatid 新しいカテゴリーID
PreMoveCategory | (v2.0) カテゴリーが他のblogに移される直前 | catid カテゴリーID sourceblog 移動元の`BLOG` オブジェクト destblog 移動先の`BLOG` オブジェクト
PostMoveCategory | (v2.0) カテゴリーが他のblogに移された直後 | catid カテゴリーID sourceblog 移動元の`BLOG` オブジェクト destblog 移動先の`BLOG` オブジェクト
MemberSettingsFormExtras | (v2.0) メンバー設定ページにフォームを追加可能 あまり多くのデータを追加しないこと。また以下のように正しいXHTMLを生成してください。
    <h4>プラグイン名</h4>
    <form method="post" action="..."><p>
    追加フォームの内容</p></form>
このようにして、正しい構造を保ちつつ複数のプラグインがオプションを保持できます。またフィールド名の重複を避けるためにプレフィックスを用いてください（例 `plug_tb_url`）。 | member `MEMBER` オブジェクトへの参照
GeneralSettingsFormExtras | (v2.0) 一般設定ページにフォームを追加可能 あまり多くのデータを追加しないこと。また以下のように正しいXHTMLを生成してください。
    <h4>プラグイン名</h4>
    <form method="post" action="..."><p>
    追加フォームの内容</p></form>
このようにして、正しい構造を保ちつつ複数のプラグインがオプションを保持できます。またフィールド名の重複を避けるためにプレフィックスを用いてください（例 `plug_tb_url`）。 | なし
AdminPrePageHead | (v2.5) 管理画面で、ページヘッドを出力する直前。このイベントはヘッド領域にスクリプトやCSSを追加するのに用いられます。 | extrahead HTMLページのヘッド領域に埋め込まれる追加情報。ここに追加したいものを入れてください。 action 現在実行されているアクション、またはページタイプ
AdminPrePageFoot | (v2.5) 管理画面で、ページフッターを出力する直前。 | action 現在実行されているアクション、またはページタイプ
PreSendContentType | (v2.5) HTTPヘッダーにコンテントタイプがセットされる直前 | contentType コンテントタイプ（`application/xhtml+xml`など） charset キャラクターセット pageType 表示するページの種類を示す文字列：`skin` (スキンタイプ), `media` (メディアライブラリ), `admin-action` (管理エリア), `bookmarklet-action` (ブックマークレット)
QuickMenu | (v2.5) 管理エリアのクイックメニューの一番下。そこへのプラグイン登録に利用されます。登録するにはoptionsに連想配列を入れます。実装例がプラグイン管理エリアを作るのセクションにあります。 | options 配列
BookmarkletExtraHead | (v2.5) ブックマークレット XHTMLコードのヘッド領域内。 | extrahead XHTMLコードのヘッド領域に埋め込まれる追加情報。ここに追加したいものを入れてください。
FormExtra | (v3.2) このイベントは、プラグインがコメント、メンバー間メール、認証フォームのいずれかのフォーム内に追加フィールドを挿入するときに使います。フォーム処理の際に発生する `ValidateForm` イベントに対応します。 | type イベントを発生させるフォームタイプ `activation` `additemform` （注：これは管理画面のアイテム追加フォームではない） `commentform-loggedin` `commentform-notloggedin` `membermailform-loggedin` `membermailform-notloggedin` member `type` が `activation`のとき、このフィールドは認証メンバーの詳細情報を含みます
ValidateForm | (v3.2) コメント、メンバー間メール、アカウント認証のいずれかが処理されるときに呼ばれます。プラグインはこれで各データの評価を実行でき、もし不具合があれば処理を中断できます。`FormExtra` と共に使うとフォームにフィールドを追加できます。 | type 処理されるフォームタイプ `membermail` `comment` `activation` error フォーム処理をストップするときに、`error` フィールドに空でないエラーメッセージを記入します。このエラーメッセージはユーザー側に表示されます。 comment コメントフォームのとき、コメントデータに関する連想配列を含みます。 member 認証フォームのとき、認証中のメンバー情報を含みます。

# オプションを保存する

プラグインに簡単にオプションを登録・取得できるように一連のメソッドが用意されています。これらのオプションは直接Nucleusの管理エリアで編集でき、プラグイン自身の管理エリアを用意する必要もなく、PHPファイルそのものの中にオプションの値を書き込まずにすみます。

オプションは異なったコンテクストで利用可能です。

1. グローバルオプション：管理エリアのプラグインセクションで編集可能
2. blogオプション：blog設定ページで編集可能
3. カテゴリーオプション：blog設定ページ（のカテゴリー編集ページ）で編集可能
4. メンバーオプション：メンバー編集ページで編集可能
5. アイテムオプション：アイテムの追加、およびアイテムの編集ページで編集可能

## オプションの種類

オプションにはいくつかのタイプが提供されています。

text
  シンプルなテキスト
yesno
  'yes'か'no'どちらか（編集画面ではラジオボタンとして表示されます）
password
  テキストフィールド (編集画面では伏字で表示されます)
textarea (v2.2)
  複数行のテキストフィールド
select (v2.2)
  ドロップダウンメニュー。次のような形式の追加情報が必要です： Option 1|value1|Option 2|value2|Option 3|value3

## オプション・メタ

Nucleus v3.2よりオプション・メタデータを用いて、オプションタイプを正しい値を受け取れるように制限できるようになりました。このメタデータは `$typeExtras`フィールドにセミコロン区切りのリストで保存されます。注：selectオプションでは、selectリストは`$typeExtras`のなかで一番最初でなければいけません。

キー | 説明
--- | ---
`datatype` | Nucleus本体に、どのデータ型を使いたいかという追加情報を与えます。現在は '`numerical`' のみ利用できます。 '`numerical`' を指定することでNucleusは数値情報のみを受け付けます（クライアントサイド・サーバサイド両方でチェック） （'`select`' と '`text`'のオプションタイプで利用できます）
`access` | '`readonly`'にセットすることで、オプションを編集不可能にします（'`text`' と '`textarea`'のオプションタイプで利用できます） '`hidden`'を使うと、利用者側にそのオプションの存在を完全に隠蔽します（'`text`'のオプションタイプで利用できます）

設定例

    // 数値のみを受け付けるテキストオプションを作成
    $this->createBlogOption('FooBar', 'foobar', 'text', '0', 'datatype=numerical');
    // 数値のみを受け付けるセレクトオプションを作成
    $this->createItemOption('FooBar', 'foobar', 'select', '0', '0|0|1|1|2|2;datatype=numerical');
    // 編集不可能なテキストエリアオプションを作成
    $this->createOption('FooBar', 'foobar', 'textarea', 'This textarea is readonly', 'access=readonly');

## 制限

1. オプション名は最大20文字です。
2. オプションの説明文は最大255文字です。
3. オプションの値は制限ありません（v2.2より前のバージョンでは128文字の制限がありました）
4. '=', '|', ';' のキャラクターはセレクトオプション用のセレクトリストやオプション・メタデータ中で使用することはできません。

## メソッド

### createOption($name, $desc, $type, $defValue = '', $typeExtras = '')

グローバルなコンテクストで新しいオプションを生成します。

パラメータ | 値
--- | ---
$name | オプション名
$desc | オプション編集画面で表示される説明文
$type | オプションタイプ（前出）
$defValue | 初期値
$typeExtras | オプションタイプの追加情報（前出）

### [v2.2] createBlogOption($name, $desc, $type, $defValue = '', $typeExtras = '')

blogのコンテクストで新しいオプションを生成します（`createOption`を参照）。

### [v2.2] createCategoryOption($name, $desc, $type, $defValue = '', $typeExtras = '')

カテゴリーのコンテクストで新しいオプションを生成します（`createOption`を参照）。

### [v2.2] createMemberOption($name, $desc, $type, $defValue = '', $typeExtras = '')

メンバーのコンテクストで新しいオプションを生成します（`createOption`を参照）。

### [v3.2] createItemOption($name, $desc, $type, $defValue = '', $typeExtras = '')

アイテムのコンテクストで新しいオプションを生成します（`createOption`を参照）。

### setOption($name, $value)

すでにデータベースに存在するオプションの値を変更します。

パラメータ | 値
--- | ---
$name | オプション名
$value | 新しい値

### [v2.2] setBlogOption($blogid, $name, $value)

blogオプションの値を変更します。`blogid`属性はどのblogでそのオプションが有効かを示します（その他のオプション：`setOption`を参照）。

### [v2.2] setCategoryOption($catid, $name, $value)

カテゴリーオプションの値を変更します。`catid`属性はどのカテゴリーでそのオプションが有効かを示します（その他のオプション：`setOption`を参照）。

### [v2.2] setMemberOption($memberid, $name, $value)

メンバーオプションの値を変更します。`memberid`属性はどのメンバーでそのオプションが有効かを示します（その他のオプション：`setOption`を参照）。

### [v3.2] setItemOption($itemid, $name, $value)

アイテムオプションの値を変更します。`itemid`属性はどのアイテムでそのオプションが有効かを示します（その他のオプション：`setOption`を参照）。

### getOption($name)

データベース内のオプションの値を返します。

パラメータ | 値
--- | ---
$name | オプション名

### [v2.2] getBlogOption($blogid, $name)

blogオプションの値を返します。`blogid`属性は値がリスエストされたblogを示します（その他のオプション：`getOption`を参照）。

### [v2.2] getCategoryOption($catid, $name)

カテゴリーオプションの値を返します。`catid`属性は値がリスエストされたカテゴリーを示します（その他のオプション：`getOption`を参照）。

### [v2.2] getMemberOption($memberid, $name)

メンバーオプションの値を返します。`memberid`属性は値がリスエストされたメンバーを示します（その他のオプション：`getOption`を参照）。

### [v3.2] getItemOption($itemid, $name)

アイテムオプションの値を返します。`itemid`属性は値がリスエストされたアイテムを示します（その他のオプション：`getOption`を参照）。

### deleteOption($name)

データベースからオプションを削除します。

パラメータ | 値
--- | ---
$name | オプション名

### [v2.2] deleteBlogOption($name)

blogオプションを削除します（`deleteOption`を参照）。

### [v2.2] deleteCategoryOption($name)

カテゴリーオプションを削除します（`deleteOption`を参照）。

### [v2.2] deleteMemberOption($name)

メンバーオプションを削除します（`deleteOption`を参照）。

### [v3.2] deleteItemOption($name)

アイテムオプションを削除します（`deleteOption`を参照）。

### [v2.2] getAllBlogOptions($name)

与えられたblogオプションの全ての値を返します。結果は存在するblogidごとの連想配列です。

### [v2.2] getAllCategoryOptions($name)

与えられたカテゴリーオプションの全ての値を返します。結果は存在するcatidごとの連想配列です。

### [v2.2] getAllMemberOptions($name)

与えられたメンバーオプションの全ての値を返します。結果は存在するmemberidごとの連想配列です。

### [v3.2] getAllItemOptions($name)

与えられたアイテムオプションの全ての値を返します。結果は存在するitemidごとの連想配列です。

### [v3.2] getBlogOptionTop($name, $amount = 10, $sort = 'desc')

与えられたオプションの最初の値を返します。結果は配列で、各要素がそれぞれのblogid ('id') の値 ('value') を持つ配列になっています。

パラメータ | 値
--- | ---
$name | オプション名
$amount | 必要なオプション数
$sort | 昇順 ('asc') か降順 ('desc') で並べ替え

### [v3.2] getMemberOptionTop($name, $amount = 10, $sort = 'desc')

与えられたオプションの最初の値を返します。結果は配列で、各要素がそれぞれのメンバーID ('id') の値 ('value') を持つ配列になっています（パラメータは`getBlogOptionTop`を参照）。

### [v3.2] getCategoryOptionTop($name, $amount = 10, $sort = 'desc')

与えられたオプションの最初の値を返します。結果は配列で、各要素がそれぞれのカテゴリーID ('id') の値 ('value') を持つ配列になっています（パラメータは`getBlogOptionTop`を参照）。

### [v3.2] getItemOptionTop($name, $amount = 10, $sort = 'desc')

与えられたオプションの最初の値を返します。結果は配列で、各要素がそれぞれのアイテムID ('id') の値 ('value') を持つ配列になっています（パラメータは`getBlogOptionTop`を参照）。

注： プラグインクラス内のコンストラクタから、これらのファンクションを呼ぶことはできません。プラグインがロードされた後にこれらを実行したいときは、かわりに`init()`メソッド内に置きます。

# データベース・テーブル

## Nucleusテーブルへのアクセス

v2.0まで、Nucleusテーブルへのアクセスは単に`nucleus_`と名づけられたテーブルに対してSQL命令を実行するだけのものでした。Nucleusのバージョン2.2以降はカスタム・テーブル名を利用できるようになったため、プラグイン開発に若干注意する必要があります。

1. `nucleus_item` などの固定されたテーブル名の代わりに、テーブル名のプレフィックスを生成するために `sql_table('item')` というグローバルファンクションを利用します。
2. `supportsFeature('SqlTablePrefix')` が呼ばれたときにプラグインが1（真）を返すようにします。これがないと、カスタムプレフィックスがセットされている場合でバージョンが2.0より大きいNucleusではプラグインをロードできません（用心のため）。

v2.0までのNucleusではグローバルファンクション `sql_table` は利用できないことに注意してください。もしこのメソッドを用いつつ、プラグインをv2.0以下のNucleusで動作させたい場合は、以下のコードをプラグインクラスの前に追加してください。

    <?

    // プラグインがNucleusバージョン2.0以下と互換性を持つために必要
    if (!function_exists('sql_table'))
    {
    	function sql_table($name) {
    		return 'nucleus_' . $name;
    	}
    }

    class NP_HelloWorld extends NucleusPlugin {
    ...
    }

    ?>

## 独自テーブル

もしプラグイン独自のテーブルが必要なら、`install`メソッドの中で独自テーブルを生成し、`unInstall`メソッドの中でそれを削除するようにします。

いくつかの注意点

- `nucleus_plug_plugname` のように、他のプラグインと競合しないテーブル名を考えてください。カスタムプレフィックスに対応するため、テーブル名を `sql_table('plug_plugname')` で生成してください。
- 自分自身でデータベース接続をする必要はありません。PHPコマンド `mysql_query()` を使ってSQL命令を実行できます。
- 自分でデータベース接続をする場合、後でNucleusデータベースへの接続を復元するようにしてください。自前処理の後で `sql_connect()` を呼ぶことで可能です。頻繁な再接続を避けるために、コンストラクタでそれを行うのも良いです。`$this- >db`のリンクIDを保持でき、各クエリにそれを渡すことができます。
- バックアップ機能を使う時は、独自テーブルもバックアップに含めるよう、`getTableList()` を再定義してください。

# プラグイン管理エリア

Ver2.5から、Nucleusの管理エリアに統合されたプラグイン管理エリアを作成できます。これらのページは従来のプラグイン管理ページや左側のクイックメニューからアクセスできます。

## 基本

管理エリアを提供するには、次のステップが必要です。

1. プラグインディレクトリにプラグイン名のサブディレクトリを作ります。たとえばプラグイン名が`NP_PluginName`なら、'pluginname'です。ディレクトリ名はすべて小文字で！
2. そのディレクトリで、次のようなindex.phpを用意します。

       <?php

       	// if your 'plugin' directory is not in the default location,
       	// edit this variable to point to your site directory
       	// (where config.php is)
       	$strRel = '../../../';

       	include($strRel . 'config.php');
       	if (!$member->isLoggedIn())
       		doError('You\'re not logged in.');

       	include($DIR_LIBS . 'PLUGINADMIN.php');

       	// create the admin area page
       	$oPluginAdmin = new PluginAdmin('PluginName');
       	$oPluginAdmin->start();

       	echo '<h2>プラグイン名</h2>';

       	echo '<p>ページ内容<p>';

       	$oPluginAdmin->end();

       ?>

3. プラグイン側に次のコードを挿入し、クイックメニューイベントに登録します。

       function event_QuickMenu(&$data) {
       		array_push(
       			$data['options'],
       			array(
       				'title' => 'プラグイン名',
       				'url' => $this->getAdminURL(),
       				'tooltip' => 'ツールチップテキスト'
       			)
       		);
       	}

4. プラグイン側に次の関数を記述します。

       function hasAdminArea()
       {
       	return 1;
       }

## 考慮すること

- 登録できるからといって安易にクイックメニューへ登録しないこと。クイックメニューにプラグインが100個並んだりしたらかなりウンザリするでしょう。ですので、クイックメニューに登録する場合でも、クイックメニュー登録を有効・無効化するプラグインオプションを（グローバルまたはメンバーオプションで）用意することを考えてください。
- `プラグインディレクトリが nucleus/plugins/ ではない場合は、index.php内の $strRel` 変数は手動で書き換える必要があります。
- 管理エリアのアウトプットが正しいXHTMLになっているか確認してください。正しくないと、MozillaなどのGeckoベースのブラウザでページ表示が崩れます。

## PluginAdmin クラス

`PluginAdmin` クラスは助けになります。これを一度生成すれば、`$oPluginAdmin->plugin` でプラグインのインスタンスにアクセスできます。

# プラグイン用ヘルプページ

Nucleus v3.2から、プラグインの機能の概要、利用できるスキン・テンプレート変数、さらに詳細な情報のありかなどを示すヘルプページを提供可能になりました。

ヘルプページは管理画面のプラグイン一覧からアクセス可能になります。

## 基本

ヘルプページを提供するために、次のステップが必要です。

1. プラグインディレクトリに、プラグイン名をつけたサブディレクトリを作成します。ディレクトリ名は小文字であることに注意します。管理エリアを作るときと同様です。
2. そのディレクトリの中に help.html を作り、プラグインについての文章を記述します。次の雛型からはじめると良いでしょう。

       <h3>プラグインの概要</h3>

       <p>このプラグインはヘルプページがいかに機能するかを示すためだけのものです</p>

       <h3>インストール</h3>

       <p>これを読めてるならインストールは正しく出来てます :-)</p>

       <h3>スキン変数</h3>

       <p>このプラグインはただのテストケースなのでスキン・テンプレート変数はありませんが、書くとすれば。

       <ul><li><b><%HelpPageTestCase1%></b>: なにかをする</li>
       <li><b><%HelpPageTestCase1(foobar)%></b>: 別のなにかをする</li></ul></p>

       <h3>サポートとバグ報告</h3>

       <p>さらなるサポートやバグ報告のために、次のフォーラムのスレッドを利用してください。
       <a href="http://forum.nucleuscms.org/viewtopic.php?t=<トピックID>">
       http://forum.nucleuscms.org/viewtopic.php?t=<トピックID></a></p>

       <h3>バージョン履歴</h3>

       <ul><li>Version 0.1: 最初のテストケースバージョン</li>
       <li>Version 0.0: その前のバージョン ;-)</li></ul>

3. supportsFeature('HelpPage') で0より大きい数字を返すように設定します。

       function supportsFeature($what) {
       	switch($what) {
       	case 'HelpPage':
       		return 1;
       	  default:
       		return 0;
       	}
         }

# プラグイン依存チェック

v3.2から、他のプラグインとの依存関係を宣言する新しいプラグインインターフェイスが追加されました。他のプラグインの機能を必要とするプラグインに利用できます。特に依存関係が成立しなくて正しく機能しない状態を検知するときに便利です。

## この機能を利用するプラグインの書き方

現実世界での例からはじめましょう。

NP_PageLinkList は NP_BlogWithOffset の機能を利用するため、利用者には NP_BlogWithOffset のインストール後に NP_PageLinkList をインストールさせたいとします。NucleusはこのAPIによって、インストール前に依存関係を検知させる方法をプラグインに提供します。

このケースでは、NP_PageLinkList 側に NP_BlogWithOffset が必要だということを認識させるコードを埋め込みます。プラグインがインストールされる際に、Nucleusコアは `getPluginDep()` というファンクションを呼び出します。このファンクションは必要なプラグインのリストを返し、コアはインストール済みのプラグインをチェックして、もし依存関係に欠如があればインストールを拒否します。

必要なことは NP_PageLinkList にこのファンクションを追加する、ただそれだけです。

    function getPluginDep() {
    	 return array('NP_BlogWithOffset');
    }

このプラグイン依存チェックは、他のプラグインが依存しているプラグインがアンインストールされることも防ぎます。