Callback.pod 訳してみた

August 31, 2007 5:51 AM

sixapart のサイトにはもうすぐより詳細な情報提供をしてくれる旨書かれているのだけれど、いつになるかわからないし、予習しとくのも悪いことじゃないしなあと思って、Callback.pod ファイルをちょっと勉強がてら訳してみました。長いので今日は前半部分のみ。これでも3時間くらいがんばったんで勘弁してください...

クローン作成機能についての言及があるので、暇な人読んでみてください。役に立つことがあるかもしれません。以前にMovable Type 4のクローン機能でエントリを複製させない方法という記事で、クローン機能の処理ではコールバックは無理そうだ...とか書いてしまったのですが、どうやらクローン機能でもコールバックを発生させられるようです(未確認!)。

コールバックを発生させられることを確認しました。関連エントリ「Movable Type 4 クローン機能におけるコールバックに関する動作について」や、「ブログの複製(クローン機能)の時、複製したエントリを削除する ClonedBlogCleaner プラグイン」をご覧ください。

あと、これは僕の基準で理解しやすいように訳したし、英訳は10年ぶりくらいになるので、オウンリスクでお願いします。「***」のあたりのくだりはよくわからなかったり、言い回しが思いつかなかったりしたところです。「=」で始まる行は Callback.pod にもともと書いてあったものをそのままコピペしました。指摘などあればぜひ weeeblog@gmail.com まで送ってください。

ちなみに、Callback.pod ファイルは Movable Type 4 なら「mt/lib/MT/」にあります。

=pod

=head1 NAME

Callback.pod - Movable Type Callbacks

=head1 DESCRIPTION

Movable Type におけるコールバックシステムは簡単に使うことができ、
アプリケーション中のキーとなる箇所で発生させることができる。
このドキュメントはMovable Type のすべてのコールバックのリファレンスだ。

このAPIドキュメントとも言うべきドキュメントは、
Movable Type と Movable Type 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 コールバックは安全、つまりデータベースを変更しないものである必要がある。

Comments

ちなみに、Callback.pod ファイルは Movable Type 4 なら「mt/lib/MT/」にあります。

=pod

=head1 NAME

Callback.pod - Movable Type Callbacks

=head1 DESCRIPTION

Movable Type におけるコールバックシステムは簡単に使うことができ、
アプリケーション中のキーとなる箇所で発生させることができる。
このドキュメントはMovable Type のすべてのコールバックのリファレンスだ。

このAPIドキュメントとも言うべきドキュメントは、
Movable Type と Movable Type 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 コールバックは安全、つまりデータベースを変更しないものである必要がある。

BLOG

Callback.pod 訳してみた

Comments