MTAppjQuery P7

MTAppMultiCheckbox

テキスト入力欄をチェックボックス群に置き換え、チェックした値を区切り文字で連結して保存する。標準のタグ欄に適用すると、決めた語彙をクリックで入力でき、表記ゆれを防げる。

テキスト入力欄をチェックボックス群に置き換え、チェックした値を区切り文字で連結して元の欄へ保存するメソッドです。

おすすめの使い方は、PowerCMS 標準の「タグ」欄に適用することです。 あらかじめ決めた語彙をクリックで入力できるようになるため、「お知らせ」「おしらせ」「オシラセ」のような表記ゆれが起こらず、タグを使ったサイト構築が安定します。タグ欄に適用したときは、区切り文字にユーザー設定の値を、選択肢の既定値にそのスペースの既存タグを自動で使います。

構文

$.MTAppMultiCheckbox(options);

パラメータ

options {Object} — 省略可。以下のプロパティを持ちます。

プロパティ	型	既定値	説明
`basename`	string	`''`	対象フィールドのベースネーム（必須）。タグ欄なら `'tags'`
`custom`	boolean	`false`	`true` でカスタムフィールド（`#customfield_<basename>`）を対象にする
`label`	string \| Array \| Object	`''`	選択肢。カンマ区切り文字列／配列／`{値: ラベル}` の連想配列。省略時は対象欄の `title` 属性、タグ欄なら既存タグ一覧
`sort`	string	`''`	並び順。`'ascend'`（昇順）／`'descend'`（降順）／`''`（指定した順）
`skin`	string	`''`	`'tags'` でタグ風のデザインを適用
`insert`	string	`'before'`	チェックボックス群の挿入位置。`'before'`（既定）／`'after'`。それ以外の値は `'before'` として扱う
`add`	boolean	`false`	`true` で選択肢を追加できる入力欄を表示
`maxCount`	number	`999999999`	チェックできる最大数（実質無制限）。正の数以外を渡した場合は既定値として扱います
`maxCountMessage`	string	`''`	上限を超えたときの警告文。空なら既定文言。`l10n.maxCountMessage` より優先されます
`delimiter`	string	`''`	値の区切り文字（1文字）。既定はカンマ。2文字以上を指定した場合は先頭1文字だけを使います。タグ欄では PowerCMS のユーザー設定が優先され、この指定は無視されます
`l10n`	Object	`null`	表示文言の上書き。キーは `maxCountMessage` / `addItemLabel` / `addItemPlaceholder` / `delimiterInValue`
`debug`	boolean	`false`	`true` で元の入力欄を隠さずに残す

戻り値

{jQuery} — 対象フィールドのラッパー（#<フィールドID>-field）。

保存される値

チェックした値を区切り文字で連結した文字列が、元の入力欄に保存されます。

区切り文字は、タグ欄ならユーザー設定（PowerCMS の「タグの区切り文字」）、それ以外はカンマです。delimiter で明示指定もできます（タグ欄を除く）。タグ欄でカンマ区切りの場合は、PowerCMS 本体と同じく , （カンマ＋スペース）で連結します。
タグ欄では、値そのものに区切り文字が含まれる場合、保存時に自動で引用符（" または '）で囲みます。 これは PowerCMS がタグを解釈するときの規約に合わせたもので、区切り文字がスペースの設定でも「イベント案内」のような値が2つのタグに割れません。
カスタムフィールドでは引用符を解釈しません（P5 と同じ挙動）。"社長の一言" 特集 のような値もそのまま保持されます。引用符の規約は PowerCMS のタグ欄にしか無いため、カスタムフィールドに適用すると保存済みの文字列が切り詰められてしまうためです。
その代わり、カスタムフィールドでは区切り文字そのものを含む値は選択肢にできません（保存後に別々の値へ分裂してしまうため）。label に指定した場合はその項目を読み飛ばし、add で入力された場合は欄の下に理由を表示します。
選択肢に無い値が既に保存されていた場合は、sort の指定に関わらずチェック済みの選択肢として末尾に追加します。 別の画面で付けられたタグなどが、チェック操作をした瞬間に消えることはありません。

使用例

タグ欄を決まった語彙のチェックボックスにする（推奨）

$.MTAppMultiCheckbox({
    basename: 'tags',
    label: 'お知らせ,イベント,採用情報,プレスリリース',
    skin: 'tags'
});

user.js での記述例

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

(function ($) {
    if (typeof mtappVars !== 'object') return;
    if (mtappVars.screen_id === 'edit-entry') {
        $.MTAppMultiCheckbox({
            basename: 'tags',
            label: 'お知らせ,イベント,採用情報,プレスリリース',
            skin: 'tags'
        });
    }
})(jQuery);

