プラグイン API 2011年2月3日
訳者注:
注:

はじめに

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

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

目次

イントロダクション back to top

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

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

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

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

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

では、シンプルなプラグインを書いてみましょう。基本的にプラグインは、あらかじめ定義された 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;
            case 'SqlApi':
                return 1;
            default:
                return 0;
        }
    }

}
?>
  1. このコードをコピーし、 NP_HelloWorld.php と名づけて保存し、プラグインディレクトリに置きます。最後の ?> の後や、最初の <?php の前にスペースがないことを確認しましょう。ところでNP は "Nucleus Plugin" って意味ですよ :-) 念のため。
  2. Nucleusの管理画面を開き、Nucleusの管理>プラグインの管理にいきます。
  3. HelloWorld プラグインがインストール可能な状態になっているはずですので、インストールします。すべてがうまくいけば、インストール済みプラグインリストに追加されます。
  4. あなたのスキンの1つを編集し、実際のページに表示する箇所に次の文を挿入します。
    <%HelloWorld%>
    注意:カッコ内の名称 (HelloWorld) は大文字小文字を識別します!
  5. さて、編集したスキンから生成されるページを見てみましょう。プラグイン変数を追加した場所に "Hello World" と見えますね?

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

NucleusPlugin クラスの概要 back to top

すべてのプラグインは、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/footerdateheader/footer)での<%plugin(...)%> 変数からの呼び出しになります。デフォルトではこのメソッドはテンプレートをスキンタイプとみなしてdoSkinVar メソッドに処理を渡します。doTemplateVar メソッドの実装に関する詳細情報はこちら
doTemplateCommentsVar(&$item, &$comment) (v2.0b) 基本的に doSkinVar と同じですが、今度はテンプレート内(コメント部分)での<%plugin(...)%> 変数からの呼び出しになります。デフォルトではこのメソッドはテンプレートをスキンタイプとみなしてdoSkinVar メソッドに処理を渡します。doTemplateCommentsVarメソッドの実装に関する詳細情報はこちら
doItemVar(&$item, &$param) (v3.30) 基本的に doSkinVar と同じですが、今度は投稿した記事内での<%plugin(...)%> 変数からの呼び出しになります。渡される引数のうち&$itemは変数が記述されているアイテムのフルオブジェクトを、&$paramはプラグインごとの関数のパラメータになります。
doIf($key, $value) (v3.30) スキン変数 if/ifnot/elseif/elseifnot に対して、プラグイン独自の判断をする事が出来るメソッドです。通常は、$key 変数が $value の値を持っているかを調べて、 truefalse を返すことになります。このメソッドをプラグインに実装する場合は、作者は使用方法のドキュメントを書くようにしてください。
doAction($type) プラグインがユーザーインタラクションを求めたとき、 action.phpを介してこのメソッドがそれを与えます。これはNucleus自身が新しいコメントや投票を処理するのに使用するスクリプトです。正しいパラメータを用いることで、プラグインからの doAction メソッドを呼び出せます。$type はオプションのメッセージタイプに該当します。doAction メソッド内で、リクエストからの追加の変数にアクセスできます。デフォルトではこのメソッドがエラーメッセージをトリガーすると'No Such Action'という文字列を返します。doAction に関する詳細情報はこちら
install() このメソッドはプラグインがインストールされた際に呼ばれます。データベース・テーブルの生成やプラグインオプションの生成などの初期化作業を行うことができます。デフォルトではこのメソッドは何もしません。
unInstall() プラグインがアンインストールされた際に呼ばれます。この時点でデータベースに作られたプラグイン情報を消去すると良いです。デフォルトではこのメソッドは何もしません。
getEventList() プラグインはイベント登録が可能です。イベントはNucleusが何かアクションを起こすたびに生成されます。たとえば、AddItem イベントは、このイベントを登録しているすべてのプラグインを呼び出します。呼び出されるメソッドは event_AddItem($params)になります。 $params パラメータは、例えば AddItemitemid のような、情報フィールドを複数持つ連想配列です。デフォルトではどのイベントにも登録されていないことを示す空の配列を返します。イベントに関する詳細情報はこちら
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_"部分を省き、全てを小文字にしたプラグインのクラス名を返します。この情報は getAdminURLgetDirectory で使用されます。

