« 目次

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

MT

概要

use MT;
my $mt = MT->new;
$mt->rebuild(BlogID => 1)
    or die $mt->errstr;

解説

MTクラスは、Movable Typeの再構築/ping用のインターフェース本体で、再構築の操作のすべてを処理します。MTクラスでは、アプリケーション機能は扱いません。MTクラスのサブクラスであるMT::AppおよびMT::App::CMSクラスを参照してください。

プラグイン・アプリケーション

Movable Typeにアクセスしているユーザーは、Movable Typeのアプリケーション本体か、プラグイン・アプリケーション(サブアプリケーションとも呼びます)のどちらかにアクセスしています。

プラグイン・アプリケーションは、Movable Typeの機能を継承し、ユーザー側からはMovable Typeのコンポーネントとして動作しているように見える、ユーザー・インターフェースを備えたアプリケーションです。通常、プラグイン・アプリケーションには、独自の機能を表示するためのテンプレートがありますが、ナビゲーション・メニュー、システム・ツールバー、ブログ・ツールバーおよびやエラー・ページといったMovable Typeテンプレートの一部も継承します。

2つのルート(MTルートとアプリケーション・ルート)

Movable Typeでは、Movable Type本体とプラグインのファイルの置き場所として、mt_dirapp_dirのディレクトリを使用します。これらのディレクトリ名は、同名のMTクラスのメソッドを呼び出すことで取得できます。また、これらのディレクトリから派生するディレクトリ名を返すメソッドもあります。

mt_dirは、Movable Typeをインストールするルート・ディレクトリで、app_dirは、実行中のアプリケーションのルート・ディレクトリです。実行中のアプリケーションとは、Movable Type本体を指すこともあれば、プラグイン・アプリケーションを指す場合もあります。それぞれの違いと用途を理解しておくことが重要です。

mt_dirは、Movable Type自身が置かれているディレクトリへの絶対パスです。特に重要なのは、環境設定ファイルmt-config.cgiや、各種リクエストを実行するスクリプトが、ここに置かれているということです。このディレクトリは、Movable Type本体のテンプレートを探す際のデフォルトのベース・パスともなっています(ただし、これは、環境変数TemplatePathので変更可能です。)。

同様に、app_dir実行中のアプリケーションのルートになります。Movable Typeでは、アプリケーション別のテンプレートを見つけるためにapp_dirを検索しますが、mt_dirも検索対象となります。このため、Movable Type本体のヘッダー、フッター、エラー・ページ、あるいは場合によっては他のテンプレートも利用可能になります。

この仕組みが有効に働くためには、プラグインのテンプレートとコードはすべて同じディレクトリの配下に置く必要があります。app_dirからアプリケーションのテンプレートへの相対パスは独自に設定することが可能です。プラグインのテンプレートの場所の指定方法の詳細は、MT::Appを参照してください。

ルートパスの検索

プラグイン・アプリケーションが、アプリケーション・クラス(MT::Appのサブクラス)を初期化する際、mt_dirを見つけてコンストラクターに渡してやる必要があります。これはDirectoryパラメーターまたはConfigパラメーターから取得できます。

プラグインは、Movable Typeのルート・ディレクトリの配下から読み込まれます。プラグインを起動するコード側では、ファイルシステムを縦断することで、環境設定ファイルを見つける(そして、そこからルート・ディレクトリを見つける)ことができます。これは、環境設定ファイルへの絶対パスは、MT::App::newのConfigパラメーターとして渡されるからです。この例が、examples/plugins/mirror/mt-mirror.cgiにあります。

一方、app_dirは、必ず現在実行中のプログラムの場所をもとに判断するので、通常は指定する必要はありません。

利用方法

MTには、次のインターフェースが用意されています。どのメソッドも、実行に失敗するとundefを返し、該当するオブジェクトまたはクラス(そのメソッドがインスタンス・メソッドかクラス・メソッドかによります)のerrstrを設定します。詳細は、エラー処理の項を参照してください。

MT->new( %args )

MTの新規インスタンスを生成し、そのオブジェクトを返します。失敗した場合にはundefを返します。

