Trabajo con plantillas Twig

Drupal te permite sobrescribir todas las plantillas que se usan para generar el marcado HTML, para que tengas control total sobre el marcado que se muestra como salida en tu tema personalizado. Hay plantillas para cada elemento de la página, desde el HTML de alto nivel hasta campos pequeños.

Sobrescribir plantillas

Puedes sobrescribir las plantillas principales de Drupal agregando plantillas en la carpeta de tu tema, siguiendo una convención específica de nombres.

Para sobrescribir plantillas necesitas:

1. Encontrar la plantilla que quieres sobrescribir.
2. Copiar el archivo de plantilla desde su ubicación base a la carpeta de tu tema.
3. (Opcional) Renombrar la plantilla según las convenciones de nombres para apuntar a subconjuntos más específicos donde se use la plantilla.
4. Modificar la plantilla a tu gusto.

Una vez que copies el archivo de plantilla en tu tema y limpies la caché, Drupal empezará a usar tu copia del archivo en lugar de la versión base.

Puedes descubrir qué plantillas se usan para cualquier parte de la página usando herramientas de depuración Twig.

Sugerencias de hooks de tema

A veces quieres modificar un archivo de plantilla, pero solo para algunos lugares donde se usa. Un ejemplo típico es modificar el archivo de plantilla de nodo solo para nodos de un tipo específico. La capa de tema de Drupal te permite apuntar a casos específicos de uso de un archivo de plantilla siguiendo una convención de nombres. Por ejemplo, al renderizar un nodo tipo artículo, Drupal primero busca el archivo node--article.html.twig y lo usa si existe. Si no, usa la plantilla estándar node.html.twig. El proceso por el que Drupal determina qué nombres posibles puede usar un archivo de plantilla se llama sugerencias de tema.

Las sugerencias de hooks de tema te permiten implementar sobrescrituras específicas en tu tema para archivos de plantilla con una convención de nombres específica.

Todos los niveles del núcleo, módulos, motores de tema y temas pueden proveer sugerencias. Puedes agregar o modificar sugerencias usando hooks:

• hook_theme_suggestions_HOOK(array $variables)
• hook_theme_suggestions_alter(array &$suggestions, array $variables, $hook)
• hook_theme_suggestions_HOOK_alter(array &$suggestions, array $variables)

Limpiar caché

Cuando trabajes con sugerencias de tema, existe la posibilidad de que Drupal use su caché y no las nuevas plantillas que has propuesto. Limpia la caché si tienes este problema. Para limpiar la caché, usa uno de los métodos descritos en la sección de limpieza de caché de Drupal.

Información de fondo

Puedes pensar en las sugerencias como pistas de nombres que indican al sistema qué elegir según las circunstancias adecuadas.

Las sugerencias de plantillas se establecen mediante hooks para sugerencias de tema, que pueden modificarse. Estos hooks permiten a cualquier módulo o tema proveer funciones de tema alternativas o sugerencias de nombres de plantilla, y reordenar o eliminar sugerencias proporcionadas por hook_theme_suggestions_HOOK() o llamadas anteriores a estos hooks.

Cómo Drupal determina las sugerencias de tema para la página según la ruta

Aquí hay una explicación basada en la función theme_get_suggestions():

La lista de posibles plantillas para una página dada la genera Drupal usando la función theme_get_suggestions(), llamada por la función system_theme_suggestions_page().

La ruta de la página en Drupal se divide primero en sus componentes. Como se mencionó, la ruta de Drupal no es ninguno de sus alias: para una página hay una y solo una ruta de Drupal. Para los ejemplos "http://www.example.com/node/1/edit" y "http://www.example.com/mysitename?q=node/1/edit", la ruta de Drupal es node/1/edit, y sus componentes son "node", 1 y "edit".

Luego se establece el prefijo "page". Para cada componente se aplica la siguiente lógica:

1. Si el componente es un número, añade el prefijo más "__%" a la lista de sugerencias.
2. Independientemente de si el componente es un número o no, añade el prefijo más "__" más el componente a la lista.
3. Si el componente no es un número, añade "__" más el componente al prefijo.

Después de iterar los componentes, si la página es la página principal (como está configurado en "Administración > Configuración > Sistema > Información del sitio."), se añade "page__front" a la lista de sugerencias.

Nota que para convertir la sugerencia en un nombre de archivo real, "__" se convierte en "--" y se añade ".html.twig". Así que para node/1/edit obtenemos esta lista de sugerencias:

1. page.html.twig (siempre sugerida)
2. page--node.html.twig (prefijo: page__node)
3. page--node--%.html.twig
4. page--node--1.html.twig (prefijo no cambia porque el componente es numérico)
5. page--node--edit.html.twig (prefijo: page__node__edit)
6. page--front.html.twig (solo si node/1/edit es la página principal)

Cuando la página se renderiza, se prueba la última sugerencia primero. Si existe, se usa. Si no, se prueba la siguiente y así sucesivamente. Por supuesto, si ninguna sugerencia existe, page.html.twig es la última opción. Esto también explica por qué page--front.html.twig, si existe, sobrescribe cualquier otra sugerencia para la página principal: siempre es la última sugerencia para la página marcada como principal.

Diferencias con Drupal 7

Antes, para cambiar sugerencias de plantilla, modificabas $variables['theme_hook_suggestions'] y $variables['theme_hook_suggestions'] en funciones preprocess para introducir sugerencias. En Drupal 8, módulos y temas ahora definen y alteran sugerencias de tema en sus propios hooks especializados.

Más información

Ver la entrada Nuevos hooks para sugerencias de tema