Voilà, voilà... Fin de l'aventure...

 

Fermeture de kolossaldrupal.org dans...


Bonjour tout le monde,

Drupal évolue, les versions changent et Kolossaldrupal.org était essentiellement consacré à la version 6 de Drupal.

Autant dire que les infos présentées ici commencent à dater...

Faute de temps, je ne peux plus garder le site Kolossaldrupal à jour...

Je vous aurais bien proposé de reprendre le flambeau mais... c'est tellement simple de nos jours de se faire son propre site à soi...Pourquoi s'embêter alors ? :-)

Ce site restera donc en l'état, tel qu'il était en 2011...

Ah la la ! Cela ne nous rajeunit pas !

Manuel Vila - Avril 2016

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

Traduction de la page http://drupal.org/node/223430
publiée / actualisée le 17 Mai 2011 sur drupal.org


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. La tâche principale du pré-traitement est l'initialisation des 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 :

  • Les pré-traitements sont également utilisés pour fournir des template suggestions.
  • 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.
  • Avant Drupal 6.7, pour que votre thème reconnaisse ses fonctions de pré-traitements, le gabarit associé au hook devait exister dans le thème. S'il existe un gabarit par défaut, copiez-le dans votre thème et videz le cache (ou actualisez plutôt votre Drupal vers une version récente, ne serait-ce que pour des raisons de sécurité, et vous n'aurez plus à vous préoccuper de cette question).

Il peut y avoir de nombreux pré-traitements pour chaque point d'entrée du thème. Chaque couche du noyau, les modules, les moteurs et les thèmes peuventt avoir le leur propre, chacun renseignant les variables au fur et à mesure, avant qu'elles ne soient mises en forme dans les gabarits. On conserve un balisage propre et facile à maintenir si on place la majeure partie des traitements dans les pré-traitements.

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 des variables spécifiques au point d'entrée se fait généralement 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

DÉCONSEILLÉ - 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. S'applique à tous les hooks.

8. engineName_preprocess_hook

DÉCONSEILLÉ - 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 hooks.

10. themeName_preprocess_hook

Identique au pré-traitement précédent mais pour un hook en particulier.

Tout ceci offre de nombreuses possibilités pour l'initialisation des 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 :

  • Une malheureuse erreur de conception dans le système de thèmes 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.
  • Le nom du thème (9 et 10) devrait toujours être utilisé pour les 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é qui passe toujours le hook. 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';
}
}
?>

Dans Drupal 7, il existe deux jeux de fonctions de traitement de variables. Le premier est le jeu existant de fonctions de pré-traitement. Le deuxième rassemble les fonctions de traitement qui sont exécutées après les pré-traitements. Tous les préfixes et suffixes s'appliquent de la même façon à ce second jeu. C'est utile lorsque des variables doivent être travaillées en deux cycles. Par esemple, l'ajout de classes dans un tableau lors de la phase de « pré-traitement » puis leur mise à plat dans une chaîne de caractères lors de la phase de « traitement » afin qu'elle puisse être mise en forme dans une mise en page.

 

« Snippets » et « HowTo » connexes :