はじめに

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

このドキュメントは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 と名づけて保存し、プラグインディレクトリに置きます。最後の ?> の後や、最初の <?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() を再定義してください。
• ユーザーがプラグインをアップデートする時や、何らかの理由で一時的にプラグインをアンインストールしなければならない時、やプラグイン独自のテーブルの内容が失われる事があります。そうならないように、テーブルを削除するか否かをプラグインオプションで設定できるようにしておくといいでしょう。テーブルの削除をオプションでコントロールするには、install()メソッドで次のようなオプションを作成します。

  $this->createOption('del_uninstall', 'Delete NP_MyPlugin data tables on uninstall?', 'yesno','no');

  そしてuninstall()メソッドで、次のようにします。

  if ($this->getOption('del_uninstall') == 'yes')	{
  	foreach ($this->getTableList() as $table) {
  		sql_query("DROP TABLE $table");
  	}
  }

プラグイン管理エリア

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-%gt;getAdminURL(),
                   'tooltip' => 'ツールチップテキスト'
               )
           );
       }

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

   function hasAdminArea()
   {
       return 1;
   }

5. オプション。クイックメニュー登録のオプションを作成し、誰に表示するか制限します。quickmenuというyesnoタイプのオプションがinstall()にあるとします。次のように、クイックメニュー登録の表示を最高管理者とブログ管理者に制限します。

   function event_QuickMenu(&$data) {
       // only show when option enabled
       if ($this->getOption('quickmenu') != 'yes') return;
       global $member;
       if (!$member->isAdmin() && !count($member->getAdminBlogs())) return;
       array_push($data['options'],
         	array('title' => 'PluginName',
          	'url' => $this->getAdminURL(),
          	'tooltip' => 'Administer NP_PluginName'));
   }

考慮すること

• 登録できるからといって安易にクイックメニューへ登録しないこと。クイックメニューにプラグインが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');
}

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

プラグインの多国語化

プラグインをより多くの人に使ってもらうために

あなたと同じ言葉を話さない世界中の人達がプラグインをより使いやすくするために、プラグインを多国語化できます。 少し手間は増えますが、プラグインが出力する文章を翻訳するだけで可能です。 以下に Nucleus のコアで用意されている標準的な手順を記載します。 Andyさん、ありがとう！

1. プラグインを作る 先ずはじめに、あなたが普段使っている言葉でプラグインを作ります。プラグインが安定して動作するようになってから、言語ファイルを作成することが推奨されます。
2. プラグインディレクトリを作る 作ったプラグインの名前が NP_AbcDef なら、プラグインディレクトリの名前は abcdef になります(必ず小文字を使用すること)。
3. 言語ファイルを作る プラグインディレクトリに言語ファイルを作成します。言語ファイルの名前は Nucleus コアが使用しているものと同じにします。例えば、英語なら english.php。日本語の UTF-8 なら japanese-utf8.phpになります(UTF がお勧めです。参考までに日本語の EUC の場合は japanese-euc.php になります)。
4. 文を定義する 次のように言語ファイル内で分を定義します。

   <?php
   define('_ABCDEF_MESSAGENAME',                  '実際のメッセージ');
     . . .
   ?>

   全ての文を定義する必要があります。定数は一回しか定義できないので、既に定義されているものと重複しないようにプラグインの名前をはじめにつけることが推奨されます(この例だと _ABCDEF)。
5. 文の置き換え 全ての文を、言語ファイルで定義した定数と置き換えます
6. init() メソッドの編集 プラグイン内の init() メソッドを、次のように編集します(既に init() メソッドを定義している場合は init() メソッド内にコードを追記します)。

      function init() {
         // include language file for this plugin
         $language = ereg_replace( '[\\|/]', '', getLanguageName());
         if (file_exists($this->getDirectory().$language.'.php'))
            include_once($this->getDirectory().$language.'.php');
         else
            include_once($this->getDirectory().'english.php');
      }

   このコードは Nucleus のコアで使用されているものと同一です。
7. 言語ファイルの追加 ｢英語｣が基本の言語になっていますので、｢英語｣の言語ファイルも追加することが望まれます。

スキン変数の出力の書式

偉大なプラグインのいくつかは、様々なスキンや URL の生成において、必ずしもそのまま使用できるとはいえません。なぜなら、doSkinVar() メソッドによって出力されるものが、 ユーザーのニーズに十二分に合致するものであるとは言いがたいからです。Nucleus では、出力をここのユーザーによっておのおののニーズに沿ったものにする為に、いくつかのツールを用意しています。

URLの出力

各ブログ・カテゴリー・アイテム・メンバー、それから action.php や管理エリア、または各プラグインの管理エリアなどの URL を出力する為に、Nucleus はコアの機能として いくつかのファンクションとグローバル変数を用意しています。：

スキンへの出力にテンプレートを使う

出力する文字列をテンプレートを使って整形出来るようにしましょう。あなたが順不同のリストで出力したいと考えていたとしても、別のユーザーは同じデータを 記号で区切ったり、特別な形で出力したいと考えるかもしれません。Nucleus にはテンプレートデータを作ったり定義したりする2種類の方法があります。 次に上げるれいの両方において、<%foo%> と <%bar%> のふたつのテンプレート変数を使用します。

