テーマでパターン・独自の型・表示する場所を足す


この機能は Ver. 3.3.0 で追加予定の、リリース前の機能です

このページは、アルファ版(Ver. 3.3.0-alpha.1)時点の内容です。正式版までに仕様や設定項目が変わる可能性があります。本番サイトでは使わず、検証環境でお試しください。

足すもの

置き場所

フィールドパターン

themes/<テーマ>/admin/field-definitions/patterns/<名前>.json

独自のフィールド型

themes/<テーマ>/admin/field-types/<ディレクトリ>/field-type.json と入力欄のテンプレート

表示する場所

themes/<テーマ>/admin/field-definitions/placements.json と、編集画面のテンプレートの差し込み口

フィールドパターン

パターンは、よく使うフィールドの組です。型を選ぶ画面の「パターン」に並び、開いているフィールドセットの末尾にコピーして使います。

{
  "version": 1,
  "name": "住所",
  "description": "郵便番号・都道府県・住所の入力欄",
  "entityTypes": ["entry", "category"],
  "categories": ["address"],
  "wrapper": { "type": "accordion", "key": "cf_address_box", "label": "住所" },
  "fields": [
    { "key": "cf_address_row", "label": "郵便番号と都道府県", "type": "row" },
    { "key": "cf_zip", "label": "郵便番号", "type": "text", "parentKey": "cf_address_row",
      "validation": { "required": "none", "rules": [ { "method": "regex", "arg": "^[0-9]{3}-?[0-9]{4}$" } ] } },
    { "key": "cf_pref", "label": "都道府県", "type": "text", "parentKey": "cf_address_row" },
    { "key": "cf_address", "label": "住所", "type": "textarea", "config": { "rows": 2 } }
  ]
}

キー

必須

型

既定値

内容

version

必須

数値

—

1

fields

必須

配列

—

フィールドの配列。書き方はフィールド定義と同じです(テーマでフィールド定義を宣言する)。

name

文字列

ファイル名

「パターン」に出す名前。

description

文字列

空

説明。

entityTypes

配列

すべての対象

使える対象。

categories

配列

なし

分類。

wrapper

オブジェクト

なし

「まとめ方」でアコーディオン・見出しを選んだときの箱。type(accordion か heading)・key・label。

  • ファイル名は、英小文字・数字で始まり、英小文字・数字・ハイフン・アンダースコアの 64 文字以内にします。

  • 並びは、テーマのパターン、プラグインのパターン、標準のパターン(「SEO」「SEO・OGP 画像」)の順です。

  • 追加するとき、同じキーの定義がすでにあるフィールドは追加しません。箱・見出しのキーが重なるときは、末尾に _2 などを付けて追加します。

  • 追加後はパターンとのつながりは残りません。パターンのファイルを変えても、追加済みのフィールドは変わりません。

  • 中身の誤りは、パターンを追加するときにエラーになります。

独自のフィールド型

PHP を書かずに、テーマに宣言ファイルと入力欄のテンプレートを置いて型を足せます。例として、色を選ぶ型を作ります。

themes/<テーマ>/admin/field-types/color/
├── field-type.json
└── input.twig
{
  "key": "mytheme.color",
  "label": "色",
  "icon": "palette",
  "template": "input.twig",
  "configFields": [
    { "key": "palette", "label": "候補(カンマ区切り)", "type": "text", "default": "#000000,#ffffff" }
  ],
  "validators": ["regex"]
}

キー

必須

型

既定値

内容

template

必須

文字列

—

同じディレクトリにある入力欄のテンプレートのファイル名。.twig なら Twig、それ以外は標準のテンプレートとして描きます。

key

文字列

ディレクトリ名

型のキー(64 文字以内)。vendor.name の形にすると、ほかの型とぶつかりにくくなります。コアの型のキーは使えません。

label

文字列

キー

型を選ぶ画面の名前。

icon

文字列

空

アイコン名。

configFields

配列

なし

型ごとの設定の欄。各項目は key(必須)・label・type(text・textarea・select・checkbox・number など。ほかはテキスト)・description・default。

validators

配列

なし

入力チェックで選べる項目のメソッド名。必須・パスワードチェック・ファイルサイズ・入力の変換・重複禁止(メールアドレス)は書いても選べません。

入力欄のテンプレート(input.twig)です。

{% set palette = (definition.config.palette ?? '#000000')|split(',') %}
{% for color in palette %}
  <label>
    <input type="radio" name="{{ name }}" value="{{ color }}"{% if color in values %} checked{% endif %}>
    <span style="background: {{ color }}">{{ color }}</span>
  </label>
{% endfor %}

テンプレートで使える値

内容

name(標準のテンプレートでは {name})

値の入力の name。複数の値を送るときは {{ name }}[] にします。

values(標準のテンプレートでは {values.0}・{values.1}…)

保存済みの値の配列。

definition(標準のテンプレートでは {definition.key}・{definition.label}・{definition.type}・{definition.description}・{definition.config.<キー>})

定義。config に型ごとの設定が入ります。

  • field[] の宣言・:search・:v# は編集画面が出すため、テンプレートには書きません。

  • 標準のテンプレートでは BEGIN_IF などの条件分岐が使えません。選択状態など、条件分岐が要るときは .twig で書きます。

  • Twig では |raw を使わないでください。保存済みの値から XSS になります。

  • ファイルの入力(<input type="file">)は使えません。あると保存が止まります。

  • カスタムフィールドメーカーで作った HTML をそのまま貼らないでください。value="{キー}" のような書き方はこのテンプレートでは空になり、保存すると値を空で上書きします。

  • テーマ・プラグインの型は、フィールドグループの中では使えません(値は保持されます)。

  • 型の宣言はテンプレートのキャッシュに保存されます。宣言を変えたときは、テンプレートのキャッシュを削除すると読み直します。

値の保存・テンプレートでの出し方は、テキストの型と同じです({mytheme_color のキー} ではなく、定義したフィールドのキーで {キー} と書きます)。JS で見た目を作り込むときは、管理画面の JS イベント field-definition.field.rendered / field-definition.field.remove で、入力欄が入った・外れるタイミングを受け取れます(プラグインからの拡張)。

表示する場所

エントリーの編集画面などに、フィールドセットを出す場所を足します。

  1. themes/<テーマ>/admin/field-definitions/placements.json に場所を宣言します。

  2. 編集画面のテンプレート(エントリーなら admin/entry/edit.html など)の、<acms-custom-fields> と同じフォームの中に、同じ名前の差し込み口を置きます。

  3. フィールド定義の画面で、フィールドセットの「表示する場所」で足した場所を選び、「設定を保存」を押します。

{
  "version": 1,
  "placements": {
    "entry": [
      { "name": "top", "label": "一番上", "hint": "短い入力向きです。" }
    ]
  }
}
<acms-custom-fields-slot placement="top"></acms-custom-fields-slot>

キー

必須

内容

version

必須

1

placements

必須

対象(entry など)ごとの場所の配列。

name

必須

英小文字で始まる、英小文字・数字・ハイフン・アンダースコアの 32 文字以内。main は使えません。

label

必須

「表示する場所」の選択肢に出す名前。

hint

定義画面でその場所を選んだときに出す案内。

  • エントリーの foot(本文の下)・side(サイドバー)は標準の場所です。同じ名前を宣言しても無視されるため、別の名前にします。

  • 差し込み口が無い画面では、その場所のフィールドセットは <acms-custom-fields> の位置に出ます。差し込み口はフォームの外に置いても使われません。

  • 名前を変えると、その場所を選んだフィールドセットは標準の位置に戻ります。一度使った名前は変えないでください。