Twig Field Value
Provides Twig filters for extracting field labels, values, raw data, and referenced entities in Drupal templates.
twig_field_value
Install
composer require 'drupal/twig_field_value:^2.0'
Overview
Twig Field Value is a utility module designed for Drupal theme developers that provides four powerful Twig filters for working with field render arrays in templates. The module enables themers to print field labels and field values individually, giving complete control over field output without the default field wrapper markup.
The module provides field_label for extracting field labels, field_value for getting rendered field values without wrappers, field_raw for accessing raw field property values directly, and field_target_entity for retrieving referenced entity objects from entity reference fields. All filters respect Drupal's access control system and properly bubble cache metadata.
This module is essential for theme developers who need fine-grained control over field output, especially when creating custom field layouts, building image galleries with alt text, or iterating over referenced entities in a custom manner.
Features
- Provides the field_label Twig filter to extract and print only the label from a field render array
- Provides the field_value Twig filter to return field value render arrays without the field wrapper markup, supporting both single and multi-value fields
- Provides the field_raw Twig filter to access raw field property values (e.g., alt text, target_id, value) directly from the field data
- Provides the field_target_entity Twig filter to retrieve the actual referenced entity objects from entity reference fields like Image, File, Taxonomy term, etc.
- Respects Drupal's access control system - inaccessible fields and field items are properly hidden
- Properly bubbles cache metadata and attachments from field render arrays to ensure correct caching behavior
- Supports multilingual sites by automatically retrieving entity translations from context
- Works with various field types including text, image, file, entity reference, and taxonomy fields
- Compatible with Field Collection module by supporting #field_collection_item parent objects
Use Cases
Displaying field label and value separately
Use the field_label and field_value filters to create custom field layouts with separate control over the label and value markup: <strong>{{ content.field_name|field_label }}</strong>: {{ content.field_name|field_value }}
Joining multiple field values with a separator
For multi-value fields, use field_value with safe_join to create comma-separated lists or other formatted output: {{ content.field_tags|field_value|safe_join(', ') }}
Building custom image output with alt text
Extract the image URL and alt text separately to build custom image markup: <img src="{{ file_url(content.field_image|field_target_entity.uri.value) }}" alt="{{ content.field_image|field_raw('alt') }}">
Iterating over referenced entities
Loop through multiple referenced entities to create custom lists or layouts: {% for item in content.field_tags|field_target_entity %}<li>{{ item.label }}</li>{% endfor %}
Accessing specific field properties
Use field_raw to access any field property such as value, format, alt, title, target_id, etc.: {{ content.field_link|field_raw('uri') }} or {{ content.field_text|field_raw('format') }}
Preserving cache metadata with referenced entities
When using field_target_entity, render the original field to preserve cache metadata: {{ content.field_ref|field_target_entity.label }}{% set dummy = content.field_ref|render %}
Tips
- Always check if a multi-value field has more than one value before iterating: {% if content.field_name.1 %}...{% endif %}
- Use file_url() Twig function with field_target_entity to generate proper URLs for file/image entities
- The filters respect Drupal's access control - if a field or entity is not accessible, NULL is returned
- For entity reference fields, field_target_entity automatically returns the translated entity based on the current language context
- Cache metadata is automatically bubbled to the render context, ensuring proper cache invalidation
Technical Details
Troubleshooting 4
Ensure you are passing a field render array (with #theme = 'field') to the filter. The filters only work with field render arrays, typically accessed via content.field_name in entity templates.
When printing data from referenced entities using field_target_entity, render the original field to capture its cache metadata: {% set dummy = content.field_name|render %}
The field_raw filter does not support access control at field item level for entity reference fields. This is a known limitation documented in the README. Consider using field_target_entity which properly respects entity-level access control.
This occurs when field item-level access control is applied (via #access = FALSE on individual items). The filter cannot determine which referenced entity corresponds to the blocked item and returns NULL for safety. Check the Drupal logs for an alert message.
Security Notes 4
- The field_raw filter bypasses field formatters and access checks at the field item level for entity reference fields - use with caution when outputting user-generated content
- The field_target_entity filter cannot enforce item-level access control (#access = FALSE on individual field items) - a warning is logged when this situation is detected
- All filters check field-level access control - if the entire field has #access = FALSE, no data is returned
- Raw values from field_raw should be escaped appropriately in templates when outputting user-provided content