Initialisation des variables pour leur utilisation dans un gabarit (fonctions de pré-traitement)

Soumis par kolossaldrupal le mer, 15/04/2009 - 06:00
in
Date du document original en anglais : 27 Août 2009 - 02h36 - http://drupal.org/node/223430

Les fonctions de pré-traitement ne s'appliquent qu'aux points d'entrée (hook) des thèmes implémentés en tant que gabarits. Le rôle principal du pré-traitement est d'initialiser les variables qui seront utilisées dans les fichiers gabarits .tpl.php. Les fonctions de thèmes n'interagissent pas avec le pré-traitement.

Plain theme functions do not interact with preprocessors.

Remarques :

  • Pour que votre thème ait ses fonctions de pré-traitements reconnues, le gabarit associé au hook doit exister dans le thème. Depuis Drupal 6.7, ce n'est plus indispensable. Quand il existe un gabarit par défaut, copiez-le dans votre thème et videz le cache. Si vous convertissez une fonction de thème en gabarit, lisez la page hook to register as a template.
  • Dans les version 5 et antérieures de Drupal, la fonction _phptemplate_variables avait le même but. Elle est obsolète dans la version 6.

Il peut y avoir de nombreux pré-traitements pour chaque point d'entrée du thème. Chaque couche du core, des modules, des moteurs et des thèmes peut avoir le sien propre, chacun renseignant les variables avant qu'elles ne soient "restituées" dans les gabarits. En plaçant la plus grande partie de la logique de traitement dans ces pré-traitements, cela permet de conserver un balisage propre et facile à maintenir dans les gabarits, .

Voici la liste des pré-traitements. Quand ils existent, ils s'exécutent dans cet ordre :

1. template_preprocess

Fourni par le core et toujours ajouté. Les variables générées ici (variables generated here) sont utilisées par chaque point d'entrée du gabarit.

2. template_preprocess_hook

Le module ou le core qui implémente le point d'entrée fourni le template_preprocess_hook. La création de toutes les variables spécifiques au point d'entrée est généralement faite ici.

3. moduleName_preprocess

A ne pas confondre avec le pré-traitement précédent. Celui-ci permet aux modules, qui n'implémentent pas initialement de point d'entrée, d'agir sur les variables. S'applique à tous les points d'entrées.

4. moduleName_preprocess_hook

Même principe que le pré-traitement précédent mais restreint à des points d'entrées spécifiques.

5. engineName_engine_preprocess

Le pré-traitement des moteurs de thème. S'applique à tous les points d 'entrée.

6. engineName_engine_preprocess_hook

Autre pré-traitement pour moteurs de thèmes mais ne portant que sur un seul point d'entrée.

7. engineName_preprocess

NON RECOMMANDÉ - Premier pré-traitement pouvant être utilisé à l'intérieur du thème. Il peut être nommé d'après le nom du moteur qui fait tourner le thème.

8. engineName_preprocess_hook

NON RECOMMANDÉ - Autre pré-traitement nommé d'après le nom du moteur de thème mais propre à un seul point d'entrée.

9. themeName_preprocess

Ce pré-traitement est nommé d'après le nom du thème. S'applique à tous les points d'entrée.

10. themeName_preprocess_hook

Identique au pré-traitement précédent mais pour un point d'entrée en particulier.

Tout ceci vous offre de nombreuses possibilités pour initialiser les variables. Dans la plupart des cas, ce sont les deux premiers pré-traitements qui seront utilisés. Le premier déclarant les variables par défaut et le second ajoutant un paramétrage spécifique à un point d'entrée.

Les modules additionnels tirant partie des pré-traitement (3 et 4) devraient documenter leur comportement. Ce point ne sera pas développé ici.

Quand c'est possible, le PHPTemplate par défaut ne s'appelle pas dans cette liste (5 et 6)

While it is possible, the default PHPTemplate does not inject itself to this list. (5 & 6)

Les thèmes peuvent ajouter leurs pré-traitement en septième position dans la liste. Les fonctions de pré-traitement devraient êtres ajoutées aux fichiers template.php des thèmes. Cependant, étant donné les problèmes listés ci-après, il est conseillé que les thèmes utilisent leurs propres noms comme préfixe (9 et 10). Il est possible d'agrandir cette liste au-delà du dixième pré-traitement ci-dessus en ayant des sous-thèmes ajoutant des pré-traitements avec leurs propres noms de sous-thème comme indiqué dans les deux derniers exemples.

Quelques remarques :

  • Il y a une malheureuse erreur de conception dans le système de thèmes qui se manifeste lorsqu'un thème fait partie de la hiérarchie d'un thème ou d'un sous-thème. Toute fonction de pré-traitement préfixée avec engineName_preprocess sera exécutée plusieurs fois (au lieu d'une). Cela ne fait pas que gaspiller les ressources mais rend également difficile le déboguage. Il est conseillé que les thèmes-parents utilisent le nom du moteur (7 et 8) pour leurs pré-traitements. Cela facilite la migration de code entre thèmes et snippets sur Drupal.org.
  • Le nom du thème (9 et 10) devrait toujours être utilisé pour les sous-thèmes. Cela réduit les risques d'erreurs fatales dues aux duplications de fonctions, qui sont interdites en PHP.

Notez qu'aucune valeur ne devrait être retournée par ces fonctions et que les variables sont passées par référence, comme l'indique la perluète devant les noms de variables : &$variable.

Les variables initialisées dans les premiers pré-traitements sont utilisées par l'ensemble des pré-traitements suivants, puisque passées par référence. Faites attention de ne pas remettre à zéro les variables ajoutées avant votre thème. Il est possible de les réinitialiser mais si vous le faites accidentellement vous aurez bien évidemment du mal à trouver l'origine d'un mauvais comportement.

Exemple d'initialisation d'un module implémentant le point d'entrée « foo » :

<?php
function template_preprocess_foo(&$variables) {
  $variables['foo_list'] = array(
    'list item 1',
    'list item 2',
    'list item 3',
);
}
?>

Le pré-traitement créé à partir du thème pour ajouter une valeur à la variable créée précédemment :

<?php
function drop_preprocess_foo(&$variables) {
  // Ne pas faire ceci, à moins que vous ne sachiez pourquoi :
$variables['foo_list'] = array('list item 4');
  // Faites plutôt ceci :
  $variables['foo_list'][] = 'list item 4';
}
?>

Les variables que l'on retrouve dans le fichier gabarit sont les clés initialisées dans $variables. Dès lors, dans l'exemple précédent, la variable du gabarit sera retournée dans $foo_list.

Quand vous lancez un pré-traitement non spécifique à un point d'entrée de thème, un deuxième paramètre peut être utilisé pour passer le point d'entrée. Utiliser une fonction de pré-traitement plus spécialisée, comme celle de l'exemple ci-dessus, est plus facile à maintenir mais si le code doit être partagé entre plusieurs points d'entrée, vous préférerez peut-être ce qui suit :

<?php
function drop_preprocess(&$variables, $hook) {
  // Partagé entre les points d'entrée 'foo' et 'bar'
// Shared between the 'foo' and 'bar' theming hooks.
if ($hook == 'foo' || $hook == 'bar') {
    $variables['foobar_item'] = 'foobar item';
}
  // Specific to 'foo'. Propre à 'foo'
  if ($hook == 'foo') {
    $variables['foo_item'] = 'foo item';
}
  // Specific to 'bar'. Propre à 'bar'
  elseif ($hook == 'bar') {
    $variables['bar_items'] = 'bar item';
}
}
?>

 

« Snippets » et « HowTo » connexes :