スキン変数back to top

解説

独自のスキン変数を生成し、<%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')

ノート

テンプレート変数back to top

解説

テンプレートプラグイン変数はスキンプラグイン変数と同様に働きますが以下の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')

ノート

アクションback to top

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

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

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

イベントback to top

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に知られるかどうかを示すために色を使い分けています。

パラメータとして渡されるオブジェクトは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 オブジェクト
username
ログ印字に使用されたログイン名
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
コメントデータ(連想配列)
spamcheck
(v3.3) SpamCheckイベントの結果として返されるデータ構造(連想配列)
PostAddComment コメントがデータベースに追加された後
comment
コメントデータ(連想配列)
commentid
コメントのID
spamcheck
(v3.3) SpamCheckイベントの結果として返されるデータ構造(連想配列)
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 に追加する前に pidgetID() を比較し、さらに 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
PreDeleteSkinPart スペシャルスキンパーツがデータベースから削除される直前
skinid
削除されるスペシャルスキンパーツが含まれるスキンのID
skintype
削除されるスペシャルスキンパーツの名前
PostDeleteSkin スペシャルスキンパーツがデータベースから削除された直後
skinid
削除されたスペシャルスキンパーツが含まれるスキンのID
skintype
削除されたスペシャルスキンパーツの名前
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
typeactivationのとき、このフィールドは認証メンバーの詳細情報を含みます
ValidateForm (v3.2) コメント、メンバー間メール、アカウント認証のいずれかが処理されるときに呼ばれます。プラグインはこれで各データの評価を実行でき、もし不具合があれば処理を中断できます。FormExtra と共に使うとフォームにフィールドを追加できます。
type
処理されるフォームタイプ
  • membermail
  • comment
  • activation
