Movable Type オブジェクト・リファレンス

概要

package MyPlugin;

use base 'MT::Plugin';
use vars qw($VERSION);
$VERSION = 1.12;

my $plugin = new MyPlugin({
    name => 'My Plugin',
    version => $VERSION,
    author_name => 'Conan the Barbaraian',
    author_link => 'http://example.com/',
    plugin_link => 'http://example.com/mt-plugins/example/',
    description => 'Frobnazticates all Diffyhorns',
    config_link => 'myplugin.cgi',
    settings => new MT::PluginSettings([
        ['option1', { Default => 'default_setting' }],
        ['option2', { Default => 'system_default', Scope => 'system' }],
        ['option2', { Scope => 'blog' }],
    ]),
    config_template => \&config_tmpl
});
MT->add_plugin($plugin);

# Alternatively, instantiating MT::Plugin itself

my $plugin = new MT::Plugin({
    name => "Example Plugin",
    version => 1.12,
    author_name => "Conan the Barbarian",
    author_link => "http://example.com/",
    plugin_link => "http://example.com/mt-plugins/example/",
    description => "Frobnazticates all Diffyhorns",
    config_link => 'myplugin.cgi',
    doc_link => <documentation URL>,
    settings => new MT::PluginSettings([
        ['option1', { Default => 'default_setting' }],
        ['option2', { Default => 'system_default', Scope => 'system' }],
        ['option2', { Scope => 'blog' }],
    ]),
    config_template => \&config_tmpl
});
MT->add_plugin($plugin);

解説

MT::Pluginオブジェクトは、ユーザーがプラグインの動作を理解して設定を行うことができるように、プラグインの情報を保持します。通常、プラグインはMT::Pluginオブジェクトを生成して、MTクラスのadd_pluginメソッドに渡します。

MT->add_plugin($plugin);

これはMovable Typeのシステム・メニューのプラグイン一覧に、プラグインに関する追加情報を表示させるために用います。

コールバックを追加する場合には、pluginオブジェクトも用います。このオブジェクトは、コールバックの実行時に発生したエラーを特定する際に用います。たとえば、MT::Fooオブジェクトをデータベースに保存する前に実行するコールバック関数を追加するには、以下のように呼び出しを行います。

MT::Foo->add_callback("pre_save", 10, $plugin, \&callback_function);

この呼び出しでは、callback_functionという名前の*コールバック関数*を、すべての*保存*処理の直前に呼び出すよう、MT::Fooに指示するものです。10という数値は、異なるプラグインを呼び出すときの優先順位を示すもので、数字の若いコールバックほど優先順位が高くなります。

引数

key

keyは必須ではありませんが、推奨されるプラグイン要素です。この値はプラグインの識別に用いられるもので、バージョン変更時に変更してはなりません。keyは、MT::PluginDataパッケージを使ってプラグインの設定データを保存するときに用います。

name （必須）

人間が読解可能なプラグインの識別名を格納する文字列です。システム・メニューのプラグイン一覧に表示されます。

version

プラグインのリリース・バージョン番号です。各所のプラグイン一覧でプラグイン名の横に表示されます。必須ではありませんが、推奨されます。

schema_version

プラグインでいくつかのオブジェクト・クラスを宣言している場合、これらのクラスのインストールまたはアップグレードが必要かどうかを判断するためにschema_versionを用います。Movable Typeでは、プラグインのschema_versionをMT::Configテーブルに保存し、参照できるようになっています。

description

nameより長めの文字列で、プラグインの動作に関する簡単な説明文を指定します。

doc_link

プラグインのドキュメントのURLです。プラグインの配布パッケージ内でドキュメントを参照する相対パスか、サイト外のドキュメントを参照する絶対URLを指定します。

config_link

プラグインの設定を行うためのCGIスクリプトその他のインターフェースへの相対パスです。*プラグイン・エンベロープ*（mt/plugins以下にある、当該プラグインの全ファイルが存在するディレクトリ）からの相対パスで指定します。

author_name

プラグイン開発者の個人名または会社名です。

author_link

プラグイン開発者である個人または会社のホームページのURLです。

plugin_link

プラグイン自体のホームページのURLです。

config_template

プラグイン設定画面用のテンプレート（HTML::Template型）をファイル名で指定します。何らかのコードへのリファレンスを指定することもできます。その場合、MTは指定されたコードを呼び出し、以下の3つの引数を渡します。プラグイン・オブジェクトのインスタンス名、HTML::Templateのパラメータ・データへのハッシュ・リファレンス、およびスコープの指定（システム全体をスコープとする場合は"system"、特定のブログをスコープとする場合はアクティブなブログのIDをNとして"blog:N"の形で指定します）。

system_config_template

システム全般のプラグイン設定画面用のテンプレート（HTML::Template型）をファイル名で指定します。指定しない場合はconfig_templateで指定されたテンプレートが用いられます。何らかのコードへのリファレンスを指定することもできます。その場合、MTは指定されたコードを呼び出し、以下の3つの引数を渡します。プラグインオブジェクトのインスタンス名、HTML::Templateのパラメータデータへのハッシュリファレンス、およびスコープの指定（この場合は"system"のみ指定可能）。

