Skip to content

Ja dev listing framework overview

Jump to bottom
aklaswad edited this page May 9, 2011 · 14 revisions

リスティングフレームワーク

特徴

リスティングフレームワークは、 MT::Object を継承したオブジェクトに対して、フィルタリングやソートなどの機能を含む、共通のリスト画面を提供します。プラグイン作成者は、レジストリに各種設定を追加することで、独自のオブジェクトのリスト画面を作成し、振る舞いを設定することが出来ます。
また、既存のコアオブジェクトの一覧画面に対しても、カラムやフィルタの追加をレジストリ経由で行うことが出来ます。

既存のリスト画面との互換性

新しいリスティングフレームワークでは、テンプレートタグ mtapp:listing は使用していません。 mtapp:listing タグは後方互換性のため引き続きサポートされますが、リスティングフレームワークの各種機能を利用することは出来ません。
既存の list_actions や、フィルタ設定を含むリスト画面へのリンク1は可能な限り動作するようになっています。

リスト画面の起動

リスティングフレームワークは、 mt.cgi?__mode=list&_type=foo というリクエストに対し、対応するメソッド applications/cms/methods/list_foo が存在しない場合、 レジストリの listing_screens/foo および list_properties/foo から情報を収集して、自動的にリスト画面を生成します。

フィルタを指定してリスト画面を開く

クエリパラメータ filter_key を使って、ビルトインフィルタを指定することで、直接フィルタが適用された状態のリスト画面を開く事が出来ます。

http://example.com/mt.cgi?__mode=list&_type=entry&blog_id=0&filter_key=published

また、一部のフィルタアイテムについては、クエリパラメータ filter と filter_val を使って、フィルタ条件を指定する事も出来ます。

http://example.com/mt.cgi?__mode=list&_type=entry&blog_id=0&filter=status&filter_val=2

リスト画面の構造

リスティングフレームワークが作成するリスト画面では、XMLHttpRequestを利用してリストの内容を動的に取得します。以下、リスト画面全体のHTMLページを「リスト画面」と呼びます。また、リスト画面がXHRでリクエストするオブジェクトの内容を「リストの内容」または「フィルタされたリスト」と呼びます。コールバックを作成し、カスタマイズを行う場合には、カスタマイズを行う対象が「リスト画面」なのか「リストの内容」なのかを把握し、適切なコールバックを選択する必要があります。

リスト画面は、JavaScriptコードや、現在ユーザーが利用可能なフィルタの一覧、オブジェクトに対して実行可能なアクションの一覧などを含むHTMLページです。リスト画面のロードが完了した時や、ユーザーがリスト画面でフィルタの設定を変更した時に、リスト画面はMTに対して、XHRでリストの内容を要求します。要求には、フィルタの種類や、件数の上限、表示したいカラムの一覧などが含まれます。MTは、要求に応じてデータベースからオブジェクトのロードを行い、適切なHTMLスニペットに変換し、JSON形式でリストの内容を返します。リスト画面は受け取ったJSONデータを展開し、テーブルにレンダリングします。

Registry

以下のレジストリキーに値を追加していくことで、リストを作成/カスタマイズ出来ます。

listing_screens
リスト画面の全体の振る舞いを設定します
list_properties
リストにカラムやフィルタを追加します
system_filters
リストに、すぐに利用可能なビルトインフィルタを追加します
list_actions
リストに、オブジェクト単位で適用可能なアクションを追加します
content_actions
リストに、画面全体に適用するアクションを追加します

これらのレジストリキーの下に、任意のリストIDを指定し、リストの定義を行います。通常は表示するオブジェクトのobject_typeと同じものを指定します。

listing_screens:
    foo:
        # オブジェクトfooを表示するリストfooを定義し、基本的な振る舞いを指定
list_properties:
    foo:
        fizz:
            # リストfooにプロパティfizzを追加
list_actions:
    foo:
        buzz:
            # リストfooにアクションbuzzを追加

レジストリに設定可能な値については、以下のページを参照してください。

Callbacks

list_template_param.object

リスト画面が作成された際に、テンプレートのビルドの直前に呼び出されます。通常のテンプレートでの template_param コールバックに相当します。

Synopsis

sub list_template_param_foo {
    my $cb = shift;
    my ( $app, $param, $tmpl ) = @_;
    # Do something
}

Attributes

$app
MT::App クラスのインスタンスです
$param
テンプレートの構築時に渡されるパラメータを含むハッシュリファレンスです
$tmpl
構築に使用される MT::Template オブジェクトです

Return Value

このコールバックは戻り値を要求しません。

cms_pre_load_filtered_list.object

リストが要求された際、オブジェクトのロードの直前に呼び出されます。

Synopsis

sub cms_pre_load_filtered_list_foo {
    my $cb = shift;
    my ( $app, $filter, $options, $cols ) = @_;
    # Do something
}

Attributes

$app
MT::App クラスのインスタンスです
$filter
MT::Filter クラスのインスタンスです
$options
実行中のフィルタの $terms などを含むハッシュリファレンスです
$cols
現在要求されているカラムの一覧を含む配列リファレンスです

Return Value

このコールバックは戻り値を要求しません。

cms_filtered_list_param.object

リストが要求された際、作成されたリストが出力される直前に呼び出されます。

Synopsis

sub cms_filtered_list_param_foo {
    my $cb = shift;
    my ( $app, $res, $objs ) = @_;
    # Do something
}

Attributes

$app
MT::App クラスのインスタンスです
$res
リクエストにマッチしたオブジェクトを、画面表示用に加工された配列リファレンスです
$objs
リクエストにマッチしたオブジェクトの配列リファレンスです

Return Value

このコールバックは戻り値を要求しません。

More Customizing

list_common.tmpl

テンプレートのサーチパスに listing/foo_list_header.tmpl が存在する場合、自動的にインクルードされます。インクルードされたテンプレートからMTMLの変数にアクセスすることで、様々なカスタマイズやJavascriptコードの追加などが行えます。

<mt:setvarblock name="jq_js_include" append="1"> 
    // Some JavaScript 
</mt:setvarblock>

JavaScript and jQuery API in Common Listing Screen

Events

listReady

XHRを利用したリストの内容の読み込みが完了したタイミングでイベント listReady が発生します。

jQuery(window).bind('listReady', function() {
    // Do something after the List table was rendered.
})

Foot Notes

1 以前のバージョンで使われていた http://example.com/mt.cgi?__mode=list&_type=entry&filter=status&filter_val=2 のような形式のリンク

Clone this wiki locally