Guide du débutant pour surcharger les affichages personnalisables

Référence en anglais sur drupal.org : 18 Novembre 2009 - 13h52 - http://drupal.org/node/457740

Lors du paramétrage d'un site Drupal, vous remarquerez qu'il y a du code HTML en provenance de Drupal, des modules du core ou des modules tiers. Il peut vous déplaire, pour une raison ou pour une autre, et vous décider de le différencier du reste du site.

La plupart du code HTML fourni par Drupal, par le modules du core ou par les modules tiers, est surchargeable, ce qui veut dire qu'au lieu de modifier le module pour modifier l'affichage qu'il produit (ce qui n'est pas conseillé car cela provoquera tôt ou tard des problèmes dans la mise à jour des modules), vous pouvez modifier cet affichage en ajoutant des fonctions ou des fichiers à votre thème. Ces fonctions ou fichiers seront prioritaires sur les modules pour la génération du code HTML.

Il y a plusieurs façons de surcharger une sortie personnalisable, comme vous pourrez le constater dans les autres pages de cette section. Cette page-ci présente un simple survol des méthodes les plus courantes pour surcharger une sortie personnalisable, à l'intention des concepteurs de thèmes débutants.

Éviter simplement d'avoir à surcharger

Avant de décider que les affichages de Drupal ou de l'un des modules de votre site doivent être modifiés, examinez les possibilités suivantez - vous vous éviterez peut-être l'ensemble du processus :

• Pouvez-vous simplement modifier un paramètre ? Par exemple, vous pouvez cliquer sur le lien "Configurer" de n'importe quel bloc et cela vous permettra de lui modifier son titre, voire de le supprimer (sur la page de configuration des blocs - Administrer » Construction du site » Blocs - , vous pouvez aussi déplacer les blocs dans d'autres régions de la page).

  Certains modules vous permettent aussi de modifier quelques parties de leurs affichages à l'aide de paramètres (libellés pour des champs texte, ordre d'affichage, etc). Pour trouver leurs pages de configuration, cliquez sur Administrer puis sur Par module et regardez les pages de configuration que votre module propose. Les pages de configuration des thèmes peuvent également disposer de paramètres, et d'autres peuvent se trouver dans les différents onglets des pages de configuration des Types de Contenus (Administrer » Gestion de contenu » Types de contenu).

• Pouvez-vous effectuer les modifications avec les styles CSS ? Presque tous les affichages de Drupal sont situés dans des DIV utilisant des classes spécifiques ou des ID, vous permettant ainsi de ne personnaliser qu'une simple partie de l'affichage. Les CSS vous permettent de modifier les polices, les tailles, les emplacements, les images d'arrière-plan, etc. Pour surcharger un style fournit par Drupal ou par un module, il suffit de l'ajouter à l'un des fichiers CSS de votre thème.

Si aucune de ces possibilités ne vous permet de personnaliser ce que vous voulez, vous devrez surcharger les sorties HTML de Drupal ou de ses modules. Lisez la suite.

Trouver d'où vient le code à personnaliser

La première étape dans le processus de surcharge du code HTML de Drupal consiste à trouver qui fournit ce code. Ce que vous recherchez est-il :

• une fonction de thème (une fonction PHP appelée theme_xyz, comme theme_search ou theme_aggregator_block_item) ?
• une fonction de pré-traitement de thème (une fonction PHP appelée template_preprocess_xyz) ?
• ou un fichier de thème (un fichier PHP qui se termine par .tpl.php, comme views-more.tpl.php) ?

Pour trouver le bon fichier ou la bonne fonction, commencez par trouver le dossier du module qui produit l'affichage (dans modules, sites/all/modules ou sites/votre_sous_dossier/modules).

Les fichiers de thèmes se trouvent habituellement au plus haut niveau du dossier du module; dans le dossier du sous-module en-dessous, ou dans un dossier appelé theme situé en-dessous.

Les fonctions de thèmes et les fonctions de pré-traitement des gabarits (template preprocess functions) se trouvent soit dans le fichier module (qui se termine pas .module) ou dans un fichier inclus (qui se termine par .inc); le fichier se trouvera dans le dossier du module, ou dans un sous-dossier. Une bonne façon pour trouver la bonne fonction ou le bon fichier est de rechercher un ID CSS ou une classe spécifique de l'élément HTML que vous voulez modifier, ou un texte unique produit par le module.

