はじめに

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

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

目次

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

イントロダクション

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

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

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

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

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

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

<?php

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

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

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

	// プラグインのバージョン
	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 クラスが提供する、再実装すべきでない幾つかの特殊メソッドです。これらはプラグイン内で、$this->functionName()シンタックスを利用して呼び出します。

スキン変数

解説

独自のスキン変数を生成し、<%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のように示されます。

イベントリスト

<h3>プラグイン名</h3>
<p>追加フォームの内容</p>

<h4>プラグイン名</h4>
<form method="post" action="..."><p>
追加フォームの内容</p></form>

<h4>プラグイン名</h4>
<form method="post" action="..."><p>
追加フォームの内容</p></form>

<h4>プラグイン名</h4>
<form method="post" action="..."><p>
追加フォームの内容</p></form>

オプションを保存する

プラグインに簡単にオプションを登録・取得できるように一連のメソッドが用意されています。これらのオプションは直接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のなかで一番最初でなければいけません。

設定例

// 数値のみを受け付けるテキストオプションを作成
$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 = '')

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

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

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

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

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

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

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

[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') を持つ配列になっています。

[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を参照）。

データベース・テーブル

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

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