1. プラグインのオプションを使う方法。この方法は v3.2 以降で使用でき、次のように install() メソッド に記述する事によって簡単に作成する事が出来ますが、アップグレードのためにプラグインを削除した時に、ユーザーは同時にカスタマイズした テンプレートを失ってしまうという大きなデメリットがあります。

   $this->createOption('my_template', 
   		'プラグインの出力の為のテンプレート', 
   		'textarea', 
   		'<li><%foo%> loves <%bar%></li>');

   doSkinVar() メソッドで、foo と bar を次のように定義して、テンプレートを埋めます。

   $mytemplate = $this->getOption('my_template');
   $couples = array(
   			array(
   				'foo'=>'Ricky',
   				'bar'=>'Lucy'),
   			array(
   				'foo'=>'Sid',
   				'bar'=>'Nancy'),
   			array(
   				'foo'=>'Mickey',
   				'bar'=>'Minnie')
   			);
   foreach ($couples as $values) {
   	echo TEMPLATE::fill($mytemplate,$values);
   }

   これでプラグインのスキン変数 <%TemplateTest%> を書いたところに、次のように出力されます。

   <li>Ricky loves Lucy</li>
   <li>Sid loves Nancy</li>
   <li>Mickey loves Minnie</li>

2. Nucleus コアのテンプレートシステムを使う方法。この方法は v3.4以降で使用できます。この方法の利点は、他のテンプレートと 同じようにデータベースに格納され、配布用にテンプレートをエクスポートできるところにあります。この API を使用したプラグインのサンプルが、 フォーラムの新API「TemplateExtraFields」を使ったプラグインの見本に (本家フォーラムのスレッドは Skin specific values for Plugins) にあります。細かな点は本家フォーラムの Skin specific values for Plugins スレッド を参照してください。ここでは要約のみ書いてあります。 まず、install() メソッド中でプラグインオプションを作成し、ここでテンプレートのデフォルトの内容を定義します。

   $this->createOption('my_template', 
   		'Template used to format output of plugin.', 
   		'textarea', 
   		'<li><%foo%> loves <%bar%></li>');

   次に割り込みをかけるイベントのリストに TemplateExtraFields を登録します。

   function getEventList() { return array('TemplateExtraFields'); }

   そして、event_TemplateExtraFields メソッドを作成します。

   function event_TemplateExtraFields(&$data) {
       /* Add an element in the $data['fields'] array using your plugin name as the key 
   	and an associative array containing the field name and field label*/
       /* note that your field names should be lowercase and include the name 
   	of your template as shown below. This will ensure that all template field names are unique. */
       $data['fields']['NP_TemplateTest'] = array(
           'templatetest_body'=>'TemplateTest Body'
       );
   }

   最後に doSkinVar() メソッドで、テンプレートを埋めます。この時、スキン変数の引数に使用するテンプレート名が必要です。

   function doSkinVar($skinType,$template = '') {
   	global $blog, $CONF, $manager,$member;
   
   	$template =& $manager->getTemplate($template);
   	if (trim($template['templatetest_body']) == '')
   		$template['templatetest_body'] = $this->getOption('my_template');
   		
   	$couples = array(
   			array(
   				'foo'=>'Ricky',
   				'bar'=>'Lucy'),
   			array(
   				'foo'=>'Sid',
   				'bar'=>'Nancy'),
   			array(
   				'foo'=>'Mickey',
   				'bar'=>'Minnie')
   			);
   	foreach ($couples as $values) {
   		echo TEMPLATE::fill($template['templatetest_body'],$values);
   	}	
   }

   ユーザーは『テンプレート編集』画面で、「TemplateTest Body」フィールドに出力したい形式でテンプレートを編集します。 例えば「default/index」テンプレートを使って、こんな風にテンプレートを編集します。

   <li><%foo%> loves <%bar%>!!!</li>

   そしてスキンに <%TemplateTest(default/index)%> と書くと、そこに

   <li>Ricky loves Lucy!!!</li>
   <li>Sid loves Nancy!!!</li>
   <li>Mickey loves Minnie!!!</li>

   と表示されます。
   
3. 通常のテンプレートを使って書式化。この方法は v3.4 以降で、アイテムを出力するプラグインで使用できます。 この方法にはコアのテンプレートシステムの既存の｢アイテム｣フィールドを使うというアドバンテージがあり、スキン変数の <%blog%> の様に使用します。スキン変数の引数として、一つ以上のアイテムの ID と使用するテンプレート名を、また、BLOG クラスの readLogFromList() メソッドを呼び出せることが条件です。テンプレート変数として使用したい場合は、doTemplateVar() メソッドで使用することも出来ます。 例として doSkinVar() メソッドでこのテクニックを使う方法を示しておきます。 4つのアイテムの ID を引数として受け取り、「default/index」テンプレートを使って出力します。

   function doSkinVar($skinType,$item1 = 0,$item2 = 0,$item3 = 0,$item4 = 0) {
   	global $blog;
   	$highlight = '';
   	$template = 'default/index';
   	$item_array = array($item1,$item2,$item3,$item4);
   	$blog->readLogFromList($item_array, $template);
   }

この他にも……

役立つドキュメントがたくさん！

このドキュメント以外にもあなたがプラグインを開発するにあたって、リンク先のページもきっと役立つことと思います。

• Development Wiki(公式サイト(英語))
• Nucleusプラグインの技術情報(日本公式サイト)
• Nucleus - SQL テーブル構造