カスタムフィールド

カスタムフィールドはコンテンツ（ページ・コレクション・モジュール・カレンダー）に任意の入力項目を用意できる機能です。

たとえば、お知らせ記事用のコンテンツタイプに、お知らせ種類を選択するためのラジオボタンを用意するという場合に、カスタムフィールドを活用することができます。

カスタムフィールドはフィールド設定ファイル（system/config/fields.php）に定義します。 定義されたカスタムフィールドは、各コンテンツで同様に利用することができます。

カスタムフィールドを利用する

フィールド設定ファイル（system/config/fields.php）には、いくつかのカスタムフィールドがあらかじめ定義されています。 それらのカスタムフィールドはコンテンツ設定ファイルで指定すると利用できます。

コンテンツ設定ファイル（pages.php, collections.php, modules.php, calendars.php）の各コンテンツタイプの fields 項目に利用したいフィールドを指定します。 たとえば、ページコンテンツのお知らせ記事用の info_article タイプで、リンクフィールドを使いたい場合はページコンテンツ設定ファイル（system/config/pages.php）で次のように指定します。

return [
    'info_article' => [
        'label' => 'お知らせ記事',
         // ... 省略
        'fields' => [
            'info_link' => [ // （このコンテンツタイプ内で識別するための）フィールド名
                'type' => 'link', // フィールドタイプ名
            ],
        ],
    ],
];

fields 項目にフィールドを列挙します。キーはこのコンテンツタイプでフィールドを識別するための任意の名前を指定します。ここでは、'info_link' を指定しています。 'type' には fields.php で定義されているフィールドタイプ名（link）を指定します。

このように利用したいフィールドタイプを指定すると、コンテンツ編集画面に該当フィールドの入力部品が表示されてデータを登録できるようになります。 登録されたデータはテンプレートで次のように記述すると出力されます。

{{ field('info_link') }}

field() 関数の引数の 'info_link' はページコンテンツ設定ファイルで指定したフィールド名を指定します。

カスタムフィールド設定

カスタムフィールドの設定ファイルは system/config/fields.php です。この設定ファイルに定義したフィールドは各コンテンツ（ページ・コレクション・モジュール・カレンダー）で利用できます。 この設定ファイルはPHPの配列で定義されます。配列のキーがフィールドタイプ名になりその要素にいくつかの項目を定義できます。

設定ファイルのフォーマットと設定項目について説明します。
設定ファイルフォーマット：

<?php

return [
    'フィールドタイプ名' => [
        // フィールドタイプの設定項目
        'inputs' => [
            'インプット名' => [
                // インプットの設定項目
            ],
            // ... 以降のインプット設定
        ],
    ],
    // ... 以降のフィールドタイプ設定
];

フィールドタイプの設定項目：

['link']

インプット（inputs）の設定項目：

[
    '' => 'なし',
    'lead' => 'リード',
],

[
    'rows' => '10',
    'placeholder' => 'ここに複数行のテキストを入力してください。',
],

設定例

    'link' => [ // フィールドタイプ名
        'label' => 'リンク',
        'inputs' => [
            'href' => [
                'label' => 'URL',
                'rule' => '',
                'value' => '',
            ],
            'text' => [
                'label' => 'リンク文字列',
                'rule' => '',
                'value' => 'リンク',
            ],
        ],
    ],

カスタムフィールドテンプレート

カスタムフィールドそれぞれに入力テンプレートと出力テンプレートを持ちます。

入力テンプレートは、コンテンツ編集画面でinput要素などの入力部品を表示するために使われます。
例：

<div class="form-group row">
  <label class="col-xl-3 form-control-label" for="{{ input_id('text') }}">{{ field.label }}</label>
  <div class="col-xl-9">
    <input type="text" id="{{ input_id('text') }}" name="{{ input_name('text') }}" class="form-control"
           value="{{ form.field('text') }}" placeholder="">
    {{ form.error(input_id('text'))|raw }}
  </div>
</div>

出力テンプレートは、公開ページでカスタムフィールドの内容を出力するために使われます。
例：

{{ field.text }}

フィールドの出力テンプレートに割り当てられる変数：

基本的には入出力テンプレートはフィールド毎に用意しますが、他のフィールド名を指定すると他のフィールドの入出力テンプレートを利用することができます。 そのため、入力部品が同じで出力だけ変えたい場合には出力テンプレートだけを作成すれば良いということになります。

入出力テンプレートはサイトテーマの inputs, outputs ディレクトリに保存します。 デフォルトで用意されるフィールドは cms テーマ（public/themes/cms/views/）の inputs, outputs ディレクトリに用意されています。 ただし、cms テーマは製品側のファイルのため、それらのファイルを書き換えても製品をアップデートしたタイミングで変更した内容が消えてしまいます。 この内容を変更したい場合は、同名のファイルをサイトテーマ側に配置することで優先して利用される仕組みです。

テンプレートが選択される順序は次になります。
linksフィールドの出力テンプレートの例：