newは、環境設定ファイルmt-config.cgiの内容も読み込みます(環境設定ファイルが読み込めなかったと思われる場合には、Configパラメーターを参照してください)。また、選択されているオブジェクト・ドライバー(デフォルトではDBMオブジェクト・ドライバー)の初期化も行います。%argsには、次の項目が指定可能です。

Config

環境設定ファイルへのパスです。パスを指定しなかった場合、カレント・ディレクトリ内で探そうとします。

Directory

MTルートへのパスです。パスを指定しなかった場合、環境設定ファイルへのパスとして見つかったパスを使用します。

MT->instance

MTとそのサブクラスは、すべてシングルトン・クラスです。つまり、パッケージあたりインスタンスを1つしか生成できないクラスです。MT->instance()メソッドは、アクティブなインスタンスを返します。現在、MT->new()はinstance_ofへのエイリアスとなっています。

$class->instance_of

$classに指定されたMTサブクラスの唯一のインスタンスを返します。

MT->set_instance

アクティブなMTインスタンスのオブジェクトを割り当てます。MT->instanceが呼び出されるとこの値が返されます。

$mt->find_config($params)

MTの環境設定ファイルの検索を行います。戻り値は環境設定ファイルのパスとファイル名です。$paramsパラメーターは、MTコンストラクターに渡されるパラメーターのハッシュへのリファレンスです。

$mt->read_config($params)

MTの環境設定ファイルの設定項目とデータベースを読み出します(MT::Config)。$paramsパラメーターは、MTコンストラクターに渡されるパラメーターのハッシュへのリファレンスです。

$mt->init_plugins

利用可能なすべてのプラグインを読み込みます。このメソッドは、read_configメソッドが環境設定ファイルを読み込んだ後、initメソッドから呼び出されます。

MT->unplug

MTインスタンスへのグローバル・リファレンスを削除します。

MT::log( $message ), $mt->log( $message )

アプリケーションのログ・テーブルにエントリーを追加し、STDERRにメッセージを書き込みます。通常、STDERRはWebサーバのエラー・ログにリダイレクトされています。

$mt->server_path
$mt->mt_dir

両メソッドともに、MTルート・ディレクトリへの物理的ファイル・パスを返します。MTのコンストラクターに渡されるDirectoryパラメーターの値となるか、あるいは環境設定ファイルのパスをもとに決定されます。

$mt->app_dir

アクティブなアプリケーションのディレクトリへの物理的ファイル・パスを返します。アクティブなスクリプトのあるディレクトリをもとに決定されます。

$mt->config_dir

環境設定ファイルへのパスを返します。

$mt->config([$setting[, $value]])

環境設定値の設定と取得を行います。パラメーターなしで呼び出した場合には、そのアプリケーションが使用するアクティブなMT::ConfigMgrインスタンスを返します。$settingパラメーターのみを指定すると、その設定項目の設定値を返します。$valueパラメーターを渡した場合、その値を$settingで指定した設定項目に設定し、configオブジェクトを更新します。

$mt->request([$element[,$data]])

リクエストを有効範囲として保存するオブジェクトを提供します。MT::Requestパッケージのアクセス・インスタンスです。パラメーターなしで呼び出すと、MT::Requestインスタンスを返します。$elementパラメーターを指定して呼び出した場合、その要素に保存されたデータ(あるいはその要素が存在しない場合にはundef)が返されます。$dataパラメーターを指定して呼び出した場合、該当するリクエスト・オブジェクト内の指定した要素に、渡された値を設定します。

リクエスト・オブジェクトに設定された値は、リクエストの終了とともにすべて解放されます。実行中のアプリケーションがWebベースのアプリケーションでない場合には、プロセスが終了するまでリクエスト・オブジェクトが存続し、プロセス終了とともに解放されます。詳細はMT::Requestを参照してください。

$mt->ping( %args )

自分のブログの更新を他のサイトに通知するために、設定されたすべてのXML-RPC pingを送信します。%argsには、次のものが指定可能です。

Blog