blog_config_template

ブログ別のプラグイン設定画面用のテンプレート（HTML::Template型）をファイル名で指定します。指定しない場合はconfig_templateで指定されたテンプレートが用いられます。何らかのコードへのリファレンスを指定することもできます。その場合、MTは指定されたコードを呼び出し、以下の3つの引数を渡します。プラグインオブジェクトのインスタンス名、HTML::Templateのパラメータデータへのハッシュリファレンス、およびスコープの指定（この場合はアクティブなブログのIDをNとして"blog:N"の形で指定します）です。

settings

プラグインの環境変数の値を指定します。

app_methods

一つまたは複数のアプリケーション・クラスの、カスタム・モード・ハンドラーを登録します。このパラメーターには、モードからハンドラーにマッピングするハッシュ・リファレンスに対して、パッケージ名からマッピングを行うハッシュ・リファレンスを指定します。たとえば次のように指定します。

app_methods => {
    'MT::MyPackage' => {
        'mode1' => \&handler1,
        'mode2' => \&handler2
    }
}

app_action_links

MT::App::CMSアプリケーション内のさまざまなページで表示する、プラグイン実行用のリンクを登録するために使用します。このキーの書式は以下の通りです。

app_action_links => {
    'MT::App::CMS' => { # application the action applies to
        'type' => {
            link => 'myplugin.cgi',
            link_text => 'Configure MyPlugin'
        }
    }
}

これはMT->add_plugin_actionの代わりに使用することができます。

app_itemset_actions

MT::App::CMSアプリケーション内のさまざまな項目リストで表示するプラグイン実行用の項目セットを登録するのに使用します。このキーの書式は以下の通りです。

app_action_links => {
    'MT::App::CMS' => { # application the action applies to
        'type' => {
            key => 'unique_action_name',
            label => 'Uppercase text',
            code => \&itemset_handler
        }
    }
}

これはMT::App::CMS->add_itemset_actionの代わりに使用することができます。

callbacks

コールバック・システムに、オブジェクトまたはアプリケーションのコールバックを登録するために使用します。これはMT->add_callbackの代わりに使用することができます。たとえば以下のように指定します。

callbacks => {
    'callback_name' => \&callback_handler,
    'another_callback' => {
        priority => 1,
        code => \&another_handler
    }
}

junk_filters

このキーを用いて、1つまたは複数の、迷惑コメント/トラックバックの検知フィルターを登録することができます。たとえば次のように指定します。

junk_filters => {
    'MyJunkFilter' => \&junk_filter_handler
}

これはMT->register_junk_filterの代わりに使用することができます。

init_app

プラグインでは、このパラメーターを使って、アプリケーション初期化時に実行するコードを定義することができます。すべてのMT::Appインスタンスで呼び出されるコードへのリファレンスを指定することもできます。たとえば次のように指定します。

init_app => \&init_app_routine

あるいは、次の例のように、MT::Appパッケージ名からコード・リファレンスへのマッピングを定義したハッシュ・リファレンスを指定することもできます。

init_app => {
    'MT::App::CMS' => \&init_cms_app_routine,
    'MT::App::Comments' => \&init_comments_app_routine,
}

init_request

プラグインでは、このパラメーターを使って、当該アプリケーションへの各HTTPリクエストの開始時に実行するルーチンを定義することができます。init_app同様、このパラメーターは、コード・リファレンスと、アプリケーション固有のルーチンのハッシュ・リファレンスのどちらも指定可能です。

template_tags

このパラメーターは、Movable Type用の独自のタグ・ハンドラーを宣言するために使用します。機能的にはMT::Template::Context->add_tagと同様です。パラメーターは、次の例のようにハッシュ・リファレンスとして指定します。

template_tags => {
    'TagName' => \&tag_handler
}

この方法で、複数のテンプレート・タグを登録することも可能です。

container_tags

このパラメーターは、Movable Type用の独自のコンテナ・タグを宣言するために使います。機能的にはMT::Template::Context->add_container_tagと同様です。この方法で、複数のコンテナ・タグを登録することも可能です。

container_tags => {
    'ContainerTag' => \&container_tag_handler
}

conditional_tags

このパラメーターは、Movable Type用の独自の条件タグを宣言するために使います。機能的にはMT::Template::Context->add_conditional_tagと同様です。この方法で、複数の条件タグを登録することも可能です。

conditional_tags => {
    'IfCondition' => \&conditional_tag_handler
}

global_filters

このパラメーターは、グローバル・タグ・アトリビュートを宣言するために使います。機能的にはMT::Template::Context->add_global_filterと同様です。この方法で、複数のグローバル・フィルターを登録することも可能です。

global_filters => {
    'attribute_name' => \&attribute_handler
}

text_filters

このパラメーターを使って、テキスト整形フィルターを宣言することができます。機能的にはMT->add_text_filterと同様です。この方法で、複数のフィルターを登録することも可能です。