※ 入力テンプレートの場合は output(s) を input(s) に読み替えてください。
※ 上記の「site」は、cms.php の theme 設定に「site」を指定している場合の例になります。

独自項目とカスタムフィールド設定の上書き

フィールド設定では、規定されていない独自の項目を定義することができます。
imageフィールドで class 項目を定義する例。(system/config/fields.php)

'image' => [
    'label' => '画像',
    // ... 省略
    'class' => 'img-fluid',
],

フィールド設定の項目は config 変数に格納されて、フィールドの出力テンプレートに渡されます。次のように {{ config.class }} という記述で出力することができます。（例：themes/cms/views/outputs/image.twig）

{% if field.src %}
  <img src="{{ field.src|resize(field.resize) }}" class="{{ config.class }}" alt="{{ field.alt }}" {{ field_data_id('src') }}>
{% endif %}

コンテンツタイプ設定（ページ・コレクション・モジュール・カレンダー）ではフィールドの定義を上書きすることができます。 次は、カスタムフィールド設定（system/config/fields.php）で定義した image フィールドを type に指定しています。label, class はこのコンテンツ設定で上書きするために指定しています。

'left_image' => [
    'label' => '左ボックス画像',
    'type' => 'image',
    'class' => 'img-fluid img-thumbnail',
],

独自カスタムフィールドを用意する

デフォルトで用意されているカスタムフィールドとは別に、独自にカスタムフィールドを定義して利用することができます。 独自にカスタムフィールドを定義すると、任意の入力項目を設けたり、公開サイトのデザインに合わせた出力に対応することができます。

フィールド設定ファイルに独自フィールドの定義を追加して、入出力テンプレートを作成すれば独自カスタムフィールドを用意することができます。 独自に用意するカスタムフィールドはデフォルトのカスタムフィールドと同じ仕組みで動作するので、デフォルトのカスタムフィールドのつくりが参考になります。

textareaフィールドを元に特定のクラスが指定されたdiv要素を出力する独自カスタムフィールドを定義する例を示します。 fields.php の textarea フィールドをコピーして独自のフィールドタイプ名とラベルとインプットテンプレートを指定します。

    'lead_text' => [
        'label' => 'リード文',
        'input_template' => 'textarea',
        'inputs' => [
            'textarea' => [
                'label' => 'リード文',
                'rule' => '',
                'value' => '',
            ],
        ],
    ],

input_template に textarea を指定すると、textareaフィールド用の入力テンプレートを利用できるので、別途用意する必要はありません。

出力テンプレートを作成します。
public/site/views/outputs/lead_text.twig

<div class="lead" {{ field_data_id('textarea') }}>
{{ field.textarea|nl2br }}
</div>

この例では入力テンプレートはtextarea用を流用したので、設定の定義と出力テンプレートを準備するだけで独自のカスタムフィールドを作成できました。

コンテナフィールド

カスタムフィールドの１つの種類にコンテナフィールドがあります。 コンテナフィールドは他のフィールドをブロックとして配置できるコンテナを持ちます。

コンテナフィールドの設定例：

    'content' => [
        'label' => 'コンテンツ',
        'container' => 1,
        'fields' => [
            'p_class',
            'text',
            'textarea',
            'heading',
            'card',
            'richtext',
            'image',
            'ul',
            'ol',
            'table_2',
            'html',
            'module',
        ],
    ],

フィールドタイプ設定で container 項目に 1 を指定したフィールドがコンテナフィールドになります。 fields 項目にそのコンテナフィールドで利用できるフィールドタイプを列挙します。

入力テンプレートではコンテナ領域を表示します。出力テンプレートではコンテナ内の子フィールドを順番に出力します。 テンプレートのつくりはコンテナフィールドではない他のフィールドとは異なりますが、デフォルトで用意されるコンテナフィールドのテンプレートを参考に独自のコンテナフィールドを作成することもできます。

入力テンプレートの例：

<div class="mb-3 block-field">
  <label class="col-xl-3 form-control-label" for="{{ input_id('title') }}">{{ field.label }}</label>
  <div class="block-container mb-2" data-container="{{ fieldName }}">
    {% for index, row in form.fieldContainer(fieldName) %}
      {% for childFieldName, childField in row %}
        {{ set_field(childFieldName, fieldName, index) }}
        {% set childFieldConfig = form.getChildField(childFieldName, fieldName) %}
        {% include input_template_path(childFieldName, childFieldConfig) ignore missing with {'field':childFieldConfig} %}
      {% endfor %}
    {% endfor %}
  </div>
  <div>
    {% for addFieldName, addField in field.fields %}
      <input type="button" class="btn btn-sm btn-outline-primary" value="{{ addField.label }}"
           data-add-filed-name="{{ addFieldName }}" data-filed-name="{{ fieldName }}">
    {% endfor %}
  </div>
</div>

出力テンプレートの例：

<div>
  {% for index, row in field %}
    {% for childFieldName, childField in row %}
      <div>
        {{ child_field(childFieldName, index, fieldName) }}
      </div>
    {% endfor %}
  {% endfor %}
</div>