Twig : créer des suggestions de nom de template

Nous allons utiliser cette fonction pour générer de nouvelles suggestions de nom de template pour les termes de taxonomie : par exemple, des suggestions qui prendraient en compte le "view mode" avec ou sans le nom du vocabulaire ou encore l'ID du terme.

Pour ce faire, nous allons utiliser la fonction dans notre thème "montheme" dans le fichier montheme.theme.

/**
 * Implements hook_theme_suggestions_HOOK_alter().
 */
function montheme_theme_suggestions_taxonomy_term_alter(array &$suggestions, array $variables) {
  $term = $variables['elements']['#taxonomy_term'];
  $sanitized_view_mode = strtr($variables['elements']['#view_mode'], '.', '_');
  // Add view mode theme suggestions.
  $suggestions[] = 'taxonomy_term__' . $sanitized_view_mode;
  $suggestions[] = 'taxonomy_term__' . $term->bundle() . '__' . $sanitized_view_mode;
  $suggestions[] = 'taxonomy_term__' . $term->id() . '__' . $sanitized_view_mode;
}

Nous venons de créer trois nouvelles suggestions de nom de template pour les termes de taxonomie.

Par exemple, avec un "view mode" full, pour un terme du vocabulaire "Tags", dont l'ID du terme est "12" :

1. taxonomy_term__full
2. taxonomy_term__tags__full
3. taxonomy_term__12__full

Nous aurons donc la possibilité de créer trois templates supplémentaires :

1. taxonomy-term--full.html.twig
2. taxonomy-term--tags--full.html.twig
3. taxonomy-term--12--full.html.twig

À l'origine, il y a une fonction : hook_theme_suggestions_HOOK().

Pour revenir à nos suggestions pour les termes de taxonomie, nous allons trouver cette fonction dans le fichier taxonomy.module présent dans le module du core de Drupal "Taxonony" (/core/modules/taxonomy) :

/**
 * Implements hook_theme_suggestions_HOOK().
 */
function taxonomy_theme_suggestions_taxonomy_term(array $variables) {
  $suggestions = [];

  /** @var \Drupal\taxonomy\TermInterface $term */
  $term = $variables['elements']['#taxonomy_term'];

  $suggestions[] = 'taxonomy_term__' . $term->bundle();
  $suggestions[] = 'taxonomy_term__' . $term->id();

  return $suggestions;
}

Par défaut, le module "Taxonomy" nous propose deux suggestions de nom de template.

Si nous revenons à notre exemple pour un terme du vocabulaire "Tags", dont l'ID du terme est "12" :

1. taxonomy_term__tags
2. taxonomy_term__12

Nous aurons donc la possibilité de créer deux templates :

1. taxonomy-term--tags.html.twig
2. taxonomy-term--12.html.twig

La fonction hook_theme_suggestions_HOOK_alter() vient compléter / altérer la fonction hook_theme_suggestions_HOOK().

Au final, nous aurons donc 5 suggestions de nom de template : les deux proposées par défaut et les trois que nous avons ajoutés dans notre thème.

1. taxonomy_term__tags
2. taxonomy_term__12
3. taxonomy_term__full
4. taxonomy_term__tags__full
5. taxonomy_term__12__full

À partir de ce principe, nous allons pouvoir ajouter des suggestions pour chaque élément possédant déjà un template twig.

Par exemple, il m'arrive souvent de devoir créer des suggestions pour les formulaires présents sur le site en "front" (connexion, création de compte utilisateur, formulaire de contact, etc...).

/**
 * Implements hook_theme_suggestions_HOOK_alter().
 */
function montheme_theme_suggestions_form_alter(array &$suggestions, array $variables) {
  if (!empty($variables['element']['#id'])) {
    $suggestions[] = 'form__' . str_replace('-', '_', $variables['element']['#id']);
  }
}

Ici, je rajoute une nouvelle suggestion basée sur l'ID du formulaire :

1. form__FORM_ID

Pour un projet utilisant le module "Domain", j'ai été confronté à la problématique d'avoir des templates de régions de blocs différents selon le domaine utilisé .

J'ai pu répondre à cette demande en utilisant la suggestion de nom de template.

Voilà ce que cela donne :

/**
 * Implements hook_theme_suggestions_HOOK_alter().
 */
function montheme_theme_suggestions_region_alter(array &$suggestions, array $variables, $hook) {
  // Domain
  $loader = \Drupal::service('domain.negotiator');
  $current_domain_id = $loader->getActiveDomain()->id();

  if (!empty($variables['elements']['#region']) && isset($current_domain_id)) {
    $suggestions[] = 'region__' . $variables['elements']['#region'] . '__' . $current_domain_id;
  }
}

Ici, je rajoute une nouvelle suggestion basée sur l'ID du domaine courant :

1. region__DOMAIN_ID

Face aux problématiques soulevées lors du développement d'un thème, il est important de pouvoir décliner les templates proposés par défaut.

L'ajout de suggestions de nom de template se révèle être un outil puissant et facile à implanter.