Sesión 4: sobreescritura de plantillas Twig

Creación de temas personalizados en Drupal 10

En esta sesión, exploraremos cómo personalizar aún más el sitio mediante la sobreescritura de plantillas Twig específicas en Drupal. Aprenderemos a identificar las plantillas predeterminadas de Drupal y crear nuestras propias versiones para modificar la apariencia y disposición de contenido, como nodos, bloques y otros elementos, adaptándolos a las necesidades específicas del diseño.

Objetivo

El objetivo de esta sesión es aprender a identificar y sobreescribir plantillas Twig específicas de Drupal. Esto permitirá crear versiones personalizadas de los elementos visuales y de contenido del sitio, logrando una personalización avanzada del diseño y la estructura.

Contenido

1. Identificación de plantillas Twig en Drupal: Métodos para localizar las plantillas predeterminadas que podemos sobrescribir.
2. Creación de plantillas específicas para nodos y bloques: Cómo crear plantillas Twig personalizadas para tipos de contenido específicos.
3. Prácticas recomendadas para la sobreescritura de plantillas: Organización de archivos y nombres para facilitar el mantenimiento del tema.

Identificación de plantillas Twig en Drupal

Drupal permite sobrescribir plantillas de Twig para elementos específicos como nodos, bloques, menús y vistas. Los nombres de las plantillas siguen una convención que facilita su localización. A continuación, veremos algunos métodos para identificar las plantillas que puedes sobrescribir.

1. Modo de depuración de Twig:
   • Drupal cuenta con un modo de depuración para Twig que ayuda a identificar qué plantilla Twig se está utilizando para renderizar una sección específica del sitio. Para activar el modo de depuración, debes editar el archivo services.yml de tu sitio:
     • Ve a sites/default/services.yml y busca el valor twig.config.
     • Configura debug a true, de esta manera:
       parameters: twig.config: debug: true
   • Una vez activada, recarga la página y revisa el código fuente. Verás comentarios que indican qué plantillas Twig se están utilizando y sus ubicaciones.
2. Uso de drush para listar plantillas:
   • Si tienes drush instalado, puedes ejecutar drush theme:list para ver una lista de temas activos y sus respectivas plantillas.

Sobreescritura de plantillas específicas

Una vez identificada la plantilla que quieres sobrescribir, puedes copiarla en la carpeta templates de tu tema personalizado y modificarla según tus necesidades.

Sobrescritura de plantillas para nodos

Los nodos en Drupal representan tipos de contenido, y cada tipo de contenido puede tener una plantilla específica.

Ubicación de la plantilla:

• La plantilla Twig general para los nodos es node.html.twig, que controla el HTML de cualquier tipo de contenido en Drupal.
• Para sobrescribir la plantilla de un tipo de contenido específico, sigue la nomenclatura node--[nombre_tipo].html.twig. Por ejemplo, si tienes un tipo de contenido llamado «artículo», crearás una plantilla llamada node--article.html.twig.

Creación de la plantilla de nodo personalizada:

En la carpeta templates de tu tema, crea el archivo node--article.html.twig.

Personaliza el HTML dentro de esta plantilla para cambiar la apariencia del contenido del tipo «artículo».

<article class="mi-articulo">
  <h2>{{ label }}</h2>
  <div class="contenido">
    {{ content.body }}
  </div>
  <footer>
    <p>Publicado por {{ node.uid.entity.name.value }} el {{ node.created|date("d/m/Y") }}</p>
  </footer>
</article>

En este ejemplo:

• {{ label }} representa el título del nodo.
• {{ content.body }} muestra el cuerpo del nodo.
• {{ node.uid.entity.name.value }} obtiene el nombre del autor.
• {{ node.created|date("d/m/Y") }} muestra la fecha de creación en un formato específico.

Limpieza de caché:

Después de crear o modificar una plantilla, es importante limpiar la caché para ver los cambios en el sitio. Usa el comando:

drush cache:rebuild

Sobrescritura de plantillas para bloques

Los bloques en Drupal también tienen plantillas que se pueden sobrescribir para personalizar su diseño.

Ubicación de la plantilla de bloque:

• La plantilla general para los bloques es block.html.twig.
• Para sobrescribir un bloque específico, puedes usar la convención block--[id_bloque].html.twig. Por ejemplo, si tienes un bloque con ID header, crearás block--header.html.twig.

Creación de la plantilla de bloque personalizada:

En la carpeta templates de tu tema, crea el archivo block--header.html.twig.

Personaliza el contenido de la plantilla para controlar cómo se renderiza este bloque en particular.

<div class="mi-bloque-header">
  <h2>{{ configuration.label }}</h2>
  <div class="contenido-bloque">
    {{ content }}
  </div>
</div>

En este ejemplo:

• {{ configuration.label }} muestra el título del bloque.
• {{ content }} representa el contenido del bloque.

Limpieza de caché:

Limpia la caché con drush cache:rebuild para aplicar los cambios realizados en la plantilla.

Prácticas recomendadas para la sobreescritura de plantillas

1. Organización de la carpeta templates:
   • Crea subcarpetas dentro de templates para organizar las plantillas, como node, block, o page, según el tipo de contenido.
2. Documentación de cambios:
   • Añade comentarios en cada plantilla para documentar qué elementos has personalizado y por qué, facilitando el mantenimiento futuro.
3. Pruebas y depuración:
   • Al modificar una plantilla, revisa el diseño en diferentes dispositivos y contextos para asegurar que los cambios no afecten la usabilidad.

Tareas

Para completar esta sesión:

1. Identificar y sobrescribir una plantilla de nodo:
   • Elige un tipo de contenido y sobrescribe su plantilla creando un archivo node--[nombre_tipo].html.twig. Realiza personalizaciones en el diseño y el contenido del nodo.
2. Sobrescribir una plantilla de bloque:
   • Elige un bloque específico y crea una plantilla block--[id_bloque].html.twig para personalizar su apariencia.
3. Limpiar caché y probar en el navegador:
   • Limpia la caché de Drupal con drush cache:rebuild y verifica los cambios en el sitio para asegurarte de que las plantillas se han aplicado correctamente.

Al finalizar esta sesión, tendrás una comprensión sólida de cómo sobrescribir plantillas Twig en Drupal y aplicar personalizaciones específicas para cada tipo de contenido. Estas habilidades te permitirán adaptar el diseño del sitio con precisión y mejorar la experiencia del usuario.