error
フォーム処理をストップするときに、error フィールドに空でないエラーメッセージを記入します。このエラーメッセージはユーザー側に表示されます。
comment
コメントデータの連想配列(コメントフォームのときのみ)
spamcheck
(v3.3) SpamCheckイベントの結果として返される連想配列(コメントフォームのときのみ)
member
認証フォームのとき、認証中のメンバー情報を含みます。
ParseURL (v3.22)NucleusのコアでURLからアイテムやカテゴリのIDを読み取る前。プラグインはこのイベントを使ってURLを解釈します
type
FancyURLの仮想ディレクトリ(拡張子無しファイル)のファイル名(item, blog, ...)
info
解決される前のURL(この名前は以前の変数名であるpathinfoから来ています).
complete
プラグインがURLを解釈し終わるとこれがtrueにセットされます。falseの場合はプラグインはURLを解釈していません。
GenerateURL (v3.22)URLが自動生成される前。このイベントを使って独自のURLを生成する事が出来ます。
type
生成するURLのタイプ(item, blog, ...)
params
生成するURLに付加するパラメータ
completed
プラグインはURLを生成し終わるとこれをtrueにセットしてURLを返します。falseの場合はプラグインはURLを生成していません。
url
プラグインが生成したURLを格納する為の空の変数
SpamCheck (v3.3) 新しいコメントが追加されるときに呼ばれます。アンチスパムのプラグインはこのイベントを使ってコメントがスパムかどうかマークを付けられます。SpamCheckイベントの詳しい説明は別の文書を参照のこと(SpamCheck API 2.0
spamcheck
spamcheckのデータ構造(連想配列)
PreMediaUpload (v3.3)アップロードされたファイルが「media」ディレクトリに書き込まれる前。
collection
アップロードされたファイルが格納されるべき「コレクション」
uploadfile
テンポラリディレクトリに狩り沖されているアップロードされたファイルのファイル名
filename
最終的に保存されるファイル名
PostMediaUpload (v3.3)アップロードされたファイルが「media」ディレクトリに書き込まれた後。
collection
アップロードされたファイルが格納された「コレクション」
mediadir
アップロードされたファイルが保存されたメディアディレクトリ
filename
保存されたファイル名
SendPing (v3.3)「ブログの設定」で「更新時にweblogsアップデート通知サービスへPingを送りますか?」が「はい」に設定されている時に限り、新しいアイテムを追加した時に呼び出されます(このイベントに対応しているプラグインがインストールされている時に限る)。このイベントはPing送信プラグインで各種「ブログ検索サービス」へ更新pingを送信します(例えばGoogleブログ検索など)
blogid
アイテムが追加されたブログのID
JustPosted (v3.3)投稿された未来の日付のアイテムの設定時刻が来た時。このイベントはページの表示が完了した後に発生条件をチェックします。
blogid
未来の日付のアイテムの設定時刻が来たブログのID
RegistrationFormExtraFields (v3.40) createaccount.php からビジターに表示されるアカウント作成フォームが表示され、FormExtra イベントが起きる前。プラグインはこのイベントによって、アカウント作成フォームに独自のフィールドを付け加える事が出来ます。PostRegister イベントに同時に登録すると、付け加えたフィールドの値を評価する事が出来る様になります。渡されるパラメータは、付け加えられたフィールドを、元々のフィールドと違和感無く表示させる為に使用されます。このイベントの使用例はNP_Profileプラグインを参照してください。
type
アカウント作成フォームのタイプ。通常は createaccount.php
prelabel
追加フィールドの「ラベル」の前に挿入される HTML コード
postlabel
追加フィールドの「ラベル」の後に挿入される HTML コード
prefield
追加フィールドの「入力フィールド」の前に挿入される HTML コード
postfield
追加フィールドの「入力フィールド」の後に挿入される HTML コード
TemplateExtraFields (v3.40) テンプレートが編集・更新される時。プラグイン製作者がコアのテンプレートシステムをより使いやすくするために、テンプレートにフィールドを追加する事が出来ます。プラグイン作者は追加するテンプレートフィールドの初期状態をプラグインオプションに保存し、そこで使用するテンプレート変数についてのドキュメントを書くことが要求されます。また、このイベントに関するサンプルプラグインが、フォーラムの新API「TemplateExtraFields」を使ったプラグインの見本(本家フォーラムのスレッドは Skin specific values for Plugins)にあります。
fields
プラグイン名をキーにした連想配列。配列の内容は、テンプレートのフィールド名をキーにした連想配列で、その値はフォームのフィールドに表示されるラベル。フィールド名は全て英数小文字で、フィールド名の重複を避けるためにプラグイン名を含んでいる事が好ましい。
PreArchiveListItem (v3.40) アーカイブリストが表示される前。アーカイブリストを表示するために使われたテンプレートのアーカイブリスト本体フィールドのテンプレート変数を追加/修正することを可能にします。追加のテンプレート変数についてのドキュメントも整備すべきです。
listitem
テンプレート変数をキーにした連想配列。値はテンプレート変数に置き換えられる内容。この配列にキーと値のペアを追加する事で、新しい変数が追加できます。
PreCategoryListItem (v3.40) カテゴリーリストが表示される前。カテゴリーリストを表示するために使われたテンプレートのカテゴリーリスト本体フィールドのテンプレート変数を追加/修正することを可能にします。追加のテンプレート変数についてのドキュメントも整備すべきです。
listitem
テンプレート変数をキーにした連想配列。値はテンプレート変数に置き換えられる内容。この配列にキーと値のペアを追加する事で、新しい変数が追加できます。
PreBlogListItem (v3.40) ブログリストが表示される前。ブログリストを表示するために使われたテンプレートのブログリスト本体フィールドのテンプレート変数を追加/修正することを可能にします。追加のテンプレート変数についてのドキュメントも整備すべきです。
listitem
テンプレート変数をキーにした連想配列。値はテンプレート変数に置き換えられる内容。この配列にキーと値のペアを追加する事で、新しい変数が追加できます。
PreTemplateRead (v3.40) テンプレートが読み込まれる直前。読み込むテンプレートを変更する事が出来ます。NP_MultiLanguage はこのイベントを使用しています。
name
呼び出されるテンプレートの名前
CustomLogin (v3.40) Nucleus にログインする直前。ログインの手順をカスタマイズできます。外部認証を簡素化し、ログイン ID にメールアドレス等を使用出来る様になります。
login
ユーザーが「ログインID」フィールドに入力した文字列。Nucleus のメンバーとして登録されているなら、プラグイン側で外部認証された「ログインID」と Nucleus のそれを紐つけるべきです。そうでないとクッキーがセットされず、ページを移動するごとにログアウトしてしまいます。
password
ユーザーが「パスワード」フィールドに入力した文字列。
success
認証が成功したかどうかのフラグ。「1」が成功。失敗だと「0」。初期値は「0」。プラグイン側でセットします。
allowlocal
整数値。プラグイン側で外部認証に失敗した後に、Nucleus のログインを試すかどうかのフラグ。「1」が試す「0」が試さない。初期値は「1」プラグイン側でセットします。
PrePasswordSet (v3.50)パスワードを設定する時に呼び出されます。パスワードの強度をプラグインで設定することが出来ます。
password
ユーザーが入力したパスワード文字列
errormessage
エラーメッセージ。エラーが起きない場合は空白に設定します。
valid
設定しようとしているパスワードが妥当かどうかのフラグ。デフォルトは「真」。プラグインはこの値の妥当性を審査するべきです。
PostParseURL (v3.60) URLが完全にパースされた後( globalfunctions の ParseURL による)。selector() が実行されたりpath関連のglobal変数に何かがセットされる前にglobal変数を調整するのに便利。
type
生成するURLのタイプ(item, blog, ...)
info
解決される前のURL(この名前は以前の変数名であるpathinfoから来ています).
).
MediaUploadFormExtras (v3.60) Nucleusメディアマネージャのファイルアップロードページにフィールドを追加します。すべての出力が正しいXHTML 1.0 でなければなりません。PreMediaUpload イベントに同時に登録し、requestVar()を使って追加したフィールドから値を得ます。 データは渡されません。

