1933.html

Movable Type/第１６回MTプラグイン勉強会 - MT-Template-Context、stashとコンテナ・タグの作成

動画（Ustream）
コンテナ・タグの作り方
次回予定

第１６回はMT::Template::Contextクラスのリファレンスを読み、stashの扱い方と、コンテナ・タグの作成方法について取り上げます。

MT::Template::Context

動画（Ustream） †

勉強会の模様をアップしました。

Ustreamのチャンネルはこちら。
http://www.ustream.tv/channel/mt%E3%83%97%E3%83%A9%E3%82%B0%E3%82%A4%E3%83%B3%E5%8B%89%E5%BC%B7%E4%BC%9A

↑

[edit]

コンテナ・タグの作り方 †

↑

[edit]

コンテナ・タグとは？ †

Movable Type オブジェクト・リファレンス - MT::Template::Contextより。

コンテナ・タグは一般的にループを実現するために用います。

つまり、<MTEntries>のように、その内側に文字列、HTMLタグやMTテンプレートタグを含むことができるブロックを表現し、さらにループも実現できるものです。例えば<MTEntries>では

<MTEntries>
 タイトルは<$MTEntryTitle$>です。
</MTEntries>

でエントリーを繰り返し（ループし）、そのタイトルを表示します。

↑

[edit]

stashとは？ †

   このメソッドは、プラグイン中で、異なるタグの呼び出しの間でやり取りするデータを格納するシンプルなスタッシュの読み書きを行います。たとえば、上述の<MTLoop>タグの実装例に示したように、コンテナ・タグを実装する際に有用です。

   $keyはスタッシュを識別するためのスカラー文字列でなければなりません。$valueを指定する場合、任意のスカラー値（文字列、数値、リファレンス、オブジェクトなど）が指定可能です。

   $keyのみを指定してこのメソッドを呼び出すと、$keyというキーでスタッシュに格納されている値が返されます。$keyと$valueの両方を指定した場合、$keyのスタッシュの値を$valueに設定します。

MT::Template::Contextオブジェクトが提供するstashメソッドはテンプレート処理時の任意のステータスを保持します。これはテンプレート処理中の定数、変数、オブジェクトの保存領域として利用することができます。

# MT::Hogeオブジェクトを作成して、stashのMyPlugin::Hogeで保存しておく。
my $hoge = new MT::Hoge;
$ctx->stash('MyPlugin::Hoge', $hoge);

...

# その後どこかで（別のメソッド内ででも）stashから保存しておいたMT::Hogeオブジェクトを取得する
sub some_method {
  :
  my $hoge = $ctx->stash('MyPlugin::Hoge');
}

このように、プラグイン内部で独自にstashに保存する場合は、key名にはプラグイン名をプレフィックスとしてつけて（MyPlugin::）他のプラグインとバッティングしないようにします。

また、処理中のエントリーなど、既定の<type>のオブジェクト（<type>はentry、categoryなど、MT::*（MT::Objectのサブクラス）を特定する識別子）を取得することもできます。

# 現在処理対象のMT::Entryオブジェクトを得る。エントリーに対して処理していなければ（＝stashの返り値がnullなら）return
$ctx->stash('entry') or return;

このように、実際に指定した<type>のオブジェクトがロードできるかどうかはstashメソッドを呼んで、その返り値で判断する必要があります。つまり、stashメソッド利用者がコンテキストを意識して使う必要があります。

なお、コンテナ・タグのハンドラメソッド内では$ctx->stash('tokens')、$cts->stash('builder')は存在が保障されています。

Movable Type オブジェクト・リファレンス - MT::Template::Contextより

コンテナ・タグは一般的にループを実現するために用います。このため、サブルーチン内では、何らかの要素リストに関してループさせるループ構造を用意し、コンテナ・タグの内側で、各要素に対する表示を行うようなテンプレートタグを用意することになります。こうした内側のテンプレートタグは、トークン・リストとしてコンパイルされているため、MT::Builderオブジェクトを用いるだけで、このトークン・リストをスカラー文字列に変換し、出力に追加することができます。トークンのリストは$ctx->stash('tokens')に格納され、MT::Builderオブジェクトは$ctx->stash('builder')に格納されています。

↑

[edit]

サンプル、解説 †

コンテナ・タグの登録は

MT::Template::Context->add_container_tag($name, \&subroutine)

で行う。

Movable Type オブジェクト・リファレンス - MT::Template::Contextより

$nameにはタグ名（MTプレフィクスを除いたもの）を指定し、\&subroutineには無名または名前つきサブルーチンへのリファレンスを指定します。

です。

以下に、<MTMyLoop>のコンテナ・タグを定義し、またその中で<MTMyCount>で何回目のループかを表示するサンプルを記述します。

テンプレートサンプル

<MTMyLoop count="10">
   ループ、<$MTMyCount$>回目の実行
</MTMyLoop>

プラグインコード、サンプル

MT::Template::Context->add_container_tag('MyLoop', \&_my_loop);
MT::Template::Context->add_tag('MyCount', \&_my_count);

sub _my_loop {
    # ハンドラには二つの引数が渡される。
    # $ctxはテンプレート生成時に用いたMT::Template::Contextオブジェクト
    # $argsはテンプレート中のタグから渡される引数を格納するハッシュ配列へのリファレンス
    my $ctx = shift;
    my $args = shift;

    # ループ回数を取得
    my $count = $args->{count} || 1;

    my $res = '';

    my $builder = $ctx->stash('builder');
    my $tokens = $ctx->stash('tokens');

    for (my $i=1; $i<=$count; $i++) {
        $ctx->stash('MyLoop::index', $i);
        defined(my $out = $builder->build($ctx, $tokens))
        or return $ctx->error($builder->errstr);
        $res .= $out;
    }
    return $res;
}

sub _my_count {
    my $ctx = shift;
    $ctx->stash('MyLoop::index');
}

$builder->buildメソッドが失敗して、出力の構築ができなかった時は$builder->errstrで得られるエラーメッセージを$ctx->errorで返します。

Movable Type オブジェクト・リファレンス - MT::Template::Contextより

プラグイン内のサブルーチンハンドラでエラーが生じた場合、次のように*$ctx*オブジェクトの*error*メソッドを呼び出してエラーを返す必要があります。

 return $ctx->error("the error message");

特に、特定のコンテキスト内で呼び出すことを前提とするタグについては、このメソッドを用いることがよくあります。たとえば<$MTEntry*$>タグはすべて、コンテキスト中にエントリが存在することを前提としています。

 my $entry = $ctx->stash('entry')
   or return $ctx->error("Tag called without an entry in context");

と記述することにより、エントリが存在しないコンテキストでの呼び出し時にエラーを返すようになっています。

↑

[edit]