Une autre façon de trouver la fonction à surcharger est d'utiliser les fonctionnalités Theme developper du module Devel.

Certains modules prennent en compte les templates suggestions. Par exemple, dans Views 2, vous pouvez avoir des informations sur les thèmes quand vous modifiez une vue -- Views vous dit quels fichiers de thèmes seront utilisés pour produire la vue, et le premier de chaque liste est un fichier de thème situé dans le sous-dossier themes de votre module Views; c'est le fichier de thème que vous devrez surcharger. Les autres noms de la liste sont des propositions pour les noms de fichiers qui seront placés dans votre thème, dépendants du niveau de détail de ce que vous voulez surcharger (par exemple, voulez-vous surcharger toutes les vues affichées, ou juste la vôtre ?).

Vous pouvez également utilisez les suggestions pour surcharger l'habillage des modules du core de Drupal. Par exemple, si vous voulez surcharger l'affichage d'un node d'un type de contenu en particulier, vous pouvez utilisez le fichier node.tpl.php de votre thème (ou du core Drupal) comme fichier à surcharger, le copier et le renommer en node-content_type_name.tpl.php. Vous trouverez plus d'informations sur les fichiers du core et sur les noms de fichiers suggestions sur la page Gabarits de core et suggestions.

Une fois que vous avez localisé la bonne fonction ou le fichier à surcharger, suivez l'une des deux voies décrites ci-après pour le faire.

Cependant, si ce qui produit le code HTML que vous voulez surcharger ne se trouve ni dans une fonction de thème, ni dans une fonction de pré-traitement de gabarit, ni dans un fichier de thème, vous ne pourrez probablement pas modifier l'affichage avec les seules fonctions. Vous aurez sans doute besoin de consulter les forums ou de contacter le développeur du module pour trouver comment modifier son affichage.

Surcharger une fonction de thème ou de pré-traitement

Si le code HTML que vous voulez surcharger se trouve dans une fonction de thème ou dans une fonction de pré-traitement, voici les étapes à suivre pour le surcharger :

1. Ouvrez votre fichier template.php dans un éditeur de texte.

2. Copiez la fonction de thème ou de pré-traitement que vous avez trouvée dans votre fichier template.php (une façon de trouver la fonction est de chercher son nom dans . Devel indique aussi la référence des fonctions dans son menu).

3. Renommez la fonction copiée (voir ci-dessous). Si le préfixe de votre thème est "merveilleux" et que la fonction de thème que vous surchargez s'appelle "theme_xyz", la fonction sera renommée merveilleux_xyz

   Si vous surchargez template_preprocess_xyz, le nouveau nom sera merveilleux_preprocess_xyz.

4. Modifiez la fonction pour qu'elle fasse ce que vous souhaitez.

5. Uploadez le fichier template.php sur votre site, dans le dossier de votre thème.

6. Rafraîchissez le cache de thème (voir le registre de thèmes)

Remarque : pour changer un nom de fonction, par exemple theme_xyz en merveilleux_xyz, trouvez la ligne qui ressemble à ceci :

Assurez-vous de ne pas modifier ce qu'il y a entre les parenthèses !

Surcharger un fichier de thème

Si le code HTML que vous voulez surcharger se trouve dans un fichier de thème, voici les étapes à suivre pour le surcharger :

1. Copiez le fichier de thème dans le dossier de votre thème, s'il ne contient pas déjà un fichier du même nom.

2. Si vous implémentez une suggestion, renommez le fichier pour qu'il ait le nom de la suggestion.

   Notez que certains fichiers suggestions ne seront reconnus que si le fichier de base se trouve également dans le dossier - par exemple, si vous voulez faire un fichier suggestion node content type pour votre type de contenu, le fichier node.tpl.php devra être présent dans votre dossier de thème pour que le fichier suggestion node-mon_type_de_contenu.tpl.php soit reconnu. Cependant, les suggestions pour Views ne demandent pas que le fichier template de base de Views soit présent dans votre dossier templates.

3. Modifiez le fichier pour qu'il fasse ce que vous voulez.

4. Uploadez le fichier dans votre site web, dans le dossier de votre thème, y compris le fichier de base s'il est requis.

5. Rafraîchissez le cache de thème (voir le registre de thèmes)