開発室ノート | プラグイン

Serene Bachでは、プラグインにより「追加機能」メニューに追加される管理画面を作成することができます。

例えば、sbでは標準の機能だった「アクセス解析」と「データ移行」はプラグインとして提供され、ユーザー側で自由に外すことができます。

管理用プラグインとして機能させるためにはregister_pluginの後、register_admin_moduleメソッドにより、管理用プラグインとして登録する必要があります。

sb::Plugin->register_admin_module(
  'mode'   => 'memo',
  'level'  => 1,
  'module' => 'sb::Admin::Memo',
);

register_admin_moduleメソッドにはmode, level, moduleという3つの引数があります。

modeは必ず指定する必要があります。これは管理画面で利用するモード名としても利用され、ユニークな名称を利用する必要があります。

以下の名称はシステムで予約されているので、利用できません。

• new
• edit
• list
• category
• upload
• amazon
• link
• profile
• comment
• trackback
• refuse
• user
• rebuild
• template
• editor
• config
• status
• help
• bm
• view
• login
• logout
• edittemp
• edituser

また、上記以外でも標準プラグインで利用されているaccesslog, convert, memoは混乱を避けるため、利用しない方がよいでしょう。

levelはそのメニューを利用できるユーザー管理レベルを規定します。この引数が無指定の場合、0として扱われます。

• 0 : 全ユーザー
• 1 : 上級ユーザー・管理ユーザー
• 2 : 管理ユーザーのみ

例えば、'level' => 1,と指定すると、その管理用プラグインは上級ユーザーと管理ユーザーが利用できます。

moduleは管理用プラグインを実装しているパッケージ名を指定します。moduleが無指定の場合、カレントパッケージ(プラグイン内のパッケージ)名がmoduleとして利用されます。

ここで指定されたパッケージには必ず「callback」というサブルーチンを定義しておく必要があります。

コンテンツ用プラグインで登録したコールバック関数で受け取るハッシュ%varには、コンテンツ表示に必要だと思われる様々な情報が含まれています。

特に利用頻度の高い変数には以下のものがあります。

コンテンツ用のプラグインで指定されたコールバック関数の第一引数はsb::TemplateManagerインスタンスになります。

sb::TemplateManagerを通して、独自タグの置換操作・独自ブロックの表示数指定を行います。

sb::TemplateManagerのインスタンスは慣例上、$cmsという変数を利用します。以下、特に断りがない場合、$cmsはsb::TemplateManagerのインスタンスを示します。

コンテンツ用プラグインにおいて、利用するsb::TemplateManagerのメソッドは3つです。

• tag
• block
• num

tag

独自タグの置換操作を行います。

$cms->tag('tag_name'=>'hogehoge');

ここでtag_nameは独自タグ名です。独自タグは{tag_name}という形式ですが、このうち先頭の「{」と末尾の「}」を省いた文字列になります。

block

独自ブロックの表示数指定(該当ブロックの繰り返し表示数)を行います。

$cms->block('block_name'=>1);

ここでblock_nameは独自ブロック名です。独自ブロックは<!-- BEGIN block_name -->と<!-- END block_name -->という形式で表現されますが、このうちblock_nameにあたる文字列になります

num

独自タグの対象ブロック番号を指定します。

$cms->num(0);

原則として、tagメソッドを呼び出す前に宣言する必要がありますが、"type" => "main"以外のコンテンツ用プラグインではプラグインが呼び出される前に必ず呼び出されているので、通常利用する必要はありません。

コンテンツ用プラグインは、記事やプロフィール情報をテンプレートデータに展開する際に呼ばれます。

コンテンツ用プラグイン登録register_content_moduleメソッドの「callback」で指定したサブルーチンが呼び出されます。

register_content_moduleメソッドで指定する「type」によって、コールバック関数の引数が変わります。

最初の引数は必ずsb::TemplateManagerインスタンスで、最後の引数(厳密には残りの引数)は環境設定・記事情報などをひとまとめにしたハッシュ(連想配列)になっています。

"type" => "main"以外のコールバック関数では、第二引数として対象となるデータオブジェクトのインスタンスが格納されます。

   sub _topmemo {
     my $cms = shift;
     my %var = @_;
     # 以下、処理内容
     return 1;
   }

"type" => "main"のコールバック関数では、register_content_moduleメソッドで指定する「field」と同名の独自ブロックを処理します。そのブロックの繰り返し数を返り値としてreturnする必要があります。

例えば、上述の例は「ちょっと一言」プラグインから引用していますが、「field」として「topmemo」が指定されています。返り値が1の場合、<!-- BEGIN topmemo -->〜<!-- END topmemo -->領域が1度だけ表示されます。返り値として、0を返すと、該当領域は非表示になります。

   sub content {
     my $cms = shift;
     my $entry = shift;
     my %var = @_;
     # 以下、処理内容
   }

"type" => "main"以外のコールバック関数では、返り値を指定する必要はありません。

"type" => "main"以外のコールバック関数では、第二引数として対象となるデータオブジェクトのインスタンスを受け取ります。このインスタンスの実体はsb::Data::Objectを継承したSerene Bachのデータオブジェクトです。

上記の例では、$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, nameという4つの引数があります。

typeは必ず指定する必要があります。コンテンツ用プラグインが適用される種類を指定します。以下の5つからいずれかのtypeが指定されます。