text_filters => {
    'format_name' => { label => "My Text Format", code => \&formatter }
}

tasks

このパラメーターを使って、MT::TaskMgrが実行するシステム・タスクを登録することができます。このパラメーターの書式は以下の通りです。

tasks => {
    'task_id' => \&task_code,
    'weekly_task' => {
        name => "My Weekly Task",
        frequency => 24 * 60 * 60 * 7, # run every 7 days
        code => \&weekly_task_code
    }
}

登録する各タスクのキーとして用いるタスク識別子は、グローバルな範囲で一意でなければなりません。このため、プラグイン固有のプレフィクスまたはサフィックスを付加する必要があります。

MTのタスク・サブシステムについての詳細は、MT::TaskMgrを参照してください。

object_classes

MTのアップグレード処理で保持すべきMT::Objectの派生クラスのリストを宣言します。

object_classes => [ 'MyPlugin::Foo', 'MyPlugin::Bar' ]

当該オブジェクト・パッケージのスキーマも保持するため、schema_versionも併用してください。

upgrade_functions

データ操作やデータ変換を伴なう場合には、アップグレード関数を指定して処理する必要があります。アップグレード関数の宣言については、MT::Upgradeパッケージを参照してください。以下に一例を示します。

upgrade_functions => {
    'my_plugin_fix_field_a' => {
        version_limit => 1.1, # runs for schema_version < 1.1
        code => \&plugin_field_a_fixer
    }
}

メソッド

コンストラクター呼び出し時の上記の引数は、該当する値を返す*getter*メソッドでもあります。これ以外に、MT::Pluginには以下のメソッドが用意されています。

$plugin->init_app

MT::Pluginsのサブクラスでこのメソッドを宣言した場合、アプリケーション起動時にこのメソッドが呼び出されます。

$plugin->init_request

MT::Pluginsのサブクラスでこのメソッドを宣言した場合、アプリケーションが新しいリクエストの処理を開始したときにこのメソッドが呼び出されます。

$plugin->envelope

プラグインのパスを、MTディレクトリからの相対パスで返します。この値は、プラグインの読み込み時に自動的に決定されます。

$plugin->set_config_value($key, $value[, $scope]), $plugin->get_config_value($key[, $scope])

これらのメソッドを使うと、シンプルな構造の環境設定値を、容易に保存することができます。各プラグインのキーと値のペアが、データベース中のPluginDataテーブルに保存されます。これらのメソッドは次の例のように呼び出します。

$plugin->set_config_value($key, $value);
$value = $plugin->get_config_value($key);

キーの名前空間として、プラグイン・オブジェクトのnameフィールドが使用されます。したがって、他のプラグインのnameフィールドと同じnameを用いることは推奨されません。

$plugin->get_config_obj([$scope])

指定したプラグインと有効範囲（無指定の場合のデフォルト値は"system"）に関連づけられたMT::PluginDataオブジェクトを取得します。

$plugin->get_config_hash([$scope])

指定したプラグインに関連づけられた環境設定データを取得し、Perlのハッシュ・リファレンスとして返します。scope引数を省略した場合、有効範囲は"system"と見なされます。

$plugin->config_template($params[, $scope])

プラグインの環境設定フォームを出力するためのHTML::Templateオブジェクトを取得します。scope引数で有効範囲を指定することもできます（デフォルトは"system"です）。

my $system_tmpl = $plugin->config_template($params, 'system');
my $system_tmpl = $plugin->config_template($params);
my $blog_tmpl = $plugin->config_template($params, 'blog:1');

$plugin->config_vars([$scope])

指定した有効範囲での環境変数の名前の配列を返します。

$plugin->save_config($param[, $scope])

プラグインの環境設定フォームから送られた設定データを保存します。

my $param = { 'option1' => 'x' };
$plugin->save_config($param);            # saves system configuration data
$plugin->save_config($param, 'system');  # saves system configuration data
$plugin->save_config($param, 'blog:1');  # saves blog configuration data

$plugin->load_config($param[, $scope])

plugindataテーブルから環境設定データを読み込みます。

$plugin->load_tmpl($file[, ...])

プラグインのディレクトリを基準として、HTML::Templateオブジェクトを読み込みます。プラグイン・ディレクトリと、その直下にあるtmplディレクトリが検索対象となります。$fileより右側の引数は、HTML::Templateのコンストラクターにそのまま渡されます。

MT::PluginSettings

本モジュールでは、MT::PluginSettingsパッケージも宣言しています。このパッケージでは、プラグイン用の設定項目とそのデフォルト値を定義します。プラグインが環境設定データを要求した場合には、必ずこれらの設定が処理されます。以下の例のように指定します。

$plugin->{settings} = new MT::PluginSettings([
    ['option1', { Default => 'default_setting' }],
    ['option2', { Default => 'system_default', Scope => 'system' }],
    ['option2', { Scope => 'blog' }],
]);

設定項目には、デフォルト値、および適用される有効範囲が指定可能です。現在、指定可能な有効範囲は"system"と"blog:N"（NはブログID）です。