Twig Field Value

Drupalテンプレートでフィールドラベル、値、生データ、参照エンティティを抽出するためのTwigフィルターを提供します。

twig_field_value

40,640 sites

162

drupal.org

theme api

Twig theming field template filter entity-reference render-array theme-development

Drupal 8 Drupal 9 Drupal 10 Drupal 11

インストール

Drupal 11, 10, 9, 8 v2.0.5

composer require 'drupal/twig_field_value:^2.0'

概要

Twig Field Valueは、Drupalテーマ開発者向けのユーティリティモジュールで、テンプレート内のフィールドrender arrayを操作するための4つの強力なTwigフィルターを提供します。このモジュールにより、テーマ開発者はフィールドラベルとフィールド値を個別に出力でき、デフォルトのフィールドラッパーマークアップなしでフィールド出力を完全に制御できます。

このモジュールは、フィールドラベルを抽出するfield_label、ラッパーなしでレンダリングされたフィールド値を取得するfield_value、生のフィールドプロパティ値に直接アクセスするfield_raw、エンティティ参照フィールドから参照先のエンティティオブジェクトを取得するfield_target_entityを提供します。すべてのフィルターはDrupalのアクセス制御システムを尊重し、キャッシュメタデータを適切にバブルアップします。

このモジュールは、カスタムフィールドレイアウトの作成、altテキスト付きの画像ギャラリーの構築、参照エンティティのカスタム形式での反復処理など、フィールド出力のきめ細かい制御が必要なテーマ開発者に不可欠です。

Features

フィールドrender arrayからラベルのみを抽出して出力するfield_label Twigフィルターを提供
フィールドラッパーマークアップなしでフィールド値のrender arrayを返すfield_value Twigフィルターを提供（単一値・複数値フィールドの両方に対応）
フィールドデータから生のフィールドプロパティ値（alt text、target_id、valueなど）に直接アクセスするfield_raw Twigフィルターを提供
Image、File、Taxonomy termなどのエンティティ参照フィールドから実際の参照先エンティティオブジェクトを取得するfield_target_entity Twigフィルターを提供
Drupalのアクセス制御システムを尊重 - アクセス不可のフィールドおよびフィールドアイテムは適切に非表示
フィールドrender arrayからキャッシュメタデータとattachmentsを適切にバブルアップし、正しいキャッシュ動作を保証
コンテキストからエンティティの翻訳を自動的に取得することで多言語サイトをサポート
テキスト、画像、ファイル、エンティティ参照、タクソノミーフィールドなど様々なフィールドタイプに対応
#field_collection_item親オブジェクトをサポートすることでField Collectionモジュールと互換性あり

Use Cases

フィールドラベルと値を別々に表示

field_labelとfield_valueフィルターを使用して、ラベルと値のマークアップを個別に制御するカスタムフィールドレイアウトを作成: <strong>{{ content.field_name|field_label }}</strong>: {{ content.field_name|field_value }}

複数のフィールド値を区切り文字で結合

複数値フィールドの場合、field_valueとsafe_joinを使用してカンマ区切りリストやその他の形式で出力: {{ content.field_tags|field_value|safe_join(', ') }}

altテキスト付きのカスタム画像出力を構築

画像URLとaltテキストを別々に抽出してカスタム画像マークアップを構築: <img src="{{ file_url(content.field_image|field_target_entity.uri.value) }}" alt="{{ content.field_image|field_raw('alt') }}">

参照エンティティの反復処理

複数の参照エンティティをループしてカスタムリストやレイアウトを作成: {% for item in content.field_tags|field_target_entity %}<li>{{ item.label }}</li>{% endfor %}

特定のフィールドプロパティにアクセス

field_rawを使用してvalue、format、alt、title、target_idなど任意のフィールドプロパティにアクセス: {{ content.field_link|field_raw('uri') }} または {{ content.field_text|field_raw('format') }}

参照エンティティでキャッシュメタデータを保持

field_target_entityを使用する際、キャッシュメタデータを保持するために元のフィールドをレンダリング: {{ content.field_ref|field_target_entity.label }}{% set dummy = content.field_ref|render %}

Tips

反復処理の前に複数値フィールドに複数の値があるか確認: {% if content.field_name.1 %}...{% endif %}
file_url() Twig関数をfield_target_entityと組み合わせて、ファイル/画像エンティティの適切なURLを生成
フィルターはDrupalのアクセス制御を尊重 - フィールドまたはエンティティにアクセスできない場合はNULLが返される
エンティティ参照フィールドでは、field_target_entityが現在の言語コンテキストに基づいて翻訳されたエンティティを自動的に返す
キャッシュメタデータは自動的にrenderコンテキストにバブルアップされ、適切なキャッシュ無効化を保証

Technical Details

フィールド値が予期せずNULLを返す

フィルターにフィールドrender array（#theme = 'field'を持つもの）を渡していることを確認してください。フィルターはフィールドrender arrayでのみ動作し、通常はエンティティテンプレートでcontent.field_name経由でアクセスします。

参照エンティティの変更が反映されない（キャッシュの問題）

field_target_entityを使用して参照エンティティからデータを出力する場合、キャッシュメタデータを取得するために元のフィールドをレンダリングしてください: {% set dummy = content.field_name|render %}

アイテムレベルでアクセス制御があるエンティティ参照フィールドでfield_rawがNULLを返す

field_rawフィルターはエンティティ参照フィールドのフィールドアイテムレベルでのアクセス制御をサポートしていません。これはREADMEに記載されている既知の制限です。エンティティレベルのアクセス制御を適切に尊重するfield_target_entityの使用を検討してください。

フィールドアイテムが表示されているのにfield_target_entityがNULLを返す

これはフィールドアイテムレベルのアクセス制御（個々のアイテムに#access = FALSE）が適用されている場合に発生します。フィルターはブロックされたアイテムに対応する参照エンティティを特定できず、安全のためにNULLを返します。警告メッセージについてはDrupalログを確認してください。

field_rawフィルターはエンティティ参照フィールドのフィールドフォーマッターとフィールドアイテムレベルのアクセスチェックをバイパスします - ユーザー生成コンテンツを出力する際は注意して使用してください
field_target_entityフィルターはアイテムレベルのアクセス制御（個々のフィールドアイテムの#access = FALSE）を強制できません - この状況が検出されると警告がログに記録されます
すべてのフィルターはフィールドレベルのアクセス制御をチェックします - フィールド全体に#access = FALSEがある場合、データは返されません
field_rawからの生の値は、ユーザー提供コンテンツを出力する際にテンプレートで適切にエスケープする必要があります