MTAppListing

テキスト入力欄に「選択」ボタンを付け、クリックするとダイアログを開いて、Data API（や任意の URL）から取得した JSON を一覧表示し、項目を選んでフィールドに保存できる jQuery プラグインです。記事・ウェブページ・カテゴリなどを「一覧から選ぶ」UI を作るのに使います。選んだ項目の識別子（既定では id）をフィールドに保存し、MTAppShowListEntries と組み合わせると保存済み ID をタイトル一覧として表示できます。

構文

$(selector).MTAppListing(options);

$.fn プラグイン（$(selector).MTAppListing(...)）です。対象要素（this）を返すのでチェーンできます。

パラメータ

options {Object} — 以下のプロパティを持ちます（url と jsontable の必須項目以外は省略可）。

データ取得

ダイアログ表示

一覧テーブル（jsontable）

MTAppJSONTable に渡すオプションです。一覧の表示と選択挙動を決めます。

コールバック（いずれも省略可）

cbAfterOpenDialogFirst / cbProcessResponse / cbAjaxDoneFilterJSONTable / cbAjaxDone / cbAjaxFail / cbAfterCancel / cbAfterOK / cbAfterSearch / cbAfterSearchReset / cbAfterOpenDialogLast / cbAfterSelectRowUpperTable / cbAfterSelectRowLowerTable。各タイミングで呼ばれます。特に cbAjaxDoneFilterJSONTable は false を返すと一覧描画を抑止し「該当データなし」表示にします（Data API のとき return response.items && response.items.length > 0; のように使う）。

選択アイテム表示（selectedView）

selectedView にオブジェクトを渡すと、選択済みアイテムをフィールドの上にテーブル/リストで表示します（既定 null で無効）。表示は url の JSON をデータ源にします（ページ表示時にバックグラウンドで取得してキャッシュし、ダイアログ取得時の結果もマージして最新化）。Data API 専用ではなく、独自 JSON の URL でも動作します。選択を変更すると表示も更新されます。

列（見出し）は jsontable.header / jsontable.headerOrder を流用します。キャッシュに無い ID は ID のみで表示します（フォールバック）。テーブル表示はフィールドと同じ横幅に広がり、id 列は内容幅に抑えます。selectedView を有効にすると生のカンマ値フィールドは既定で非表示になります（debug: true で表示）。

戻り値

{jQuery} — 対象要素（チェーン可能）。

保存される値

選択した項目の listingTargetKey（既定 id）の値が保存されます。

• 単一選択: その値そのもの（例: 29）。
• 複数選択: 前後をカンマで囲んだカンマ区切り（例: ,29,30,31,）。
• listingTargetEscape: true の場合は各値を encodeURIComponent した文字列になります。

保存されるのは「識別子」だけです。タイトルなど人間可読な表示は、selectedView オプション（本体機能）でフィールド上に表示できます（別メソッド MTAppShowListEntries でも可）。

使用例

// 記事を一覧から選んで id を保存（Data API。アクセストークンは別途取得して付与）
$('#customfield_related').MTAppListing({
    url: '/cms/mt/mt-data-api.cgi/v3/sites/1/entries?fields=id,title&limit=20&status=Publish',
    accessToken: token, // mtappVars.DataAPI から取得したトークン等
    dialogTitle: '記事を選択',
    jsontable: {
        header: { id: 'ID', title: 'タイトル' },
        headerOrder: ['id', 'title'],
        itemsRootKey: 'items',
        listingTargetKey: 'id',
        listingCheckboxType: 'checkbox',
        listingTargetEscape: false
    }
});

// 選択済み記事をフィールドの上にテーブル表示（編集リンク付き）
$('#customfield_related').MTAppListing({
    url: '/cms/mt/mt-data-api.cgi/v3/sites/1/entries?fields=id,title&limit=100&status=Publish',
    accessToken: token,
    jsontable: {
        header: { id: 'ID', title: 'タイトル' },
        headerOrder: ['id', 'title'],
        itemsRootKey: 'items', listingTargetKey: 'id', listingCheckboxType: 'checkbox', listingTargetEscape: false
    },
    selectedView: { format: 'table', editLink: true, model: 'entry', siteId: 1 }
});

user.js での記述例

user.js（「デザイン → user.js を編集」）に書く場合は、mtappVars.screen_id で画面を判定して呼び出します。

(function ($) {
    if (typeof mtappVars !== 'object') return;
    if (mtappVars.screen_id === 'edit-entry') {
        $('#customfield_related').MTAppListing({
            url: '/cms/mt/mt-data-api.cgi/v3/sites/1/entries?fields=id,title&limit=20&status=Publish',
            accessToken: token, // mtappVars.DataAPI から取得したトークン等
            dialogTitle: '記事を選択',
            jsontable: {
                header: { id: 'ID', title: 'タイトル' },
                headerOrder: ['id', 'title'],
                itemsRootKey: 'items',
                listingTargetKey: 'id',
                listingCheckboxType: 'checkbox',
                listingTargetEscape: false
            }
        });
    }
})(jQuery);

生成される HTML

フィールドの直後に「選択」ボタン（<a class="button">）が挿入されます。ダイアログ（#mtapplisting-dialog）はページに1つだけ生成され、開くたびに内容が再構築されます。

<input type="text" id="customfield_related">
<a href="#" class="button">選択</a>
<!-- クリックで #mtapplisting-dialog（検索欄＋選択済みテーブル＋一覧テーブル＋OK/キャンセル）を表示 -->

補足

• データ取得は標準の $.ajax です。Data API を使う場合、下書きを含めて取得するにはアクセストークンが必要です。本プラグインは「DataAPI SDK を利用」が有効なとき現在ログイン中のユーザーで mtappVars.DataAPI を認証済みにするので、そこからトークンを取得して accessToken に渡せます（公開記事のみなら省略可）。
• ダイアログの検索は、入力文字列を行の表示テキストに対する大文字小文字を区別しない部分一致で絞り込みます（( や [ などの記号を入力しても安全です）。Enter キーでも検索でき、日本語入力（IME）の変換確定 Enter では検索しません。
• ダイアログ内は2段構成です。下段が取得した全項目、上段が選択済み項目で、上段はドラッグで並べ替えできます。listingCheckboxType: 'radio' のときは単一選択になります。
• 選択アイテムの表示は selectedView オプション（本体機能）で行えます。データ源は url の JSON をページ表示時にプリフェッチしてキャッシュし、ダイアログ取得時の結果もマージして最新化します。そのため Data API 専用ではなく、独自 JSON の URL を指定した場合は Data API が不要です。同等の機能を持つ別メソッド MTAppShowListEntries も引き続き利用できます（同じフィールドに両方は併用しないでください）。
• 「選択」ボタンのラベルは l10n.select で変更できます。
• レイアウト: 「選択」ボタンはフィールドとの間に少し余白を取ります（フィールドが非表示のときは余白を取らず詰めて表示します）。選択ダイアログの ID 列は幅を抑え、タイトル等の列に幅を譲ります。

関連

• MTAppShowListEntries — 保存された記事／ページ ID を Data API でタイトル一覧として表示する（本メソッドと対で使う）。
• MTAppJSONTable — 一覧テーブルの描画に内部で使用。
• MTAppAssetFields — アセット（画像・ファイル）を選択ダイアログで選ぶ。