Twig Tweak
Un módulo de extensión de Twig que proporciona funciones y filtros útiles para el desarrollo en Drupal, permitiendo renderizar fácilmente entities, blocks, views, menus y más directamente en las plantillas Twig.
twig_tweak
Install
composer require 'drupal/twig_tweak:^3.4'
composer require 'drupal/twig_tweak:^3.3'
Overview
Twig Tweak es un módulo potente que extiende el motor de plantillas Twig con un conjunto completo de funciones y filtros diseñados específicamente para el desarrollo en Drupal. Sirve de puente entre la arquitectura basada en PHP de Drupal y la sintaxis de plantillas de Twig, permitiendo a los desarrolladores de temas acceder a la funcionalidad de Drupal directamente en las plantillas sin escribir código PHP en hooks de preproceso.
El módulo proporciona más de 20 funciones Twig para renderizar blocks, entities, fields, views, menus, imágenes, formularios y más. También incluye más de 17 filtros para operaciones comunes como reemplazo de tokens, estilos de imagen, generación de URLs y manejo de metadatos de cache. Todas las funciones manejan correctamente el sistema de render array de Drupal y los metadatos de cache, asegurando un rendimiento óptimo y un comportamiento de cache correcto.
Para propósitos de desarrollo, Twig Tweak incluye funciones de depuración como drupal_dump() y dd() para inspección de variables, drupal_breakpoint() para integración con Xdebug, y comandos Drush para validar y depurar plantillas Twig. El módulo está diseñado pensando en el rendimiento, utilizando servicios de carga diferida para minimizar la sobrecarga cuando las funciones no se utilizan.
Features
- Renderizar plugins de block directamente en plantillas Twig con drupal_block(), soportando configuración personalizada y mapeo de contexto
- Incrustar displays de Views con drupal_view() y verificar resultados de views con drupal_view_result() para renderizado condicional
- Renderizar cualquier tipo de entity con drupal_entity() soportando modos de vista, códigos de idioma y verificación de acceso
- Mostrar formularios de edición/creación de entities con drupal_entity_form() incluyendo soporte para modos de formulario personalizados
- Renderizar fields individuales de entities con drupal_field() usando modos de vista u opciones de visualización personalizadas
- Construir y renderizar menus con drupal_menu() soportando profundidad, niveles y expansión configurables
- Renderizar imágenes por ID de archivo, UUID o URI con drupal_image() soportando estilos de imagen e imágenes responsive
- Acceder a valores de configuración de Drupal con drupal_config() y reemplazar tokens con drupal_token()
- Generar URLs y enlaces con drupal_url() y drupal_link() incluyendo verificación de acceso
- Renderizar regiones de tema con drupal_region() para layouts de página personalizados
- Mostrar mensajes de estado con drupal_messages() y breadcrumbs con drupal_breadcrumb()
- Añadir enlaces contextuales a cualquier elemento con drupal_contextual_links()
- Depurar variables con drupal_dump()/dd() usando integración con Symfony VarDumper
- Establecer puntos de interrupción de Xdebug en plantillas con drupal_breakpoint()
- Aplicar estilos de imagen a URIs con el filtro image_style
- Extraer URIs y URLs de archivos de entities y fields con los filtros file_uri y file_url
- Generar URLs y enlaces de entities con los filtros entity_url y entity_link
- Obtener traducciones de entities con el filtro translation para sitios multilingües
- Extraer y propagar metadatos de cache con el filtro cache_metadata para un cacheo correcto
- Filtrar hijos de render array con el filtro children
- Realizar reemplazos con expresiones regulares con el filtro preg_replace
- Reemplazar tokens en cadenas con el filtro token_replace
- Transliterar Unicode a ASCII con el filtro transliterate
- Truncar cadenas de forma segura con el filtro truncate
- Crear URIs de datos para incrustación inline con el filtro data_uri
- Comandos Drush para validación (twig-tweak:lint) y depuración (twig-tweak:debug) de plantillas Twig
- Arquitectura extensible con hooks para añadir funciones, filtros y tests personalizados
Use Cases
Renderizar un plugin de block en una plantilla de página personalizada
Usa drupal_block() para incrustar plugins de block directamente en plantillas sin configurarlos en el layout de blocks. Ejemplo: {{ drupal_block('system_branding_block', {use_site_name: true}) }} renderiza el branding del sitio. Para blocks que requieren contexto, usa context_mapping: {{ drupal_block('plugin_id', {context_mapping: {node: '@node.node_route_context:node'}}) }}
Incrustar Views en plantillas con filtros contextuales
Usa drupal_view() para incrustar displays de Views en plantillas, opcionalmente pasando argumentos de filtros contextuales. Ejemplo: {{ drupal_view('articles', 'block_1', node.id) }} incrusta una vista con el ID del nodo actual como filtro contextual. Verifica primero si la vista tiene resultados: {% if drupal_view_result('related', 'block_1')|length > 0 %}{{ drupal_view('related', 'block_1') }}{% endif %}
Mostrar contenido relacionado renderizando fields de entity
Renderiza fields específicos de entities referenciadas: {{ drupal_field('field_image', 'node', node.id, 'teaser') }}. Para configuraciones de visualización personalizadas: {{ drupal_field('field_image', 'node', 1, {type: 'image_url', settings: {image_style: 'large'}}) }}
Crear imágenes responsive con estilos de imagen
Renderiza imágenes con estilos usando drupal_image(): {{ drupal_image('public://hero.jpg', 'wide', {alt: 'Hero image'|t}, responsive=true) }}. Para imágenes de fields, combina con filtros: {% set uri = node.field_image|file_uri %}{% if uri %}{{ drupal_image(uri, 'thumbnail') }}{% endif %}
Construir menus personalizados con profundidad específica
Renderiza menus con control sobre niveles y expansión: {{ drupal_menu('main', 2, 3) }} renderiza el menu principal comenzando en el nivel 2 con profundidad 3. Usa expand=true para menus completamente expandidos: {{ drupal_menu('main', expand=true) }}
Manejar contenido multilingüe en plantillas
Obtén entities traducidas usando el filtro translation: {{ media|translation.field_description|view }}. El filtro usa el contexto de idioma actual por defecto o acepta un código de idioma: {{ node|translation('fr') }}
Asegurar un cacheo correcto con el filtro cache_metadata
Al acceder a valores raw de entities, propaga los metadatos de cache para prevenir contenido obsoleto: <img src="{{ node.field_image|file_url }}" />{{ content.field_image|cache_metadata }}. Esto asegura que el cache de renderizado se invalide cuando la imagen cambie.
Depurar variables en plantillas durante el desarrollo
Usa dd() (alias de drupal_dump) para inspeccionar variables: {{ dd(node) }} muestra el objeto node. Llámalo sin argumentos para mostrar todas las variables de la plantilla: {{ dd() }}. Requiere el paquete symfony/var-dumper para mejor salida. Usa drupal_breakpoint() para activar puntos de interrupción de Xdebug.
Crear iconos SVG inline usando URIs de datos
Incrusta iconos SVG inline usando el filtro data_uri: <img src="{{ source(directory ~ '/images/icon.svg')|data_uri('image/svg+xml') }}" />. Esto elimina peticiones HTTP adicionales para gráficos pequeños.
Renderizar formularios de entity para edición frontend
Muestra formularios de edición de entity: {{ drupal_entity_form('node', node.id) }}. Crea formularios de nueva entity con valores predeterminados: {{ drupal_entity_form('node', values={type: 'article', title: 'New Article'}) }}. Usa check_access=false para omitir verificaciones de permisos cuando sea necesario.
Acceder a valores de configuración en plantillas
Lee la configuración de Drupal directamente: {{ drupal_config('system.site', 'name') }} muestra el nombre del sitio. Útil para mostrar configuraciones sin hooks de preproceso.
Generar enlaces condicionales con verificación de acceso
Crea enlaces que solo aparecen para usuarios con acceso: {{ drupal_link('Edit'|t, '/node/' ~ node.id ~ '/edit', check_access=true) }}. El enlace no se renderizará si el usuario carece de permiso.
Tips
- Usa argumentos nombrados para parámetros opcionales para mejorar la legibilidad: {{ drupal_entity('block', 'sidebar_block', check_access=false) }}
- La función drupal_view_result() devuelve objetos de resultado, no la vista renderizada - úsala solo para verificar si existen resultados
- Los IDs de plugins de block se pueden encontrar usando Drush: drush ev "print_r(array_keys(\Drupal::service('plugin.manager.block')->getDefinitions()));"
- Para entities de block content, usa drupal_entity('block_content', id) o drupal_block('block_content:<uuid>') - el último incluye el wrapper block.html.twig
- Los filtros file_uri y file_url soportan entities media incluyendo media remota OEmbed, devolviendo la URL remota para recursos externos
- Al renderizar entities, el parámetro check_access es TRUE por defecto - establécelo en FALSE solo cuando hayas verificado el acceso en otro lugar
- drupal_field() no funciona con modos de vista impulsados por Layout Builder - usa la salida renderizada de la entity en su lugar
- Instala symfony/var-dumper para una salida mucho mejor de las funciones drupal_dump() y dd()
- Usa el filtro with como opuesto del filtro without del core para añadir propiedades: {{ content.field_image|with('#title', 'Photo'|t) }}
- Las claves de cache se añaden automáticamente por los view builders - generalmente no necesitas gestionar el cacheo manualmente
Technical Details
Hooks 3
hook_twig_tweak_functions_alter
Permite a los módulos y temas añadir o modificar funciones Twig proporcionadas por Twig Tweak. Las funciones se añaden como objetos TwigFunction.
hook_twig_tweak_filters_alter
Permite a los módulos y temas añadir o modificar filtros Twig proporcionados por Twig Tweak. Los filtros se añaden como objetos TwigFilter.
hook_twig_tweak_tests_alter
Permite a los módulos y temas añadir tests Twig personalizados. Los tests se añaden como objetos TwigTest.
Drush Commands 2
drush twig-tweak:debug
Lista todas las funciones, filtros y tests Twig disponibles en la instalación actual de Drupal con sus firmas. Muestra las rutas del loader para los namespaces de plantillas.
drush twig-tweak:validate
Valida la sintaxis de plantillas Twig y muestra los errores encontrados. Puede verificar archivos individuales, directorios o leer desde STDIN. Alias de twig-tweak:lint.
Security Notes 4
- El filtro PHP (|php) está deshabilitado por defecto y debe permanecer deshabilitado en entornos de producción debido a posibles riesgos de inyección de código
- Al usar check_access=false, asegúrate de haber verificado los permisos del usuario por otros medios para prevenir acceso no autorizado al contenido
- Nunca expongas la configuración $settings['twig_tweak_enable_php_filter'] en configuración accesible por el usuario
- Ten cuidado con drupal_form() ya que renderiza formularios que pueden realizar operaciones sensibles - asegura un control de acceso adecuado