どのブログに関するpingを送信するのかを、MT::Blogオブジェクトで指定します。BlogかBlogIDのいずれか一つは指定しなければなりません。

BlogID

どのブログに関するpingを送信するのかを、ブログIDで指定します。BlogかBlogIDのいずれか一つは指定しなければなりません。

$mt->ping_and_save( %args )

指定されたエントリーについて、保留中のping処理の発行タスクを処理し、そのエントリーをデータベースに書き戻します。ハッシュ%argsは、Entryというインデックスで、MT::Entryオブジェクトへのリファレンスを要素として持っている必要があります。

$mt->set_language($tag)

$tagで指定された言語用のローカライゼーション・プラグインを読み込みます。言語タグは、Movable Typeが対応している有効な言語タグでなければなりません。Movable Typeが対応している言語の一覧を取得するには、supported_languagesを参照してください。ここで指定する言語は、グローバル・レベルで設定され、管理システムのすべてのテキストとエラー・メッセージの翻訳に反映されます。

このメソッドは、クラス・メソッドとしてもオブジェクト・メソッドとしても呼び出すことが可能です。

MT->set_language($tag)

という呼び出し方もできますが、どちらの場合にも設定はグローバルになります。つまり現在の$mtオブジェクトに限定されるものではありません。デフォルト値(MT::new呼び出し時に設定されるもの)は英語(米語)です。MTの環境設定ファイルでDefaultLanguageが設定されている場合には、その設定が使用されます。

MT->translate($str[, $param, ...])

$strで指定した文字列を、現在設定されている言語(set_languageで設定された言語)に変換し、変換後の文字列を返します。$strの右側のパラメーターはすべてアクティブなローカライゼーション・モジュールのmaketextメソッドに受け渡されます。

MT->translate_templatized($str)

<MT_TRANS>タグが埋め込まれた文字列を変換します。<MT_TRANS>タグは、文字列の中でローカライゼーションが必要な部分を示すものです。アプリケーションのテンプレート(HTML::Template型)では、次のように使います。

<p><MT_TRANS phrase="Hello, world"></p>
<p><MT_TRANS phrase="Hello, [_1]" params="<TMPL_VAR NAME=NAME>"></p>
$mt->trans_error( $str[, $arg1, $arg2] )

$strで指定した文字列を、現在設定されている言語(set_languageで設定された言語)に変換し、変換後の文字列を現在のMTインスタンスのアクティブなエラーとして設定します。戻り値はundefで、これはアプリケーション中でエラーが発生したときの通常の戻り値です。このため、エラーが発生したときの通常の戻り値は、次のように返されます。

if ($@) {
    return $app->trans_error("An error occurred: [_1]", $@);
}

オプション引数の$arg1(およびそれ以降の引数)は、パラメーターを持つすべてのエラー・メッセージに受け渡されます。

$mt->current_language

現在設定されている言語の言語タグを返します。

MT->supported_languages

言語タグから言語の正式名へのマッピングを行うハッシュへのリファレンスを返します。たとえば次のように使うことができます。

use MT;
my $langs = MT->supported_languages;
print map { $_ . " => " . $langs->{$_} . "¥n" } keys %$langs;
MT->language_handle

アクティブな言語に対するMT::L10Nインスタンスを返します。

MT->add_plugin($plugin)

プラグイン一覧に、$pluginで指定したプラグインを追加します。引数はMT::Pluginクラスのオブジェクトでなければなりません。

MT->add_plugin_action($where, $action_link, $link_text)

アクティブなMT::Appインスタンスのadd_plugin_actionメソッドへのエイリアスです。詳細は、MT::Appを参照してください。

MT->add_text_filter($key, ¥%options)

$keyで指定した識別子と%optionsで指定したオプションを持つテキスト・フィルターを追加します。テキスト・フィルターは、エントリーの投稿/編集画面に表示されるテキスト・フィルターの選択肢に追加され、ユーザーがテンプレート中で有効にしたすべてのエントリー入力フィールドに対して適用されます(たとえば、デフォルトでは、内容および追記フィールドにはフィルターが適用されますが、概要フィールドには適用されません。)。

