Preprocesamiento y modificación de atributos en el archivo .theme

Como en Drupal 7, puedes influir en la salida de un HTML específico mediante funciones de preprocesamiento. Por ejemplo, si deseas añadir una clase a un menú y prefieres hacerlo a nivel PHP, puedes hacerlo. Esta es una buena manera de modificar el marcado relacionado con el tema, pero si quieres hacer un marcado independiente del tema, es mejor escribir un módulo propio.

(Nota: para fines de documentación aquí, "mytheme" es el nombre de máquina de tu tema; por ejemplo, "bartik" es el nombre de máquina del tema.)

Para trabajar con funciones de preprocesamiento:

1. Crea o edita un archivo en el directorio de tu tema llamado mytheme.theme

2. Crea una función como mytheme_preprocess_HOOK, donde HOOK hace referencia al elemento que deseas modificar*

3. Escribe tus cambios y guarda

4. Reconstruye la caché para que tus cambios estén disponibles (si tienes drush instalado, ejecuta drush cr en la línea de comandos)

* Los nombres de HOOK siguen las convenciones de las plantillas Twig. Para crear un hook para page.html.twig, creas la función mytheme_preprocess_page. Para un hook para node — article.html.twig, creas mytheme_preprocess_node__article (reemplazando las barras por guiones bajos). Para saber los nombres de hooks, consulta la sección "Buscar archivos de plantillas con depuración".

Supongamos que queremos añadir la clase my-menu a todos los menús de tu sitio. Asumiendo que tu tema se llama "mytheme", deberías escribir la siguiente función:

/**
* Implementa hook_preprocess_HOOK() para menu.html.twig.
*/
function mytheme_preprocess_menu(&$variables) {
  // Si no existe un arreglo de clases, crea uno vacío.
  if (!isset($variables['attributes']['class'])) {
    $variables['attributes']['class'] = [];
  }
  // Combina con cualquier clase que haya sido establecida por otras invocaciones de hook_preprocess_menu
  $variables['attributes']['class'] = array_merge($variables['attributes']['class'], ['my-menu']);
}

Esto es muy parecido a Drupal 7 y es útil si quieres personalizar un menú específico.

Puedes verificar el objeto $variables con una condición para determinar con qué menú estás trabajando. Los elementos dentro de $variables están disponibles en Twig después del preprocesamiento del tema.

Ahora, para ampliar nuestro ejemplo, supongamos que queremos añadir la clase "my-main-menu" al menú principal de tu sitio. Esta sería la función para ello:

/**
* Implementa hook_preprocess_HOOK() para menu.html.twig.
*/
function mytheme_preprocess_menu(&$variables) {
  if ($variables['menu_name'] == 'main') {
    if (!isset($variables['attributes']['class'])) {
      $variables['attributes']['class'] = [];
    }
    $variables['attributes']['class'] = array_merge($variables['attributes']['class'], ['my-main-menu']);
  }
}

Diferencias respecto a Drupal 7

Ya no existe el archivo template.php. Este archivo fue reemplazado por mytheme.theme. Sin embargo, sigue funcionando de manera muy similar, permitiendo que los hooks modifiquen la salida.

Otros enlaces útiles

• Búsqueda en la API de implementaciones de preprocesamiento en el núcleo.
• Documentación del API hook_preprocess_HOOK (versión 8.4.x)