Home > Logs > August 2007 > This Entry
Callback.pod 訳してみた
sixapart のサイトにはもうすぐより詳細な情報提供をしてくれる旨書かれているのだけれど、いつになるかわからないし、予習しとくのも悪いことじゃないしなあと思って、Callback.pod ファイルをちょっと勉強がてら訳してみました。長いので今日は前半部分のみ。これでも3時間くらいがんばったんで勘弁してください…
クローン作成機能についての言及があるので、暇な人読んでみてください。役に立つことがあるかもしれません。以前にMovableType 4のクローン機能でエントリを複製させない方法という記事で、クローン機能の処理ではコールバックは無理そうだ…とか書いてしまったのですが、どうやらクローン機能でもコールバックを発生させられるようです(未確認!)。
コールバックを発生させられることを確認しました。関連エントリ「MovableType 4 クローン機能におけるコールバックに関する動作について」や、「ブログの複製(クローン機能)の時、複製したエントリを削除する ClonedBlogCleaner プラグイン」をご覧ください。
あと、これは僕の基準で理解しやすいように訳したし、英訳は10年ぶりくらいになるので、オウンリスクでお願いします。「***」のあたりのくだりはよくわからなかったり、言い回しが思いつかなかったりしたところです。「=」で始まる行は Callback.pod にもともと書いてあったものをそのままコピペしました。指摘などあればぜひ 3xstars@gmail.com まで送ってください。
ちなみに、Callback.pod ファイルは MovableType 4 なら「mt/lib/MT/」にあります。
=pod
=head1 NAME
Callback.pod - Movable Type Callbacks
=head1 DESCRIPTION
MovableType におけるコールバックシステムは簡単に使うことができ、
アプリケーション中のキーとなる箇所で発生させることができる。
このドキュメントはMovableType のすべてのコールバックのリファレンスだ。
このAPIドキュメントとも言うべきドキュメントは、
MovableType と MovableType Enterprise の両方に使える。
***まれな事象については、明確に注記されている。
=head1 OVERVIEW
例えば、書式として以下のようであるならば、:
callback($cb, $param1, $param2)
コールバックのサブルーチンは以下のように定義される必要がある:
sub my_callback {
my ($cb, $param1, $param2) = @_;
}
もし、書式が以下のようであれば、:
callback($cb, %info)
サブルーチンは以下のように記述する必要がある:
sub my_callback {
my ($cb, %info) = @_;
}
=head1 ERROR HANDLING
コールバック処理のために受け取る最初の引数は MT::Callback オブジェクトである。
これは MT にエラーを返させるために用いる。
エラーの発生を知らせるには、error() メソッドを使えばよい。
sub my_callback {
my ($cb, $arg2, $arg3) = @_;
....
if (some_condition) {
return $cb->error("The foofiddle was invalid.");
}
...
}
error() メソッドに加えて、MT::Callback パッケージは
そのコールバックを記述したプラグインに関するメタデータをもつ。
my $plugin = $cb->plugin;
***このメソッドは、そのコールバックがプラグインに記述されていなければ undef を返す。
=head1 Naming Conventions
MTのコールバックは以下のいずれかの形をとる:
=over 4
=item * CallbackName
これは高レベルコールバックだ。
特に TakeDown アプリケーションや、BuildFileFilter のようなプロセス重視のコールバックである。
=item * callback_name
***より低いケースのコールバックは、低レベルコールバックを意味する。
これらは pre_save や post_save などの MT::Object のコールバックで一般的である。
=item * Package::CallbackName
前置されたパッケージ名で呼び出されたコールバックは、
たくさんのクラスで呼び出されるコールバックとは明示的に区別される。
transformer コールバックがその例だ。
これらのコールバックは以下のワイルドカード部分に書かれた処理にフックすることができる。
MT->add_callback('*::CallbackName', ...)
もっと単純にすることもできる:
MT->add_callback('CallbackName', ...)
つまり、名前の部分によって、コールバックを特別なパッケージにすることもできるし、
それを記述せず、パッケージを無視したコールバック処理として記述することもできる。
=item * Package::CallbackName.type
=item * CallbackName.type
これは、引数や識別子とともにコールバック処理をするための書き方である。
様々なところでフックする場合に使われる。
CMS アプリケーションのコールバックには、この書式を使うものがある。:
MT->add_callback('CMSDeletePermissionFilter.entry', ...)
この書式を使えば、transformer コールバックにおいて、
特定のテンプレートをターゲットにすることができる:
MT->add_callback('AppTemplateSource.list_blog', ...)
スタフィックスをつけないこともできる:
MT->add_callback('AppTemplateSource', ...)
また、部分的なアプリケーションやオブジェクトを処理対象とすることも可能になる:
MT->add_callback('MT::App::CMS::AppTemplateSource.header', ...)
最後につけられた header は例ではあるが、CMS アプリケーションの、
ヘッダテンプレートアプリケーションであることを特定している。
=back
=head1 Object Callbacks
オブジェクトのコールバックは MT::Object とそのサブクラスに結びつく。
MT::Entry や MT::Blog がそれにあたる。
=over 4
=item * ::pre_save
callback($cb, $obj, $original)
コールバックは $obj をデータベースに保存する前に発生する。
$original は保存のために作られたインスタンスで、$obj に id がないのであれは、
それは新規オブジェクトである。
=item * ::post_save
callback($cb, $obj, $original)
コールバックは $obj をデータベースに保存した後で発生する。
$original は保存のためにつくられたインスタンスである(保存前の $obj)。
=item * ::pre_update
callback($cb, $obj, $original)
コールバックは現存の $obj をデータベースに保存する前に発生する。
$original は保存のためにつくられたインスタンスである。
=item * ::post_update
callback($cb, $obj, $original)
コールバックは現存の $obj をデータベースに保存した後に発生する。
$original は保存のためにつくられたインスタンスである。
=item * ::pre_insert
callback($cb, $obj, $original)
コールバックは新規の $obj をデータベースに保存する前に発生する。
$original は保存のためにつくられたインスタンスである。
=item * ::post_insert
callback($cb, $obj, $original)
コールバックは新規の $obj をデータベースに保存した後に発生する。
$original は保存のためにつくられたインスタンスである。
=item * ::pre_load
callback($cb, \@params)
@params は load メソッドに渡す引数を含む配列である。
=item * ::post_load
callback($cb, \@params, $obj)
@params は load メソッドに渡す引数を含む配列である。
引数 $obj はload メソッドで呼び出されたオブジェクトである。
=item * ::pre_remove
callback($cb, $obj)
=item * ::post_remove
callback($cb, $obj)
=item * ::pre_remove_all
callback($cb, $class)
=item * ::post_remove_all
callback($cb, $class)
=item * ::post_clone
callback($cb, %param)
このコールバックは MT::Blog に特有のものである。
処理はブログとその子オブジェクトの複製であるクローン作成をしたときに行われる。
プラグインがブログに関連するデータを持っていて、
なおかつそのブログが複製された時にそのデータを複製したいとき、
複製処理にフックさせてコールバックを発生させることができる。
ブログが複製されるに伴い、エントリ、カテゴリ、テンプレートなどの子レコードも複製される。
***これだけで、それらの新しいIDに加えて、
複製されたレコードのもともとのIDを知るのに重要になる。
すなわちこのコールバックは複製されたエントリ、カテゴリ、トラックバック、
それにテンプレートオブジェクトの情報をもたらす。
コールバックに渡された引数の情報は以下を含む:
=over 4
=item * OldObject
MT::Blog オブジェクトが複製された。
これは複製元のブログのオブジェクトであって、新しく作成された方ではない。
=item * NewObject
複製された方（新しい方）の MT::Blog オブジェクトである。
=item * EntryMap
複製元のエントリのIDである key と、
新しく作成されたエントリのIDである value を持つハッシュリファレンス。
=item * CategoryMap
複製元のカテゴリのIDである key と、
新しく作成されたカテゴリのIDである value を持つハッシュリファレンス。
=item * TrackbackMap
複製元のトラックバックのIDである key と、
新しく作成されたトラックバックのIDである value を持つハッシュリファレンス。
=item * Callback
クローン作成の進行時のメッセージなどに使われるコードリファレンス。
メッセージと一意な識別子とともに呼び出される。
***識別子をもつそれぞれの進捗がアップデートするに伴い、メッセージが表示される。
このコールバックを使う最もよい例である、MT::Blog::clone_with_children サブルーチンを参照せよ。
$callback->("Now cloning foozles...", "foozles");
=back
=back
=head1 Application Callbacks
=head2 MT::App
これらのコールバックは MT::App パッケージに由来するすべての MT アプリケーションに共通する。
=over 4
=item * ::pre_run
callback($cb, $app)
mode ハンドラが呼び出される前に、リクエストを発生させる（アプリケーションの mode を決定する前、すなわちここで他の mode に置き換えることができる）。
=item * ::post_run
callback($cb, $app)
mode ハンドラの処理が発生したあとでリクエストを呼び出す。
このコールバックはクライアントにレスポンスを返す前に発生する。
=item * TakeDown
callback($cb, $app)
アプリケーションがリクエストに対する処理を終える時に実行される。このとき、クライアントに処理結果はすでに送られている。
=back
上記のコールバックに加え、MT::App は、
それ自身のセクションである Transformer Callbacks で文書化されている、
"Transformer" コールバックのセットを提供する。
=head2 MT::AtomServer and MT::XMLRPCServer
=over 4
=item * APIPreSave.entry
callback($cb, $app, $entry, $original)
このコールバックはエントリー・オブジェクトを保存した後に発生する。
新規エントリが保存される場合、$original->id に値は入っていない。
=item * APIUploadFile
callback($cb, %params)
このコールバックはブログにファイルをアップロードする際に発生する。
MT::App::CMS に見られるCMSUploadFileと同様のコールバックだ。
現在、このコールバックは MT::AtomServer アプリケーションが
ファイルアップロードを扱えないときからの MT::XMLRPCServer でのみ使われている。
このコールバックのための引数は以下のように名付けられる:
=over 4
=item * File
アップロードファイルのフル物理パス。
=item * Url
アップロードされたファイルのフルURL。
=item * Type
このコールバックの場合、この値は常に 'file' である。
=item * Blog
新しいアップロードファイルに関連づけられた MT::Blog オブジェクト。
=back
=back
=head2 MT::App::CMS
以下のコールバックは MT::App::CMS に特有のものである。
多くは CMS のデータタイプとしての記述である スタフィックスを持つ。使えるのは以下:
=over 4
=item author => MT::Author
=item comment => MT::Comment
=item entry => MT::Entry
=item template => MT::Template
=item blog => MT::Blog
=item notification => MT::Notification
=item templatemap => MT::TemplateMap
=item category => MT::Category
=item banlist => MT::IPBanList
=item ping => MT::TBPing
=item ping_cat => MT::TBPing
=item group => MT::Group
=item role => MT::Role
=item association => MT::Association
=back
=over 4
=item * CMSViewPermissionFilter.
決まり文句は以下:
callback($cb, $app, $id, $obj_promise)
すでに存在しているならば、$id がそのオブジェクトのIDである。
そうでないならば、このオブジェクトを作成しようとしても undef が返ってくる。
$obj_promise はそのオブジェクト自身の約束事である。
$obj_promise->force を使って ahold を呼び出すことができますが、
あまり必要になることはないだろう（MT::Promise を参照）。
負の値が返った場合、処理を中止して、権限がない旨のメッセージを表示する。
=item * CMSSavePermissionFilter.
決まり文句は以下:
callback($cb, $app, $id)
すでに存在しているならば、$id がそのオブジェクトのIDである。
そうでないならば、このオブジェクトを作成しようとしても undef が返ってくる。
注意すべきなのは、オブジェクトが存在しない可能性があることだ。
リクエストは $app->param() で参照できる引数でアプリケーションに渡される。
CMSSavePermissionFilter コールバックは安全、
つまりデータベースを変更しないものである必要がある。
負の値が返った場合、処理を中止して、権限がない旨のメッセージを表示する。
ユーザーがスーパーユーザーの場合には、このメソッドの呼び出しは行われない。
=item * CMSDeletePermissionFilter.
callback($cb, $app, $object)
=item * CMSSaveFilter.
このコールバックにより、権限がないという以外の理由でリクエストを拒否することができる。
呼び出し方は以下:
callback($cb, $app)
負の値が返った場合、リクエストを拒否する。拒否の理由を伝えるため、
$cb を使ってエラーを返してやるのが望ましい。
注意すべきなのは、オブジェクトが存在しない可能性があることだ。
リクエストは $app->param() で参照できる引数でアプリケーションに渡される。
CMSSaveFilter コールバックは安全、つまりデータベースを変更しないものである必要がある。
Post Comment