Twig Template Suggester
Proporciona sugerencias de plantilla extensas para elementos de Drupal que el core no cubre, permitiendo un control preciso del theming para blocks, formularios, menús, usuarios, términos de taxonomía y más.
twigsuggest
Overview
Twig Template Suggester llena los vacíos en el sistema de sugerencias de plantilla del core de Drupal proporcionando sugerencias adicionales para una amplia variedad de elementos que el core no soporta nativamente. Esto permite a los themers crear plantillas más específicas basadas en el contexto como regiones, view modes, bundles y tipos de entidad.
El módulo registra automáticamente sugerencias de plantilla para blocks (por región, bundle, provider), páginas y documentos HTML (por tipo de node), usuarios (por rol y view mode), fields (por view mode), formularios (por form ID y región), containers (por tipo y contexto), menús (por región y nombre), términos de taxonomía (por view mode), árboles de libros (por región) y enlaces de acción local (por ruta).
Como utilidad de desarrollo, establece su peso de módulo en 100 para asegurar que sus sugerencias se procesen en último lugar, dándole la palabra final sobre las sugerencias de plantilla. También proporciona una variable global {{ base_path }} a todas las plantillas para una construcción conveniente de rutas de assets.
Features
- Sugerencias de plantilla para blocks por región (block--[region].html.twig, block--[region]--[block_id].html.twig)
- Sugerencias de plantilla para blocks por bundle para blocks personalizados/de contenido (block--bundle--[bundle].html.twig)
- Sugerencias de plantilla para blocks por provider y plugin base con combinaciones de región
- Sugerencias de plantilla HTML y page por tipo de node (html--node--[type].html.twig, page--node--[type].html.twig)
- Sugerencias de plantilla para usuarios por rol más alto, ID de usuario y view mode (user--[role]--[view_mode].html.twig)
- Sugerencias de plantilla para fields por view mode, tipo de entidad y combinaciones de bundle
- Sugerencias de plantilla para formularios por form ID, element ID y región (form--[form_id].html.twig)
- Sugerencias de plantilla para elementos de formulario e inputs por element ID y tipo
- Sugerencias de plantilla para containers por tipo, nombre/display de view, fields de archivo gestionado y estado de padre
- Sugerencias de plantilla para menús por región y nombre de menú (menu--[region].html.twig)
- Sugerencias de plantilla para términos de taxonomía por view mode y bundle
- Sugerencias de plantilla para árboles de libros por región
- Sugerencias de plantilla para acciones locales de menú por ruta del enlace
- Corrección para plantillas de layout específicas de entidad (solución alternativa para el issue del core #2881195)
- Elimina sugerencias de plantilla duplicadas de los blocks
- Proporciona la variable {{ base_path }} a todas las plantillas para rutas de assets
Use Cases
Estilos de block específicos por región
Crea diferentes estilos de block para cada región. Por ejemplo, los blocks en la barra lateral podrían necesitar estilos diferentes que los blocks en el header. Crea plantillas como block--sidebar.html.twig o block--header.html.twig para apuntar a todos los blocks en regiones específicas.
Layouts de página específicos por tipo de node
Aplica layouts de página completamente diferentes para diferentes tipos de contenido. Crea page--node--article.html.twig para artículos con un área de contenido amplia y page--node--landing_page.html.twig para landing pages con una estructura diferente.
Theming de perfil de usuario basado en rol
Muestra perfiles de usuario de manera diferente según los roles de usuario. Crea user--administrator--full.html.twig para perfiles de administrador o user--member.html.twig para miembros regulares.
Plantillas de field conscientes del view mode
Estiliza el mismo field de manera diferente en distintos view modes. Por ejemplo, un field de imagen podría ser grande en view mode 'full' pero una miniatura en 'teaser'. Crea field--field_image--full.html.twig y field--field_image--teaser.html.twig.
Estilos de formulario por formulario o región
Aplica estilos únicos a formularios específicos o a todos los formularios en una región. Usa form--user_login_form.html.twig para el formulario de inicio de sesión, o form--sidebar.html.twig para todos los formularios colocados en la región de barra lateral.
Estilos de menú por región
Estiliza menús de manera diferente según dónde estén colocados. La navegación principal en el header podría ser horizontal (menu--header.html.twig) mientras que el mismo menú en un footer podría estilizarse como una lista vertical (menu--footer.html.twig).
Plantillas de view mode para términos de taxonomía
Muestra términos de taxonomía de manera diferente en diferentes contextos. Crea taxonomy_term--tags--full.html.twig para la página completa del término y taxonomy_term--tags--teaser.html.twig para listados de términos.
Envoltorios HTML específicos por tipo de contenido
Aplica diferentes clases de body o metainformación según el tipo de contenido. Crea html--node--article.html.twig para agregar marcado schema.org específico o códigos de seguimiento solo para artículos.
Tips
- Habilita la depuración de Twig durante el desarrollo para ver todas las sugerencias de plantilla disponibles en los comentarios HTML del código fuente de tu página
- Usa guiones en los nombres de archivo de plantilla (por ejemplo, block--sidebar--main-menu.html.twig) - corresponden a guiones bajos en los nombres de sugerencia
- La variable {{ base_path }} está disponible en todas las plantillas - útil para referenciar assets del theme: {{ base_path ~ directory }}/images/logo.svg
- Para plantillas específicas de tipo de block, considera usar el módulo Block Type Templates junto con Twig Template Suggester para una cobertura más completa
- Las sugerencias de plantilla están ordenadas por especificidad - las sugerencias más específicas aparecen después y tienen precedencia
- Recuerda que las sugerencias de región de menú requieren que el atributo 'region' esté establecido en las plantillas de block de tu theme
Technical Details
Hooks 17
hook_theme_suggestions_block
Agrega sugerencias de plantilla para blocks basadas en región, bundle (para blocks de contenido), provider, plugin base y combinaciones de nombre de menú.
hook_theme_suggestions_layout_alter
Corrige plantillas de layout específicas de entidad agregando doble guión bajo a los IDs de layout cuando la configuración de Display Suite está presente. Deshabilitado por defecto, habilitar vía settings.php.
hook_theme_suggestions_container
Agrega sugerencias de plantilla para elementos container basadas en tipo, contexto de view, envoltorio de archivo gestionado, estado de padre, grupo y clave de webform.
hook_theme_suggestions_form_alter
Agrega sugerencias de plantilla para formularios basadas en element ID, form ID y región. Soporta plantillas de formulario específicas de región cuando el atributo región está establecido.
hook_theme_suggestions_form_element
Agrega sugerencias de plantilla para elementos de formulario basadas en element ID, tipo e ID de webform.
hook_theme_suggestions_input
Agrega sugerencias de plantilla para elementos input basadas en element ID.
hook_theme_suggestions_user
Agrega sugerencias de plantilla para entidades de usuario basadas en user ID, view mode y rol más alto.
hook_theme_suggestions_html
Agrega sugerencias de plantilla para el envoltorio HTML basadas en el tipo de node actual.
hook_theme_suggestions_page
Agrega sugerencias de plantilla para plantillas de página basadas en el tipo de node actual.
hook_theme_suggestions_field
Agrega sugerencias de plantilla para fields basadas en view mode, tipo de entidad y combinaciones de bundle.
hook_theme_suggestions_field_alter
Agrega el tipo de destino de entity reference como sugerencia de plantilla de field.
hook_theme_suggestions_taxonomy_term
Agrega sugerencias de plantilla para términos de taxonomía basadas en view mode, bundle e ID del término.
hook_theme_suggestions_book_tree
Agrega sugerencias de plantilla para árboles de libros basadas en región.
hook_theme_suggestions_block_alter
Elimina sugerencias de plantilla duplicadas de los blocks para mantener las listas de sugerencias limpias.
hook_theme_suggestions_menu_alter
Agrega sugerencias de plantilla para menús basadas en región, soportando tanto menús específicos como todos los menús en una región.
hook_theme_suggestions_menu_local_action_alter
Agrega sugerencias de plantilla para acciones locales de menú basadas en el nombre de ruta del enlace, construyendo sugerencias progresivamente más específicas.
hook_preprocess
Agrega la variable base_path a todas las plantillas, permitiendo la construcción fácil de rutas de assets en Twig.
Troubleshooting 5
Asegúrate de que la depuración de Twig esté habilitada en /admin/config/development/settings. Limpia todos los caches con drush cr. Revisa el código fuente de la página (no el inspector del navegador) para ver los comentarios HTML que muestran las sugerencias disponibles.
Verifica que el nombre del archivo de plantilla coincida exactamente con la sugerencia (usa guiones bajos en el nombre del archivo, no guiones). Asegúrate de que la plantilla esté en el directorio templates de tu theme. Limpia los caches después de agregar nuevas plantillas.
Las sugerencias de región para blocks requieren que el block se coloque vía la interfaz de block layout (/admin/structure/block). Los blocks renderizados programáticamente pueden no tener información de región disponible.
La corrección de layout está deshabilitada por defecto. Habilítala en settings.php: $config['twigsuggest.settings']['alternate_ds_suggestions'] = TRUE; Ten en cuenta que esto puede no funcionar para todas las configuraciones de DS.
Twig Template Suggester establece su peso de módulo en 100 para asegurar que se ejecute de último. Si otro módulo tiene un peso mayor, sus sugerencias tendrán precedencia. Verifica los pesos de módulos en la tabla system.module.