オプションを保存するback to top

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

データベース・テーブルback to top

Nucleusテーブルへのアクセス

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

v3.5でNucleusはPDO等MySQL以外のデータベースハンドラのサポートをするようになりました。この機能はベータ実装ではありますが、プラグイン開発者はデータベースの呼び出しに使用する関数の「sql_*」への書き換えを始めてください。 基本的に、使用している全ての「mysql_*」関数を「sql_*」に置き換える必要があります。たとえばmysql_fetch_assoc($result)sql_fetch_assoc($result) に置き換えになります。 全ての関数を書き換えたら、Sql APIが無い古いバージョンのNucleusインストールできないように、次に示すコードをプラグイン内に記述して、インストールに必要な最低バージョンを350に指定する必要があります。
function getMinNucleusVersion( return '350';)

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

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メソッドの中でそれを削除するようにします。

いくつかの注意点

プラグイン管理エリアback to top

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

考慮すること

PluginAdmin クラス

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

プラグイン用ヘルプページ back to top

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

プラグイン依存チェック back to top

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

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

プラグインの多国語化back to top

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

あなたと同じ言葉を話さない世界中の人達がプラグインをより使いやすくするために、プラグインを多国語化できます。 少し手間は増えますが、プラグインが出力する文章を翻訳するだけで可能です。 以下に 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 = preg_replace( '#\\\\|/#', '', getLanguageName());
          if (file_exists($this->getDirectory().$language.'.php'))
             include_once($this->getDirectory().$language.'.php');
          else
             include_once($this->getDirectory().'english.php');
       }
    このコードは Nucleus のコアで使用されているものと同一です。
  7. 言語ファイルの追加 「英語」が基本の言語になっていますので、「英語」の言語ファイルも追加することが望まれます。

スキン変数の出力の書式 back to top

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

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

