Convenciones de nombres de plantillas Twig
Drupal carga las plantillas basándose en ciertas convenciones de nombres. Esto te permite sobrescribir plantillas añadiéndolas a tu tema y asignándoles nombres específicos.
Después de agregar una plantilla, debes reconstruir la caché para que Drupal detecte tu nueva plantilla.
Puedes depurar plantillas Twig para averiguar qué plantillas se usan para generar el marcado de cualquier elemento dado. Más información sobre depuración Twig aquí.
En esta página se enumeran las convenciones usadas para la estructura básica de HTML, página, regiones, bloques, nodos, campos y otros componentes principales. (Es útil saber que puedes crear tus propias sugerencias de nombres de plantillas usando la función hook_theme_suggestions_HOOK_alter.)
HTML (plantilla <head>)
La plantilla HTML proporciona el marcado para la estructura básica de la página HTML, incluyendo las etiquetas <head>, <title> y <body>.
Plantilla base: html.html.twig (ubicación base: core/modules/system/templates/html.html.twig)
A continuación algunos ejemplos de cómo puedes sobrescribir la plantilla base:
- html--[internalviewpath].html.twig
- html--node--[nodeid].html.twig
- html.html.twig
Consulta la documentación API html.html.twig.
Plantilla Page
Plantilla: page--[front|internal/path].html.twig
Plantilla base: page.html.twig (ubicación base: core/modules/system/templates/page.html.twig)
Las sugerencias son numerosas. La página principal tiene prioridad. El resto se basa en la ruta interna de la página actual. En la página principal se puede configurar en Administración > Configuración > Sistema > Información del sitio. (http://example.com/admin/config/system/site-information). La plantilla de la página principal es page--front.html.twig.
No confundas la ruta interna con alias de ruta, que no se consideran.
La lista de sugerencias de plantillas está ordenada por especificidad según la ruta interna. Se genera una sugerencia para cada elemento de la ruta actual, aunque los elementos numéricos no se propagan a las sugerencias siguientes. Por ejemplo, «http://www.example.com/node/1/edit» genera las siguientes sugerencias:
- page--node--edit.html.twig
- page--node--1.html.twig
- page--node.html.twig
- page.html.twig
Consulta la documentación API page.html.twig. También consulta más abajo la plantilla de página de mantenimiento.
Regions
Plantilla: region--[region].html.twig
Plantilla base: region.html.twig (ubicación base: core/modules/system/templates/region.html.twig)
La plantilla de región se usa cuando una región de la página tiene contenido, ya sea del sistema de bloques o funciones como hook_page_top() o hook_page_bottom(). Los nombres posibles de regiones se definen en el archivo de tema .info.yml.
Consulta la documentación API region.html.twig.
Blocks
Plantilla: block--[module]--[delta].html.twig
Plantilla base: block.html.twig (ubicación base: core/modules/block/templates/block.html.twig)
- block--[module]--[delta].html.twig
- block--[module].html.twig
- block.html.twig
“module” es el nombre del módulo y “delta” es un identificador interno asignado al bloque por el módulo.
Por ejemplo, block--block--1.html.twig se usará para el primer bloque creado por el usuario y agregado en la pantalla de administración de bloques, ya que fue creado por el módulo de bloque con id 1. Las plantillas específicas de bloque por región no están disponibles en Drupal 8.
Si tienes un bloque creado por un módulo personalizado llamado “custom” y delta “my-block”, la sugerencia para el hook de tema sería block--custom--my-block.html.twig.
Otro ejemplo con Views: si tienes un bloque creado con Views llamado "front_news" y un identificador de visualización "block_1", la sugerencia para el hook de tema será block--views-block--front-news-block-1.html.twig (nota que cuando tienes guiones bajos en el id de visualización o en el nombre de la vista, debes convertirlos en guiones).
Recuerda que en este contexto los nombres de módulos distinguen mayúsculas y minúsculas. Por ejemplo, si tu módulo se llama “MyModule”, la sugerencia general para el hook de tema será block--MyModule.html.twig.
Consulta la documentación API block.html.twig.
Nodes
Plantilla: node--[content-type|nodeid]--[viewmode].html.twig
Plantilla base: node.html.twig (ubicación base: core/modules/node/templates/node.html.twig)
Las sugerencias de hook de tema se hacen basándose en estos factores, enumerados de la plantilla más específica a la menos específica. Drupal usará la plantilla más específica que encuentre:
- node--[nodeid]--[viewmode].html.twig
- node--[nodeid].html.twig
- node--[content-type]--[viewmode].html.twig
- node--[content-type].html.twig
- node--[viewmode].html.twig
- node.html.twig
Ten en cuenta que los guiones bajos (_) en el nombre del tipo de contenido se reemplazan por guiones (-).
Consulta la documentación API node.html.twig.
Taxonomy terms
Plantilla: taxonomy-term--[vocabulary-machine-name|tid].html.twig
Plantilla base: taxonomy-term.html.twig (ubicación base: core/modules/taxonomy/templates/taxonomy-term.html.twig)
Las sugerencias de hook de tema se hacen basándose en estos factores, enumerados de la plantilla más específica a la menos específica. Drupal usará la plantilla más específica que encuentre:
- taxonomy-term--[tid].html.twig
- taxonomy-term--[vocabulary-machine-name].html.twig
- taxonomy-term.html.twig
Ten en cuenta que los guiones bajos en el nombre máquina del vocabulario se reemplazan por guiones.
Consulta la documentación API taxonomy-term.html.twig.
Fields
Plantilla: field--[[type|name]|[entity-type]--[field-name|content-type]].html.twig
Plantilla base: field.html.twig (ubicación base: core/modules/system/templates/field.html.twig)
Las sugerencias de hook de tema se hacen basándose en estos factores, enumerados de la plantilla más específica a la menos específica. Drupal usará la plantilla más específica que encuentre:
- field--node--[field-name]--[content-type].html.twig
- field--node--[field-name].html.twig
- field--node--[content-type].html.twig
- field--[field-name].html.twig
- field--[field-type].html.twig
- field.html.twig
Ten en cuenta que los guiones bajos (_) en el nombre máquina del campo se reemplazan por guiones (-). También recuerda incluir "field-" en los nombres de campos personalizados, por ejemplo: field--field-phone.html.twig.
Consulta la documentación API field.html.twig.
Comments
Plantilla: comment--[comment-field-name]--[node-type].html.twig
Plantilla base: comment.html.twig (ubicación base: core/modules/comment/templates/comment.html.twig)
Se añadió soporte para crear archivos comment--[comment-field-name]--[node-type].html.twig para formatear comentarios de un tipo de nodo específico diferente a otros comentarios en el sitio. Por ejemplo, un comentario hecho en un nodo del tipo artículo será comment--field-comments--article.html.twig.
Consulta la documentación API comment.html.twig.
Envoltorios de comentarios
Plantilla: field--node--[comment-field-name]--[content-type].html.twig
Plantilla base: field--comment.html.twig
Forums
Plantilla: forums--[[container|topic]--forumID].html.twig
Plantilla base: forums.html.twig (ubicación base: core/modules/forum/templates/forums.html.twig)
Las sugerencias de hook de tema se hacen basándose en estos factores, enumerados de la plantilla más específica a la menos específica. Drupal usará la plantilla más específica que encuentre:
Para contenedores de foros:
- forums--containers--[forumid].html.twig
- forums--[forumid].html.twig
- forums--containers.html.twig
- forums.html.twig
Para temas de foros:
- forums--topics--[forumid].html.twig
- forums--[forumid].html.twig
- forums--topics.html.twig
- forums.html.twig
Consulta la documentación API forums.html.twig.
Página de mantenimiento
Plantilla: maintenance-page--[offline].html.twig
Plantilla base: maintenance-page.html.twig (ubicación base: core/modules/system/templates/maintenance-page.html.twig)
Esto aplica cuando la base de datos falla. Útil para mostrar una página amigable sin mensajes de error. La plantilla de página de mantenimiento debe configurarse correctamente primero.
Consulta la documentación de la API maintenance-page.html.twig.
Ten en cuenta que el archivo maintenance-page--offline.html.twig actualmente no se muestra cuando la base de datos no está disponible. Problema rastreado: #2720109: maintenance-page-offline.html.twig no se detecta cuando el sistema está en modo fuera de línea.
Resultado de búsqueda
Plantilla: search-result--[search-type].html.twig
Plantilla base: search-result.html.twig (ubicación base: core/modules/search/templates/search-result.html.twig)
search-result.html.twig es el contenedor por defecto para resultados de búsqueda individuales. Según el tipo de búsqueda, se sugieren diferentes plantillas. Por ejemplo, «example.com/search/node/Search+Term» usará «search-result--node.html.twig». Compara esto con «example.com/search/user/bob», que usará «search-result--user.html.twig». Los módulos pueden extender tipos de búsqueda agregando más sugerencias para sus tipos.
Consulta la documentación API search-result.html.twig.
Views
Todas las plantillas de Views pueden ser sobrescritas con diferentes nombres utilizando la vista, el id de visualización de la vista, el tipo de visualización o una combinación de estos.
Para cada vista se usan al menos dos plantillas. La primera se usa para todas las vistas: views-view.html.twig.
La segunda plantilla se determina por el estilo elegido para la vista. Ten en cuenta que ciertos aspectos de la vista también pueden cambiar el estilo usado; por ejemplo, argumentos que proporcionan vistas resumen pueden cambiar el estilo a uno de los estilos especiales de resumen.
El estilo por defecto para todas las vistas es views-view-unformatted.html.twig.
Muchos estilos luego renderizan cada fila usando un estilo de fila; el estilo de fila por defecto es views-view-fields.html.twig.
Plantillas:
- views-view--[viewid]--[view-display-id].html.twig
- views-view--[viewid]--[view-display-type].html.twig
- views-view--[view-display-type].html.twig
- views-view--[viewid].html.twig
- views-view.html.twig
Plantilla base: views-view.html.twig (ubicación base: core/themes/stable/templates/views/views-view.html.twig)
Por ejemplo, si queremos sobrescribir la plantilla "views-view.html.twig" para nuestra vista, los siguientes nombres de plantilla son válidos:
- views-view--[viewid]--[view-display-id].html.twig
- views-view--[viewid]--page.html.twig
- views-view--block.html.twig
- views-view--[viewid].html.twig
- views-view.html.twig
Las plantillas basadas en views-view-field.html.twig tienen un sufijo con el id del campo de la vista (como en plantillas de reemplazo) para renderizar un solo campo en la vista:
- views-view-field--[viewid]--[view-display-id]--[fieldid].html.twig
- views-view-field--[viewid]--page--[fieldid].html.twig
- views-view-field--block--[fieldid].html.twig
Drupal’s online documentation is © 2000-2020 by the individual contributors and can be used in accordance with the Creative Commons License, Attribution-ShareAlike 2.0. PHP code is distributed under the GNU General Public License.