例えば、sbでは標準の機能だった「アクセス解析」と「データ移行」はプラグインとして提供され、ユーザー側で自由に外すことができます。
管理用プラグインとして機能させるためには
の後、register_plugin
メソッドにより、管理用プラグインとして登録する必要があります。register_admin_module
sb::Plugin->register_admin_module( 'mode' => 'memo', 'level' => 1, 'module' => 'sb::Admin::Memo', );
メソッドにはregister_admin_module
, mode
, level
という3つの引数があります。module
は必ず指定する必要があります。これは管理画面で利用するモード名としても利用され、ユニークな名称を利用する必要があります。mode
以下の名称はシステムで予約されているので、利用できません。
また、上記以外でも標準プラグインで利用されているaccesslog, convert, memoは混乱を避けるため、利用しない方がよいでしょう。
はそのメニューを利用できるユーザー管理レベルを規定します。この引数が無指定の場合、0として扱われます。level
例えば、
と指定すると、その管理用プラグインは上級ユーザーと管理ユーザーが利用できます。'level' => 1,
は管理用プラグインを実装しているパッケージ名を指定します。module
が無指定の場合、カレントパッケージ(プラグイン内のパッケージ)名がmodule
として利用されます。module
ここで指定されたパッケージには必ず「
」というサブルーチンを定義しておく必要があります。callback
特に利用頻度の高い変数には以下のものがあります。
ハッシュキー | 種類 | 内容 |
---|---|---|
mode | 文字列 | 選択されているモードを示します。 |
conf | object | 環境設定オブジェクトが格納されています。$var{'conf'}->value('conf_srv_base')のようにvalueメソッドにより環境設定の読み出しができます(この場合、トップページのアドレスが取得できます)。 |
lang | object | 言語設定オブジェクトが格納されています。日本語リソースに格納された文字列を読み出すときに利用します。 |
blog | object | ウェブログ名などいくつかのウェブログデータを収めたデータオブジェクトが格納されています。 |
user | ハッシュ | ウェブログユーザー情報がユーザーidをキーとするハッシュの形で格納されています。 |
cat | ハッシュ | カテゴリーデータがカテゴリーidをキーとするハッシュの形で格納されています。 |
entryinfo | ハッシュ | 月別・カテゴリー別の記事数などの記事情報が格納されています。 |
sb::TemplateManager
インスタンスになります。
を通して、独自タグの置換操作・独自ブロックの表示数指定を行います。sb::TemplateManager
のインスタンスは慣例上、sb::TemplateManager
という変数を利用します。以下、特に断りがない場合、$cms
は$cms
のインスタンスを示します。sb::TemplateManager
コンテンツ用プラグインにおいて、利用する
のメソッドは3つです。sb::TemplateManager
$cms->tag('tag_name'=>'hogehoge');
ここで
は独自タグ名です。独自タグはtag_name
という形式ですが、このうち先頭の「{」と末尾の「}」を省いた文字列になります。{tag_name}
$cms->block('block_name'=>1);
ここで
は独自ブロック名です。独自ブロックはblock_name
と<!-- BEGIN block_name -->
という形式で表現されますが、このうち<!-- END block_name -->
にあたる文字列になりますblock_name
$cms->num(0);
原則として、tagメソッドを呼び出す前に宣言する必要がありますが、
以外のコンテンツ用プラグインではプラグインが呼び出される前に必ず呼び出されているので、通常利用する必要はありません。 "type" => "main"
コンテンツ用プラグイン登録
メソッドの「callback」で指定したサブルーチンが呼び出されます。register_content_module
メソッドで指定する「type」によって、コールバック関数の引数が変わります。register_content_module
type | コールバック関数の引数 |
---|---|
main |
|
entry |
|
comment |
|
trackback |
|
profile |
|
最初の引数は必ず
インスタンスで、最後の引数(厳密には残りの引数)は環境設定・記事情報などをひとまとめにしたハッシュ(連想配列)になっています。sb::TemplateManager
以外のコールバック関数では、第二引数として対象となるデータオブジェクトのインスタンスが格納されます。"type" => "main"
sub _topmemo {
my $cms = shift;
my %var = @_;
# 以下、処理内容
return 1;
}
のコールバック関数では、"type" => "main"
メソッドで指定する「field」と同名の独自ブロックを処理します。そのブロックの繰り返し数を返り値としてreturnする必要があります。register_content_module
例えば、上述の例は「ちょっと一言」プラグインから引用していますが、「field」として「topmemo」が指定されています。返り値が1の場合、<!-- BEGIN topmemo -->〜<!-- END topmemo -->領域が1度だけ表示されます。返り値として、0を返すと、該当領域は非表示になります。
sub content {
my $cms = shift;
my $entry = shift;
my %var = @_;
# 以下、処理内容
}
以外のコールバック関数では、返り値を指定する必要はありません。"type" => "main"
以外のコールバック関数では、第二引数として対象となるデータオブジェクトのインスタンスを受け取ります。このインスタンスの実体は"type" => "main"
を継承したSerene Bachのデータオブジェクトです。sb::Data::Object
上記の例では、
という変数に記事データオブジェクト$entry
のインスタンスが格納されます。例えば、sb::Data::Entry
というアクセサにより、記事タイトルを取得できます。$entry->subj
Serene Bachでは既存の独自ブロックを置き換えるプラグインを有効にすると、基本的に標準動作の代わりにプラグインが動作するようになります。
もし既存の独自ブロック内部に追加する形で動作させたいなどの場合は、プラグイン側で明示的に標準動作をハンドリングしているサブルーチンを呼び出す必要があります。
コンテンツ用プラグインとして機能させるためには
の後、register_plugin
メソッドにより、管理用プラグインとして登録する必要があります。register_content_module
sb::Plugin->register_content_module( 'type' => 'main', 'callback' => &sb::Content::Memo::_topmemo, 'field' => 'topmemo', 'name' => undef, );
メソッドにはregister_content_module
, type
, callback
, field
という4つの引数があります。name
typeは必ず指定する必要があります。コンテンツ用プラグインが適用される種類を指定します。以下の5つからいずれかのtypeが指定されます。
は必ず指定する必要があります。コールバック関数のリファレンスを指定します。callback
上記例では、パッケージ
内にあるsb::Content::Memo
というサブルーチンのリファレンスを指定しています。_topmemo
type
によって適用されるコールバック関数の引数が変わります。
では指定したfield
内におけるコンテンツ用プラグインの適用フィールドを指定します。type
が未指定の場合、field
name
の値が利用されます。
はfield
が「main」の時と、「main」以外の時(entry, comment, trackback, profile)で意味合いが異なります。type
が「main」の時は、処理する独自ブロック名を示します。type
上記の例では
という独自ブロックを追加するため、topmemo
に「topmemo」と指定されています。field
標準で処理されている独自ブロックの処理を置き換える場合には、置き換える独自ブロック名を指定します。
で処理される標準独自ブロックは以下の通りです。type => main
が「main」以外の時(entry, comment, trackback, profile)では、特定の独自ブロックだけを処理します。type
field
が定義されています。field
が定義されています。field
が定義されています。また、
によらず、「_main」という特殊なtype
が標準で定義されています。field
コンテンツ用プラグインで「_main」フィールドの置き換えも可能ですが、その際には標準の処理サブルーチンを明示的に呼び出すことを強く推奨します。
はコンテンツ用プラグイン毎につけるユニークな名称を指定します。未指定(空もしくは未定義)の場合は、プラグイン名が利用されます。name
ひとつのプラグインにつき、ひとつのコンテンツ用モジュールを登録するだけなら
を指定する必要はありません。ひとつのプラグインで複数のコンテンツ用モジュールを登録する場合、それぞれのモジュール毎にユニークな名称をつけます。name
my $data = sb::Plugin->get_data; $data->data($cgi->value('topmemo')); $data->setting($cgi->value('topmemo_breaks')); $data->date($self->{'time'}); sb::Plugin->set_data('data'=>$data);
プラグインデータの実体は
というsb::Data::Plugin
を継承したSerene Bachのデータオブジェクトです。sb::Data::Object
には以下のようなフィールドがあります。sb::Data::Plugin
他に
, id
, wid
というフィールドがありますが、これらはシステムで利用されるフィールドで通常プラグイン側で利用することはありません。name
, data
などのように便宜的に汎用的な名称が付けられていますが、各フィールドの中身自体はtext
とurl
を除き、特別な処理は行われていませんので、プラグイン側で自由に定義してご利用いただけます。mail
#
とurl
は出力時に簡単なアドレスチェックを行います。無効なurl・無効なメールアドレスが指定された場合には空出力されます。ですから、mail
とurl
のフィールドはアドレスチェッカとして利用することができます。mail
によってデータオブジェクトを取得できます。上記例ではsb::Plugin->get_data
という変数にデータオブジェクトを格納(代入)しています。$data
取得したデータオブジェクトに対してフィールド名のアクセサ(入出力関数)が利用できます。Serene Bachのデータオブジェクトには入出力(set/get)を兼用したアクセサを利用します。
my $data = sb::Plugin->get_data; print $data->data; # 出力(get) : data フィールドの内容を取得 $data->data('new_data'); # 入力(set) : data フィールドに 'new_data' をセット
フィールドの内容を取得する時には基本的に引数は必要ありません(他のデータオブジェクトには出力時に引数を必要とするアクセサもあります)。
フィールドの内容を更新する際には更新したい内容を引数として同一名称のアクセサを呼び出します。
Serene Bachのデータオブジェクトはデータを更新してもそのままではファイル(データベース)には反映されません。
更新したデータオブジェクトの内容をファイル(データベース)に反映させるには2つ方法があります。
上記例ではプラグインAPIを利用しています。
と対になるget_data
というメソッドを呼び出します。set_data
sb::Plugin->set_data('data'=>$data);
と異なり、get_data
という形の引数が必要になることに注意してください。'data'=>データオブジェクト
後者は
モジュールに用意されているsb::Data
メソッドを利用する方法です。update
sb::Data->update($data);
この方法で更新されたデータオブジェクト
をファイル(データベース)に反映させることができます。$data
ただし、通常プラグインデータを取り扱う際にはプラグインAPIを通した
でデータ更新処理を行うことを強く推奨します。sb::Plugin->set_data
リソースファイルは必須ではありませんが、言語毎にそのプラグイン情報を記述できます。
また、言語リソース(エラーメッセージなど)の追加・書き換えなどの動作も可能です。
リソースファイルは以下のように記述されます。
type[tab]管理用
name[tab]データ移行
text[tab]外部データ読み込みとデータ書出し
author[tab]takkyun
detail[tab]http://serennz.cool.ne.jp/sblog/
# resources
resource[tab]parts_import[tab]件のエントリーを取り込みました。
resource[tab]error_import_cond[tab]パスワードが設定されていません。
resource[tab]error_no_data[tab]読み込むデータがありません。
# [tab]はタブコードを示しています。グローバル環境設定の記述とは異なり、いわゆる半角スペースでは正しく認識されませんのでご注意ください。
, name
, text
, author
はプラグイン情報として利用されます。admin moduleではdetail
name
が追加機能のメニュー名としても利用されます。
行頭に
がある行はコメント行として無視されます。#
は言語リソースとして追加する文字列を規定します。resource
resource[tab]label[tab]内容
のように記述され、
で設定した文字列を呼び出すことができます。sb::Language->get->string('label')
リソースファイルの文字コードはプラグイン内に記述します。
文字コードはEUC-JP
, Shift_JIS
, iso-2022-jp
, UTF-8
が利用可能です。プラグインとリソースファイルの文字コードは同一に設定するようにしてください。
プラグインでは利用者がどの文字コードを利用しているかは基本的に意識する必要はありません。
ただし、外部ファイルの読込みやアクセスログの表示などソースとなるデータの文字コードが状況によって変化するような場合はこの限りではありません。
Serene Bachのプラグインではリソースファイルだけでなく、管理画面のテンプレートなどもリソースとしてプラグインディレクトリ内のリソースディレクトリに置くことができます。これらのファイルはSerene Bachで用意されているプラグインAPIを利用することで読み込むことができます。
リソースファイルはプラグインディレクトリ内にあるリソースディレクトリ内に置かれます。
日本語のリソースは
に置かれ、言語に依存しないリソースはplugin/resource/ja/
に置かれることを想定しています。plugin/resource/
plugin/ Memo.pm resource/ ja/ memo.txt memo.html]]>
典型的なプラグインの登録ルーチンを以下に示します。
use sb::Plugin (); sb::Plugin->register_plugin( 'lang' => { 'ja' => 'euc', 'en' => 'ascii', }, 'text' => { 'type' => 'admin, cms', 'name' => 'Short Message', 'text' => 'Writing short message on the top page.', 'author' => 'takkyun', 'detail' => 'http://serennz.cool.ne.jp/sblog/', 'version' => '0.00', }, 'file' => 'memo.txt', 'data' => 1, );
Serene BachのプラグインAPIを利用する際には、最初に
をロードする必要があります。上記例では、最初の行sb::Plugin
が該当します。use sb::Plugin ();
ここでは「use」を使っていますが、
としても構いません。require sb::Plugin;
次の行、
がプラグインの登録になります。sb::Plugin->register_plugin
のsb::Plugin
メソッドにより、プラグインを登録します。register_plugin
プラグインを登録すると、環境設定→プラグイン画面にて該当プラグインが表示されるようになります。
メソッドには引数を連想配列(ハッシュ)の形で記述します。register_plugin
# Serena BachではプラグインAPIに限らず、連想配列によるパラメータ引渡しが多用されていますので、この形式に慣れておくとプラグインの作成が容易になります。
sb::Plugin->register_plugin( 'lang' => { # 言語設定(文字コード) 'ja' => '', # 日本語 'en' => '', # 英語 }, 'text' => { # テキスト情報 'type' => '', # プラグインのタイプ 'name' => '', # プラグインの名称 'text' => '', # プラグインの簡単な説明 'author' => '', # プラグインの作成者 'detail' => '', # プラグイン配布先・詳細説明ページのアドレス 'version' => '', # プラグインのバージョン }, 'file' => '', # リソースファイル名 'data' => undef, # プラグインデータを利用するかどうか );
の引数にはregister_plugin
, lang
, text
, file
という4つの大項目があります。data
これらの値は必須ではありませんので、以下のように省略しても構いません。
sb::Plugin->register_plugin();
言語設定
では、プラグイン並びにリソースファイルの文字コードを指定します。そのプラグインで利用する文字コードは統一しておく必要があり、またここで文字コードを明示しておく必要があります。lang
テキスト情報
ではプラグイン名称などを記述します。この中のtext
はadmin moduleではメニューの名称にも利用されます。name
テキスト情報
の内容は後述するリソースファイルにも記述できます。リソースファイルを利用した場合、リソースファイルの内容が優先して利用されます。text
リソースファイル名
ではリソースファイルの名称を指定します。この項目が存在しないあるいは空の場合はリソースファイルは利用されません。file
プラグインデータ
ではプラグインAPIを介したプラグインデータを利用するかどうかを設定します。data
プラグインデータを利用する場合には
,のように'data' => 1
に対して「1」を設定します。data
プラグインは基本的にperlのスクリプトとして提供され、特定ディレクトリにインストールすることでSerene Bachに認識することができます。
# デフォルトではベースディレクトリ上の「plugin」がプラグインディレクトリです。
プラグインには以下のような種類があります。
項目 | 説明 |
---|---|
コンテンツ用プラグイン | 新しい独自ブロック・独自タグを定義したり、既存の独自ブロック・独自タグの動作を変更するプラグインです。 |
管理用プラグイン | 「追加機能」として新たに管理画面を追加するためのプラグインです。 |
テキストフィルタ | 記事の本文・続きのフォーマットを規定するプラグインです。 |
追加モジュール | 特定のタイミングで読み出され、標準動作を置き換えるためのプラグインです。 |
追加モジュールの種類として、以下のようなものがあります。
項目 | 説明 |
---|---|
カウンタ用 | アクセスログ収集ならびにカウンタ表示を行うスクリプトが起動したときに呼び出されます。 |
レシーバ用 | コメントないしトラックバックを受信した際に呼び出されます。 |
いずれのプラグインもSerene Bach上で正しく動作させるためには、sb::Pluginモジュールを通した登録処理を行う必要があります。
]]>