• main
• entry
• comment
• trackback
• profile

callbackは必ず指定する必要があります。コールバック関数のリファレンスを指定します。

上記例では、パッケージsb::Content::Memo内にある_topmemoというサブルーチンのリファレンスを指定しています。

typeによって適用されるコールバック関数の引数が変わります。

fieldでは指定したtype内におけるコンテンツ用プラグインの適用フィールドを指定します。fieldが未指定の場合、nameの値が利用されます。

fieldはtypeが「main」の時と、「main」以外の時(entry, comment, trackback, profile)で意味合いが異なります。

typeが「main」の時は、処理する独自ブロック名を示します。

上記の例ではtopmemoという独自ブロックを追加するため、fieldに「topmemo」と指定されています。

標準で処理されている独自ブロックの処理を置き換える場合には、置き換える独自ブロック名を指定します。

type => mainで処理される標準独自ブロックは以下の通りです。

• title
• archives
• category
• link
• recent_comment
• recent_trackback
• latest_entry
• selected_entry
• profile
• calendar
• amazon
• page
• option

typeが「main」以外の時(entry, comment, trackback, profile)では、特定の独自ブロックだけを処理します。

entry

entryブロックを処理します。以下のfieldが標準で定義されています。

• date_time
• authors
• attach
• category
• body_text
• discovery
• sequel
• others

comment

comment_area並びにcommentブロックを処理します。_contentというfieldが定義されています。

trackback

trackback_area並びにtrackbackブロックを処理します。_contentというfieldが定義されています。

profile

profile_areaブロックを処理します。_contentというfieldが定義されています。

また、typeによらず、「_main」という特殊なfieldが標準で定義されています。

コンテンツ用プラグインで「_main」フィールドの置き換えも可能ですが、その際には標準の処理サブルーチンを明示的に呼び出すことを強く推奨します。

nameはコンテンツ用プラグイン毎につけるユニークな名称を指定します。未指定(空もしくは未定義)の場合は、プラグイン名が利用されます。

ひとつのプラグインにつき、ひとつのコンテンツ用モジュールを登録するだけならnameを指定する必要はありません。ひとつのプラグインで複数のコンテンツ用モジュールを登録する場合、それぞれのモジュール毎にユニークな名称をつけます。

Serene Bachではプラグイン毎に独立したデータをプラグインAPIを通して簡単に取り扱うことができます。

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というsb::Data::Objectを継承したSerene Bachのデータオブジェクトです。

sb::Data::Pluginには以下のようなフィールドがあります。

• data
• text
• setting
• date
• url
• mail
• extra

他にid, wid, nameというフィールドがありますが、これらはシステムで利用されるフィールドで通常プラグイン側で利用することはありません。

data, textなどのように便宜的に汎用的な名称が付けられていますが、各フィールドの中身自体はurlとmailを除き、特別な処理は行われていませんので、プラグイン側で自由に定義してご利用いただけます。

# urlとmailは出力時に簡単なアドレスチェックを行います。無効なurl・無効なメールアドレスが指定された場合には空出力されます。ですから、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つ方法があります。

1. プラグインAPIを利用する
2. sb::Dataによってハンドリングする

上記例ではプラグイン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でデータ更新処理を行うことを強く推奨します。

Serene Bachではプラグイン毎に独立してリソースファイルを持つことができます。

リソースファイルは必須ではありませんが、言語毎にそのプラグイン情報を記述できます。

また、言語リソース(エラーメッセージなど)の追加・書き換えなどの動作も可能です。

リソースファイルは以下のように記述されます。

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, detailはプラグイン情報として利用されます。admin moduleでは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

Serene Bachではプラグインは専用のAPIをコールすることで、プラグインとして登録されます。

典型的なプラグインの登録ルーチンを以下に示します。

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, dataという4つの大項目があります。

これらの値は必須ではありませんので、以下のように省略しても構いません。

sb::Plugin->register_plugin();

言語設定langでは、プラグイン並びにリソースファイルの文字コードを指定します。そのプラグインで利用する文字コードは統一しておく必要があり、またここで文字コードを明示しておく必要があります。

テキスト情報textではプラグイン名称などを記述します。この中のnameはadmin moduleではメニューの名称にも利用されます。

テキスト情報textの内容は後述するリソースファイルにも記述できます。リソースファイルを利用した場合、リソースファイルの内容が優先して利用されます。

リソースファイル名fileではリソースファイルの名称を指定します。この項目が存在しないあるいは空の場合はリソースファイルは利用されません。

プラグインデータdataではプラグインAPIを介したプラグインデータを利用するかどうかを設定します。

プラグインデータを利用する場合には'data' => 1,のようにdataに対して「1」を設定します。

Serene Bachには機能拡張の仕組みとして「プラグイン」という機構が用意されています。

プラグインは基本的にperlのスクリプトとして提供され、特定ディレクトリにインストールすることでSerene Bachに認識することができます。

# デフォルトではベースディレクトリ上の「plugin」がプラグインディレクトリです。

プラグインには以下のような種類があります。

追加モジュールの種類として、以下のようなものがあります。

いずれのプラグインもSerene Bach上で正しく動作させるためには、sb::Pluginモジュールを通した登録処理を行う必要があります。