Nucleus の各ページへのリンクを生成する為に便利な変数とファンクション
名前種類引数説明
$CONF['AdminURL'] グローバル変数 なし Nucleus の管理領域への絶対 URL
$CONF['PluginURL'] グローバル変数 なし Nucleus のプラグインディレクトリへの絶対 URL。$CONF['PluginURL'].'pluginname/' の様にして、プラグインの管理エリアへのリンク生成に使用する。
$CONF['ActionURL'] グローバル変数 なし Nucleus の action.php への絶対 URL。
$CONF['MediaURL'] グローバル変数 なし Nucleus のメディアディレクトリへの絶対 URL。
$CONF['SkinsURL'] グローバル変数 なし Nucleus のスキンディレクトリへの絶対 URL。
$CONF['IndexURL'] グローバル変数 なし Nucleus のメインディレクトリへの絶対 URL。
$DIR_NUCLEUS グローバル変数 なし Nucleus のメインディレクトリへのシステムルートからのフルパス。
$DIR_SKINS グローバル変数 なし Nucleus のスキンディレクトリへのシステムルートからのフルパス。
$DIR_MEDIA グローバル変数 なし Nucleus のメディアディレクトリへのシステムルートからのフルパス。
$DIR_PLUGINS グローバル変数 なし Nucleus のプラグインディレクトリへのシステムルートからのフルパス。
$DIR_LANG グローバル変数 なし Nucleus の言語ファイルディレクトリへのシステムルートからのフルパス。
$DIR_LIBS グローバル変数 なし Nucleus のコアディレクトリへのシステムルートからのフルパス。
getAdminURL() PLUGIN クラス内メソッド なし プラグインの管理エリアディレクトリが存在すればその URL を返す(存在しない場合は無効)。
getDirectory() PLUGIN クラス内メソッド なし プラグインの追加ファイルが格納されたサーバーのファイルシステムのパスを返します(存在しない場合は無効)。結果は".../nucleus/plugins/plugname/"のようになります。
createItemLink($itemid, $extra = '') グローバルファンクション $itemid 整数。リンクしたいアイテムの ID。
$extra 連想配列。「キー」と「値」のペアが、URL の「パラメータ」と「値」に反映される。
ユーザーによって選択されたスキームにより、 $itemid に対応したアイテムへのリンクが生成されます。
createMemberLink($memberid, $extra = '') グローバルファンクション $memberid 整数。リンクしたい存在するメンバーの ID。
$extra 連想配列。「キー」と「値」のペアが、URL の「パラメータ」と「値」に反映される。
ユーザーによって選択されたスキームにより、 $memberid に対応したメンバーへのリンクが生成されます。
createCategoryLink($catid, $extra = '') グローバルファンクション $catid 整数。リンクしたいカテゴリーの ID。
$extra 連想配列。「キー」と「値」のペアが、URL の「パラメータ」と「値」に反映される。
ユーザーによって選択されたスキームにより、 $catid に対応したカテゴリーへのリンクが生成されます。
createArchiveListLink($blogid = '', $extra = '') グローバルファンクション $blogid 整数。リンクしたいアーカイブ一覧が存在ブログの ID。
$extra 連想配列。「キー」と「値」のペアが、URL の「パラメータ」と「値」に反映される。
ユーザーによって選択されたスキームにより、 $blogid に対応したアーカイブ一覧へのリンクが生成されます。
createArchiveLink($blogid, $archive, $extra = '') グローバルファンクション $blogid 整数。リンクしたい月別アーカイブが存在するブログの ID。
$archive 文字列。アーカイブのパラメータとして、渡した「日(または年、月)」のものが存在するもの。
$extra 連想配列。「キー」と「値」のペアが、URL の「パラメータ」と「値」に反映される。
ユーザーによって選択されたスキームにより、 $blogid に対応した月別アーカイブへのリンクが生成されます。
createBlogidLink($blogid, $extra = '') グローバルファンクション $blogid 整数。リンクしたいブログの ID。
$extra 連想配列。「キー」と「値」のペアが、URL の「パラメータ」と「値」に反映される。
ユーザーによって選択されたスキームにより、 $blogid に対応したブログへのリンクが生成されます。

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

  1. プラグインのオプションを使う方法。この方法は v3.2 以降で使用でき、次のように install() メソッド に記述する事によって簡単に作成する事が出来ますが、アップグレードのためにプラグインを削除した時に、ユーザーは同時にカスタマイズした テンプレートを失ってしまうという大きなデメリットがあります。
    $this->createOption('my_template',
    		'プラグインの出力の為のテンプレート',
    		'textarea',
    		'<li><%foo%> loves <%bar%></li>');
    doSkinVar() メソッドで、foobar を次のように定義して、テンプレートを埋めます。
    $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);
    }

この他にも…… back to top

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

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