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