$keyは、英数字と"_"のみで構成される(つまり正規表現の/¥w+/にマッチする)小文字の識別子でなければなりません。$keyは、エントリー別にフィルター名として保存されるので、変更してはいけません(つまり、フィルターの動作がバージョン間で同じならば、あるバージョンでfooという名前をつけ、次のバージョンでfoo_barという名前をつける、ということをしてはいけません。)。

逆に言うと、フィルターの動作がバージョン間で異なる場合には、$keyを変えなければならない、ということにもなります。同時にプラグインのファイル名も変更しなければなりません。こうすることで、古い実装(ユーザーのシステム上ですべてのエントリーに対して有効になっているかもしれません)が正常に動作するようになります。たとえば、fooという名前のプラグインが、<p>タグの代わりに<br />タグ2つで段落区切りを表すように大幅にセマンティックを変えたとすると、新しいバージョンを表すキーを、たとえばfoo_2のように変更し、ファイル名もfoo_2.plのように変更する必要があります。

%optionsには次の項目が指定可能です。

label

簡潔でわかりやすいフィルターのラベルを指定します。ここで設定したラベルが、Movable Type画面でテキスト・フィルターの名前として表示されます。

on_format

文字列をフィルターするサブルーチンへのリファレンスを指定します。ここで指定するサブルーチンは必ず、引数を1つ(フィルターの対象となる文字列)取り、フィルター適用後の文字列を返すものでなければなりません。場合によっては --- たとえばテンプレート構築時に呼び出す場合など --- このサブルーチンが2つめの引数を取ることがあります。テンプレート構築を処理するMT::Template::Contextオブジェクトです。

docs

