Meilleures pratiques Twig - fonctions et templates de prétraitement

05/07/2025, by Ivan

Pour rendre la thématisation Drupal 8 aussi performante que possible et offrir plus de possibilités de personnalisation dans les templates Twig, suivez les recommandations suivantes :

Ce guide est conçu pour aider les développeurs Drupal ayant une expérience Drupal 7, qui cherchent à supprimer des fonctions comme theme() ou drupal_render(), qui ne doivent plus être utilisées dans Drupal 8+. Les exemples « avant » sont généralement écrits dans le style Drupal 7.

Retourner des tableaux de rendu depuis les fonctions de prétraitement

Retournez toujours des tableaux de rendu au lieu d’appeler theme() ou drupal_render() dans les fonctions de prétraitement.

Twig effectue le rendu automatiquement, il n’est donc pas nécessaire d’appeler drupal_render() ou theme() dans la fonction de prétraitement. Au lieu de cela, les tableaux de rendu doivent être passés au template, car cela offre bien plus de possibilités de personnalisation qu’une chaîne HTML déjà rendue.

Suppression de theme() dans la fonction de prétraitement :

// Avant - passage d’une chaîne HTML rendue au template.
$variables['table'] = theme('table', ['header' => $header, 'rows' => $rows]);

// Après - passage d’un tableau de rendu au template.
$variables['table'] = [
  '#theme' => 'table',
  '#header' => $header,
  '#rows' => $rows,
];

Suppression de drupal_render() dans la fonction de prétraitement – il suffit d’enlever l’appel :

// Avant, appel inutile à drupal_render().
$variables['teaser'] = drupal_render($node_teaser);

// Après, suppression de drupal_render().
$variables['teaser'] = $node_teaser;

Un cas fréquent est que drupal_render() était appelé lors de l’ajout à un tableau :

// Avant, appel inutile à drupal_render().
$row[] = drupal_render($display['title']);

// Après, suppression de drupal_render().
$row[]['data'] = $display['title'];

Filtres d’appel et fonctions utilitaires dans les templates

Bien que les tableaux de rendu offrent une structure adressable et modifiable pour les données jusqu’au template, toutes les variables ne nécessitent pas un tableau de rendu. Pour fournir des données brutes aux templates aussi tard que possible, les développeurs de thèmes doivent appeler des filtres, tels que t, et des fonctions utilitaires, comme url(), directement dans les templates Twig. Appeler ces fonctions dans le template Twig, plutôt que dans la fonction de prétraitement, peut réduire le nombre d’appels car certaines variables transmises au template ne sont parfois pas affichées.

Avant :

Dans la fonction de prétraitement :

$variables['no_content_text'] = t('You have not created any content types yet. Go to the <a href="@create-content">content type creation page</a> to add a new content type.', array('@create-content' => url('admin/structure/types/add')));

Dans le template :

<p>{{ no_content_text }}</p>

Après :

Dans le template :

<p>{{ 'You have not created any content types yet. Go to the <a href="@create-content">content type creation page</a> to add a new content type.'|t({'@create-content': url('admin/structure/types/add')}) }}</p>

Afficher / masquer et supprimer drupal_render_children et element_children

Si hide() était utilisé dans le template original et que drupal_render_children était utilisé pour rendre le « reste » des données, il faut séparer tout cela en variables distinctes durant le prétraitement.

Avant (fichier PHPTemplate) :

<?php
hide($form['advanced']);
hide($form['actions']);
?>
<div class="layout-node-form clearfix">
<div class="layout-region layout-region-node-main">
<?php print drupal_render_children($form); ?>
</div>
<div class="layout-region layout-region-node-secondary">
<?php print render($form['advanced']); ?>
</div>
<div class="layout-region layout-region-node-footer">
<?php print render($form['actions']); ?>
</div>
</div>

Utilisez le filtre Twig appelé without pour masquer certains éléments. Vous pouvez les afficher comme d’habitude, là où nécessaire.

Après (template Twig) :

<div class="layout-node-form clearfix">
  <div class="layout-region layout-region-node-main">
    {{ form|without('advanced', 'actions') }}
  </div>
  <div class="layout-region layout-region-node-secondary">
    {{ form.advanced }}
  </div>
  <div class="layout-region layout-region-node-footer">
    {{ form.actions }}
  </div>
</div>

Méthode alternative (plus nécessaire) :

Prétraitez tout dans des variables distinctes et transmettez-les au template. Vous devrez peut-être réaffecter des parties du contenu (dans ce cas, le formulaire) dans des variables séparées avant de rendre le reste. Imprimez le contenu exactement comme prévu dans le template.

Avant (prétraitement) :

function template_preprocess_node_edit_form(&$variables) {
  $form = $variables['form'];
  
  // @todo Update this once drupal.org/node/1920886 is resolved.
  $variables['advanced'] = $form['advanced'];
  $variables['actions'] = $form['actions'];
  unset($form['advanced'], $form['actions']);
  $variables['form'] = drupal_render_children($form);
}