Travailler avec des « templates suggestions »

Soumis par kolossaldrupal le mer, 15/04/2009 - 06:00
in
Date du document original en anglais : 26 Août 2009 – 03h05 - http://drupal.org/node/223440

Les « templates suggestions » sont des gabarits alternatifs basés sur des fichiers .tpl.php existants.

Ces « suggestions » sont utilisées quand une circonstance particulière est rencontrée et qu'il existe une correspondance de nom de fichier. Toutes les couches du core, des modules, des moteurs de thèmes et des thèmes peuvent fournir des suggestions. Vous pouvez les imaginer comme étant des conseils qui indiquent à l'application de choisir une présentation selon un contexte donné. Le concept est simple mais il s'agit d'une puissante fonctionnalité fournissant une autre couche de personnalisation.

Module Devel affichant une « template suggestion » pour possible "page" templates.

Une liste des toutes les suggestions pour le core peut être trouvée dans Core templates and suggestions.

Les noms de ces suggestions sont indiquées dans les fonctions de pré-traitement (preprocess functions). Il en existe de nombreuse fournies par le core. Si vous avez besoin de les enrichir davantage, ajoutez un pré-traitement pour le point d'entrée de thème dans votre fichier template.php. L'exemple suivant ajoute des suggestions dans le point d'entrée de thème page. Elles peuvent être ajoutées dans n'importe quel point d'entrée implémenté en tant que gabarit.

Le préfixe « drop » doit être remplacé par le nom de votre thème.

<?php
function drop_preprocess_page(&$variables) {
  global $user;
 
  // Add a single suggestion.
  if (module_invoke('throttle', 'status') && isset($user->roles[1])) {
    $variables['template_file'] = 'page-busy';
  }

  // Add multiple suggestions.
  if (!empty($user->roles)) {
    foreach ($user->roles as $role) {
      $filter = '![^abcdefghijklmnopqrstuvwxyz0-9-_]+!s';
      $string_clean = preg_replace($filter, '-', drupal_strtolower($role));
      $variables['template_files'][] =  'page-'. $string_clean;
    }
  }

}
?>

Il y a deux façons d'ajouter ces suggestions :

  1. La clé template_file accepte une seule proposition et elle a la priorité. Si la condition est remplie et que le fichier existe, elle sera utilisée et toutes les autres seront ignorées.
  2. La clé template_files (attention au pluriel) peut prendre un tableau de propositions. Elles sont traitées dans l'ordre FILO (premier entré dernier sorti). Dans un premier temps, l'ajout au tableau doit être fait à partir d'une condition générale, condition qui devient plus restrictive au fur et à mesure, l'enchainement se faisant sur ces particularités. Adding to the array should be done with a general condition first, progressively getting more specific so it cascades based on specificity.

Dans l'exemple ci-dessus, Drupal tentera d'utiliser une fichier nommé page-busy.tpl.php lorsque le seuil d'engorgement sera atteint pour les les utilisateurs anonymes (1 est habituellement affecté à l'identifiant des rôles anonymes). Les autres conditions informent Drupal de regarder les gabarits basés sur les rôles attribués à l'utilisateur courant, par exemple « page-authenticated-user.tpl.php ». Si aucun ne correspond, la gabarit de base page.tpl.php sera utilisé.

Ce sont des exemples simples. Vous pouvez paramétrer n'importe quel contexte basé sur les données dont vous disposez.

Quelques remarques :

  • Lorsque vous ajoutez à template_files, ajoutez au tableau. Ne le réinitialisez pas puisque les variables sont passées par référence. Toute suggestion paramétrée avant dans le core et les modules sera perdue.
    • <?php
          // Ne faites pas ceci :
          $variables['template_files'] = array('hook-suggestion');
     
          // Faites plutôt cela :
          $variables['template_files'][] = 'hook-suggestion';
    ?>
  • Préfixez la suggestion avec le nom du point d'entré à qui elle est associée. Ça reste clair et les fichiers apparaissent groupés. Cela réduit également le risque que Drupal référence le gabarit avec un point d'entrée différent.
  • Par souci de cohérence, utilisez des traits d'union au lieu de signes soulignés. Le gabarit principal ne devrait jamais utiliser de signes soulignés.
  • Les suggestions ne fonctionnent que si elles sont placées dans le même dossier que le gabarit de base. Les gabarits peuvent être placés dans n'importe quel sous-dossier du thème. Ils doivent être appairés dans le même emplacement.
  • Pour les suggestions, le registre de thèmes n'a pas besoin d'être vidé. Ce n'est que le gabarit de base qui a besoin d'être référencé. Les suggestions sont prises en compte à la volée.