6.6. Trabajo con plantillas en Drupal. Qué son las plantillas en el núcleo de Drupal.
Ya hemos visto que en Drupal tenemos Twig incorporado y cómo utilizarlo. En este artículo, hablaremos sobre cómo trabajar con plantillas en Drupal, qué plantillas existen en el tema Stable, cómo sobrescribir las plantillas de Stable y cómo redefinir las plantillas de varias entidades de Drupal.
Comencemos con las plantillas del tema Stable, ve a la carpeta templates del tema Stable:
Las plantillas se dividen por funcionalidad:
/core/themes/stable/templates/admin – plantillas para la interfaz de Views, páginas y elementos administrativos, mensajes e informes.
/core/themes/stable/templates/block – plantillas de bloques.
/core/themes/stable/templates/content – plantillas para nodos, comentarios, términos de taxonomía, elementos RSS, resultados de búsqueda.
/core/themes/stable/templates/content-edit – plantillas para filtros y formularios de edición.
/core/themes/stable/templates/dataset – plantillas para foros, canales RSS, tablas y listas ul.
/core/themes/stable/templates/field – plantillas de campos de distintos tipos.
/core/themes/stable/templates/form – plantillas de elementos de formulario.
/core/themes/stable/templates/layout – plantillas de estructura como page.html.twig, regiones, y html.html.twig.
/core/themes/stable/templates/misc – plantillas para íconos RSS, marcado RDF, mensajes de Drupal, barra de progreso.
/core/themes/stable/templates/navigation – plantillas para menús, libros, paginación, barra de herramientas, pestañas verticales, rutas de navegación (breadcrumbs).
/core/themes/stable/templates/user – plantillas para la página de usuario, nombre de usuario, firma del autor en foros.
/core/themes/stable/templates/views – plantillas de elementos del módulo Views.
Como puedes ver, el tema Stable ofrece una gran cantidad de plantillas. Para sobrescribir una plantilla, solo necesitas copiar la plantilla al subtema y modificarla allí. No es necesario copiar todas, solo las que necesites.
Sobrescribir plantillas para contenido (template suggestions)
Además de sobrescribir plantillas existentes, también puedes definir plantillas específicas para nodos, términos, bloques, etc. Algunos ejemplos:
Plantilla HTML
Plantilla principal: html.html.twig
Ubicación base: core/modules/system/templates/html.html.twig
Opciones de sobrescritura:
- html--internalviewpath.html.twig
- html--node--id.html.twig
- html.html.twig
Plantilla de Página
Opciones: page--[front|ruta/interna].html.twig
Plantilla base: page.html.twig (core/modules/system/templates)
Ejemplo: page--node--1.html.twig, page--node--edit.html.twig, etc.
Regiones
Opciones: region--[nombre-region].html.twig
Plantilla base: region.html.twig
Bloques
Opciones: block--[modulo|--delta].html.twig
Plantilla base: block.html.twig
Ejemplo: block--views-block--front-news-block-1.html.twig
Nodos
Opciones: node--[tipo|nid]--[viewmode].html.twig
Plantilla base: node.html.twig
Ejemplo: node--article--teaser.html.twig, node--1.html.twig
Términos de taxonomía
Opciones: taxonomy-term--[vocabulario|tid].html.twig
Plantilla base: taxonomy-term.html.twig
Campos
Opciones: field--[tipo|nombre--tipo-de-contenido].html.twig
Plantilla base: field.html.twig
Ejemplo: field--field-tags--article.html.twig
Comentarios
Opciones: comment--node-[tipo].html.twig
Plantilla base: comment.html.twig
También puedes definir un envoltorio de comentarios:
comment-wrapper--node-[tipo].html.twig
Views
Plantillas: views-view.html.twig, views-view-unformatted.html.twig, views-view-fields.html.twig
Ejemplos:
views-view--foobar--page.html.twig
views-view-unformatted--foobar--page.html.twig
views-view-fields--foobar--page.html.twig
Foro
Opciones: forums--[container|topic]--id.html.twig
Plantilla base: forums.html.twig
Modo de mantenimiento
Opciones: maintenance-page--[offline].html.twig
Plantilla base: maintenance-page.html.twig
Resultados de búsqueda
Opciones: search-result--[tipoBusqueda].html.twig
Plantilla base: search-result.html.twig
Ejemplos:
search-result--node.html.twig
search-result--user.html.twig
<h3>Cómo funcionan las sugerencias de plantillas en Drupal</h3>
<p>Drupal genera automáticamente sugerencias de plantillas basadas en el tipo de entidad, ID, modo de vista y otros factores. Estas sugerencias siguen un orden de prioridad, desde la más específica a la más genérica. Por ejemplo, para un nodo con ID 10 del tipo "article" en modo "teaser", Drupal buscará las siguientes plantillas en este orden:</p>
<ol>
<li>node--10--teaser.html.twig</li>
<li>node--10.html.twig</li>
<li>node--article--teaser.html.twig</li>
<li>node--article.html.twig</li>
<li>node--teaser.html.twig</li>
<li>node.html.twig</li>
</ol>
<p>Este sistema permite una personalización granular sin necesidad de duplicar lógica innecesaria. Puedes utilizar <code>kint()</code> o <code>dump()</code> en modo de desarrollo (con el módulo <strong>Devel</strong>) para inspeccionar las sugerencias disponibles para una plantilla específica.</p>
<h3>Consejos para trabajar con plantillas Twig</h3>
<ul>
<li>Recuerda limpiar la caché después de modificar o agregar una plantilla Twig: <code>drush cr</code> o desde <em>/admin/config/development/performance</em>.</li>
<li>Para facilitar la depuración, habilita el modo de depuración de Twig en el archivo <code>services.yml</code> del entorno de desarrollo.</li>
<li>Usa la consola de tu IDE para navegar rápidamente entre archivos .twig y aprovechar resaltado de sintaxis y autocompletado.</li>
</ul>
<h3>Cómo registrar tus plantillas personalizadas correctamente</h3>
<p>Coloca las plantillas personalizadas en la carpeta <code>/templates</code> dentro de tu subtema. Drupal buscará automáticamente en esta ubicación si el subtema está habilitado y activo.</p>
<p>Ejemplo de estructura de tema:</p>
<pre>
mi_tema/
│
├── templates/
│ ├── node--article.html.twig
│ ├── page--front.html.twig
│ ├── block--views-block--front-news-block-1.html.twig
│ └── region--sidebar-first.html.twig
├── mi_tema.info.yml
└── mi_tema.libraries.yml
</pre>
<p>Con esta estructura clara, puedes gestionar fácilmente las personalizaciones visuales de tu sitio Drupal sin tocar el núcleo ni los módulos contribuidos.</p>
<p>En el próximo artículo aprenderás cómo crear tus propios bloques personalizados en código, cómo exponer configuraciones de bloques en el UI, y cómo aplicar estilos específicos a regiones usando plantillas y clases CSS.</p>