フィルターの説明を記述したドキュメントのURL(またはファイル名)を指定します。エントリーの投稿/編集画面でフィルターを選択してヘルプへのリンク((?))をクリックしたときにポップアップ・ウィンドウに表示されるものです。完全なURL(http://で始まるもの)を指定した場合、そのURLでポップアップ・ウィンドウが開きます。それ以外の場合には、ユーザーのシステム上のdocsフォルダー中のファイル名と解釈されます。

次は、CPANモジュールのText::WikiFormatを使ってWikiフォーマット用のテキスト・フィルターを追加する例です。

MT->add_text_filter(wiki => {
    label => 'Wiki',
    on_format => sub {
        require Text::WikiFormat;
        Text::WikiFormat::format($_[0]);
    },
    docs => 'http://www.foo.com/mt/wiki.html',
});
MT->all_text_filters

テキスト・フィルターの登録情報を格納したハッシュへのリファレンスを返します。

MT->apply_text_filters($str, ¥@filters)

¥@filtersで指定したフィルターのセットを、$strで指定した文字列に適用し、結果(フィルター適用後の文字列)を返します。¥@filtersは、フィルターのキー名(add_text_filterメソッドの第1引数として渡した短縮名)の配列へのリファレンスでなければなりません。$strはフィルターの対象となるスカラー文字列でなければなりません。

¥@filters中のフィルターのいずれかが、登録されたフィルター(add_text_filterメソッドで追加されたフィルター)の中に存在しない場合、エラーを返すことなくそのフィルターが無視されます。フィルターは¥@filters内の順番にしたがって適用されます。

最終的には、MT::Entry::text_filtersメソッドが、そのエントリーに使用するテキスト・フィルターのリストへのリファレンスを返します。ですから、たとえば、このメソッドを使って$entryで指定されたエントリーのエントリー本文にフィルターを適用するコードは、次のとおりです。

my $out = MT->apply_text_filters($entry->text, $entry->text_filters);
MT->add_callback($meth, $priority, $plugin, $code)

登録済みの特定のコールバックに対して、コールバック・ハンドラーを登録します。第1引数にはコールバック・メソッドの名前を指定します。第2引数には、ハンドラーが実行される優先順位を1から10の範囲の数値で指定します。複数のハンドラーが同じ優先順位を持つ場合には、登録された順番に実行されます。第3引数(オプション)には、そのハンドラーと関連づけられたMT::Pluginオブジェクトへのリファレンスを指定します。第4引数には、コールバックの処理を行うために呼び出すコードへのリファレンスを指定します。

MT->add_callback('BuildFile', 1, undef, ¥&rebuild_file_hdlr);

ここで指定するコード・リファレンスは、MT::Errorhandler型のオブジェクトを第1引数として受け取るものでなければなりません。これは、呼び出し側にエラーを渡すために使用します。

sub rebuild_file_hdlr {
    my ($eh, ...) = @_;
    if (something bad happens) {
        return $eh->error("Something bad happened!");
    }
}

コールバックへのその他の引数は、コールバック・ポイントに依存します。エラー文字列の処理はコールバック・ポイントに依存します。通常は無視されるか、ユーザーの操作が失敗し、エラーメッセージが表示されます。

MT->run_callbacks($meth[, $arg1, $arg2, ...])

特定のコールバックを呼び出し、関連づけられたコールバック・ハンドラーを実行します。第1引数には、実行するコールバックの名前を指定します。グローバルなコールバック・メソッド(コールバックの項を参照)か、実行するコールバックと関連づけられたパッケージの名前を含むクラス固有のメソッドが指定できます。残りの引数は、呼び出されたコールバック・ハンドラーにそのまま受け渡されます。

フィルター型のコールバックの場合、指定されたハンドラーのいずれか1つでもfalseとなる値を返した場合には、このメソッドは0を返します。指定されたハンドラーがすべてtrueとなる値を返すと、1を返します。次の例を見てください。

MT->run_callbacks('MyClass::frobnitzes', ¥@whirlygigs);

これは、次のように登録されたすべてのハンドラーを実行します。

MT->add_callback('MyClass::frobnitzes', 4, $plugin, ¥&frobnitz_hdlr);
MT->register_junk_filter( $filter )

新しいMT::JunkFilterオブジェクトをMovable Typeに登録します。迷惑コメント/トラックバック・フィルターは、受信したコメント/トラックバックがスパムであるかどうかを判断するのに使用します。詳細はMT::JunkFilterを参照してください。

require MT::JunkFilter;
MT->register_junk_filter(new MT::JunkFilter({
    name => "My Junk Filter",
    code => sub { $plugin->my_junk_filter(@_) },
    plugin => $plugin,
}));
MT->version_id

MTのバージョン(ベータ版/アルファ版の表記も含む)を返します。

MT->version_number

MTのバージョン(ベータ版/アルファ版の表記も含まない)を返します。たとえばversion_idが"2.5b1"を返す場合、version_numberは"2.5"を返します。

$mt->schema_version

MTデータベース・スキーマのバージョンを返します。

$mt->publisher

MTの公開プロセスを管理するのに使われているMT::WeblogPublisherオブジェクトを返します。詳細はMT::WeblogPublisherを参照してください。

$mt->build_email($file, $param)

アプリケーションのemailテンプレート・ディレクトリからテンプレートを読み込み、HTML::Templateとして処理します。引数$paramは、対象となるテンプレートのパラメーター・データを含むハッシュへのリファレンスです。戻り値はテンプレートの出力になります。

エラー処理

MTクラスのメソッドは、すべてエラー発生時にundefを返します。エラー・メッセージは、該当するクラスまたはオブジェクト(呼び出したメソッドがクラス・メソッドかインスタンス・メソッドかによります)のerrstrメソッドを呼び出すことで取得できます。

たとえば、そのメソッドをクラス名から呼び出す場合には次のように記述します。

my $mt = MT->new or die MT->errstr;

あるいはオブジェクトから呼び出す場合には、次のように記述します。

$mt->rebuild(BlogID => $blog_id)
    or die $mt->errstr;

コールバック

Movable Typeには、プラグインがコールバックを追加できる多様なフック・ポイントがあります。

どの場合でも、第1引数はMT::ErrorHandlerオブジェクトで、コールバック側では、このオブジェクトを使って、呼び出し側にエラーを返すことができます。

再構築に関連するアプリケーション・レベルのコールバックは後述します。


Copyright © 2001-2006 Six Apart, Ltd. All Rights Reserved.