Drupal の Twig を用いたフィールドのテンプレート出力まとめ

このページでは Drupal の Twig を用いたフィールドの出力をカスタマイズするためのテンプレート命名規則と、管理画面で入力した値を Twig ファイル内で取得し加工するための方法をフィールドの種類ごとに説明していきます。

フィールドのテンプレート命名規則

Drupal の管理画面よりコンテンツタイプやタクソノミーに登録したフィールドは、以下テンプレートファイルの命名規則となっています。

原則、対象範囲が狭いテンプレートが優先され、以下に記述している規則にいずれにも該当しない場合、最後にある field.html.twig で出力される規則となっています。

Drupal が上からの順番でテンプレートファイルを探す流れとなります。

1. field--[entity-name]--[field-name]--[entity-type].html.twig
2. field--[entity-name]--[field-name].html.twig
3. field--[entity-name]--[entity-type].html.twig
4. field--[field-name].html.twig
5. field--[field-type].html.twig
6. field.html.twig

大カッコ書きになっている箇所が使用箇所や種別によって変わってくるのですが、以下を参考に適切なファイル名を付与してください。

• [entity-name]
  • node や taxonomy-term など
• [entity-type]
  • node のタイプ (bundle) や taxonomy のタイプ (bundle) など
• [field-name]
  • フィールドのシステム内部名称 field_◯◯◯ など
• [field-type]
  • フィールドの種類 string や text-with-summary など

※ただし [parent-entity-name] [parent-entity-type] [field-name] [field-type] にアンダースコア ( _ ) がある場合はハイフン ( - ) に置き換えてテンプレートファイルを作成してください（正常に作成したテンプレートファイルを検知しないため）。

参考 field.html.twig | Drupal 10.1 | Drupal API

テキスト (プレーン), Text (plain)

フィールドタイプは string になるのでフィールドタイプ粒度のテンプレートファイルを作る場合は field--string.html.twig という命名規則になります。

このフィールドタイプで実際に Drupal 上で入力した値をそのまま取得し、加工した上で出力したいシチュエーションがあると思うので、取得する方法を記載します。

フィールドが2つ以上の繰り返し要素の場合

{% for item in items %}
  ▼ Drupal で入力した値が string 型で返却される
  {% set text = item.content['#context'].value %}
  Drupal で入力した値: {{ text }}
{% endfor %}

フィールドが繰り返し要素ではない場合

フィールドのストレージの設定を 制限 かつ 1つ だけの場合、以下のように短縮して記述することもできます（添字番号を直接指定しているだけです）。

▼ Drupal で入力した値が string 型で返却される
{% set text = items.0.content['#context'].value %}
Drupal で入力した値: {{ text }}

テキスト (プレーン, 長文), Text (plain, long)

フィールドタイプは string-long になるのでフィールドタイプ粒度のテンプレートファイルを作る場合は field--string-long.html.twig という命名規則になります。

このフィールドタイプで入力した値の取得に関しては テキスト (プレーン) と同じため、省略します。

テキスト (フォーマット付き), Text (formatted)

フィールドタイプは text になるのでフィールドタイプ粒度のテンプレートファイルを作る場合は field--text.html.twig という命名規則になります。

このフィールドタイプでも Drupal 上で入力した値をそのまま取得できることができますが、HTML の要素がそのまま含まれた状態で返却され、本来 テキストフォーマット で制限している要素もエスケープされていない状態で取得してしまうので、値を取り回して使用するには注意が必要と言えます。

テキストフォーマットで設定した各種設定を適応したあとの HTML を取得するためには render フィルターを適応する必要があります。

{% for item in items %}
  ▼ Drupal のテキストフォーマットの設定を加味した値
  {% set html = (item.content | render) %}
  ※勿論入力した値を加工などせずそのまま出力するだけならこの記述で出力できます
  {{ item.content }}
{% endfor %}

テキスト (フォーマット付き, 長文), Text (formatted, long)

フィールドタイプは text-long になるのでフィールドタイプ粒度のテンプレートファイルを作る場合は field--text-long.html.twig という命名規則になります。

このフィールドタイプで入力した値の取得に関しては テキスト (フォーマット付き) と同じため、省略します。

テキスト (フォーマット付き, 長文, 概要あり), Text (formatted, long, with summary)

フィールドタイプは text-with-summary になるのでフィールドタイプ粒度のテンプレートファイルを作る場合は field--text-with-summary.html.twig という命名規則になります。

基本的には テキスト (フォーマット付き, 長文) と同じなのですが、 概要 で入力した値を表示したい場合は、その場合は Twig のテンプレートを調整するのではなく、Drupal の管理画面上の サイト構築 > コンテンツタイプ > [変更したいコンテンツタイプ] > 表示管理 から編集することができます。

添付画像のように、フィールドに対する表示フォーマットを 概要か切り詰め を選択してもらうことで表示することができます。

もし、両方の値を取得したい場合は、少しトリッキーな実装が必要ですが、以下のように記述することで値を取得することができます（もし上記画像のように表示フォーマットを 概要か切り詰め にしていたら Default に戻してください）。

{% for item in items %}
  概要: {{ element['#object'].get(field_name)[loop.index0].summary }}
  本文: {{ item.content }}
{% endfor %}

loop.index0 は for ~ endfor 内のループオブジェクトの0開始のインデックスが入っているので、フィールドが繰り返し要素でないなら以下で取得できます。

概要: {{ element['#object'].get(field_name)[0].summary }}
本文: {{ items.0.content }}

loop 変数についての詳細は Twig のドキュメントを参照ください。

for - Documentation - Twig - The flexible, fast, and secure PHP template engine

リスト（テキスト）, List (text)

プルダウンを定義したい際に使用するフィールドです。

フィールドタイプは list-string になるのでフィールドタイプ粒度のテンプレートファイルを作る場合は field--list-string.html.twig という命名規則になります。

フィールドの設定としては以下のように、改行で選択肢候補を定義し、パイプ記号で左側にシステムで保持するキーと右側にラベルを定義することができます。

a|選択肢A
b|選択肢B
c|選択肢C

デフォルトだとラベルが出力されるのですが、キーをテンプレート側で取得し表示するには Twig のテンプレートを調整するのではなく、Drupal の管理画面上の サイト構築 > コンテンツタイプ > [変更したいコンテンツタイプ] > 表示管理 から編集することができます。

添付画像のように、フィールドに対する表示フォーマットを キー を選択してもらうことで表示することができます。

もし、両方の値を取得したい場合は "テキスト (フォーマット付き, 長文, 概要あり)" と同様に少しトリッキーな実装が必要ですが、以下のように記述することで値を取得することができます（もし上記画像のように表示フォーマットを キー にしていたら Default に戻してください）。

{% for item in items %}
  キー: {{ element['#object'].get(field_name)[loop.index0].value }}
  ラベル: {{ item.content }}
{% endfor %}

loop.index0 は for ~ endfor 内のループオブジェクトの0開始のインデックスが入っているので、フィールドが繰り返し要素でないなら以下で取得できます。

キー: {{ element['#object'].get(field_name)[0].value }}
ラベル: {{ items.0.content }}

"テキスト (フォーマット付き, 長文, 概要あり)" と同様ですが loop 変数についての詳細は Twig のドキュメントを参照ください。

for - Documentation - Twig - The flexible, fast, and secure PHP template engine

その他

誠意記事執筆中です。
テキスト系のフィールドは一通り記載したので、一旦公開。