スペースの既存タグをそのまま選択肢にする

label を省略すると、タグ欄ではそのスペースに登録済みのタグが選択肢になります。

$.MTAppMultiCheckbox({ basename: 'tags', skin: 'tags', sort: 'ascend' });

保存する値と表示ラベルを分ける

$.MTAppMultiCheckbox({
    basename: 'tags',
    label: { 'news': 'お知らせ', 'event': 'イベント', 'recruit': '採用情報' },
    skin: 'tags'
});

カスタムフィールドに適用し、選択数を制限する

$.MTAppMultiCheckbox({
    basename: 'genre',
    custom: true,
    label: '和食,洋食,中華,エスニック',
    maxCount: 2,
    maxCountMessage: 'ジャンルは2つまで選択できます。'
});

編集者が選択肢を追加できるようにする

$.MTAppMultiCheckbox({
    basename: 'tags',
    label: 'お知らせ,イベント',
    skin: 'tags',
    add: true
});

追加用の入力欄に語句を入力して Enter を押すと、その語句がチェック済みの選択肢として追加されます。

生成される HTML

対象欄の直前（insert: 'after' なら直後）にチェックボックス群のコンテナが挿入され、元の入力欄は非表示になります。

<span class="mcb-container mcb-skin-tags" role="group" aria-labelledby="tags-label">
    <label class="mcb-label mcb-label-checked">
        <input class="mcb-checkbox" type="checkbox" value="お知らせ">お知らせ
    </label>
    <label class="mcb-label">
        <input class="mcb-checkbox" type="checkbox" value="イベント">イベント
    </label>
    <!-- add: true のときのみ -->
    <input class="mcb-add-item" type="text" aria-label="選択肢を追加（Enter で確定）" placeholder="追加して Enter">
</span>
<!-- 上限超過などを知らせる欄。文言が入ったときだけ表示される -->
<span class="mcb-status" role="status" aria-live="polite"></span>
<input type="text" name="tags" id="tags" style="display: none;">

skin: 'tags' を指定すると mcb-skin-tags が付き、チェックボックスの箱を隠したタグ風のピル型 UI になります（キーボードでのフォーカス・Space での選択は可能なままです）。デザインは user.css で上書きできます。

元の入力欄を隠すとフィールドのラベルが支援技術に伝わらなくなるため、コンテナに role="group" と aria-labelledby を付けて、PowerCMS が出力するラベル（#<フィールドID>-label）を参照しています。

補足

タグ欄に適用するときは label を明示することをおすすめします。 省略するとそのスペースに登録済みのタグが全件並ぶため、タグ数が多い環境では選択肢が大量になり、「決まった語彙だけを使わせて表記ゆれを防ぐ」という目的とも噛み合いません。
値の変更時に、元の入力欄に対して change イベントを発火します。これにより、タグ欄の内部キャッシュ（#tags-cache）の同期と、PowerCMS の「未保存の変更があります」警告が正しく働きます。読み込み直後（初期表示）は発火しないため、開いただけで未保存状態になることはありません。
同じフィールドに複数回呼び出した場合は、前回のチェックボックス群を作り直します（重複して挿入されることはありません）。
選択数が上限に達した状態でさらにチェックすると、そのチェックは元に戻り、欄の下に警告が表示されます（P5 では alert() でしたが、編集の手を止めないようインライン表示に変更しました）。上限を超えている状態からチェックを外す操作は常に受け付けます（他の画面で付けられたタグなどで上限を超えている場合に、選択を減らせなくなるのを避けるためです）。
label の文字列はカンマ区切りで指定します。区切り文字の設定（delimiter やタグ欄のユーザー設定）とは無関係です。値そのものにカンマを含めたい場合は、配列か連想配列で指定してください。
連想配列で指定した場合、並べ替え（sort）は表示ラベルではなく保存される値（キー）を基準に行います。
label を省略した場合、タグ欄以外では対象欄の title 属性を選択肢として読み取ります。
選択肢が1つも作れない場合（label も title 属性も既存タグも無い）は、元の入力欄を隠さずそのまま残します。チェックボックスも入力欄も無い状態になって、値を入力する手段が失われるのを避けるためです（add: true のときは追加用の入力欄があるため、通常どおり元の欄を隠します）。
P5 にあった $(selector).multicheckbox()（内部の jQuery プラグイン）は提供していません。$.MTAppMultiCheckbox() を使ってください。

構文