Surcharger une sortie personnalisable
Traduction de la page http://drupal.org/node/341628
publiée / actualisée le 11 Mars 2011 sur drupal.org
Selon la configuration de votre site, le code HTML de vos pages résulte de l'assemblage du code HTML fourni par les différents modules installés.
Si le balisage HTML par défaut ne correspond pas aux exigences de votre thème, vous pouvez le remplacer en totalité ou en partie, afin que les pages obtenues correspondent exactement aux besoins de votre design.
Par exemple, vous pourriez décider que la boite de recherche de votre site doive afficher l'image d'une loupe et que le libellé du bouton de recherche doit être « Magne-toi de trouver ! » plutôt que le classique mais ô combien tristounet libellé « Chercher ». Vous pourriez dans ce cas remplacer le balisage par défaut en totalité, pour que l'image et le libellé ressemble à ce que vous voulez.
Il est très important de comprendre le concept de « surcharge ». Si, techniquement parlant, vous pourriez vous contenter de trouver et de modifier le code-source du module responsable de la recherche, ce n'est ABSOLUMENT PAS recommandé. Cela semble résoudre la question à première vue, mais vous aurez très vite des problèmes pour maintenir votre site à jour : chaque fois que vous actualiserez le module, pour quelque raison que ce soit, vous devrez refaire toutes vos adaptations...
La bonne démarche, la Drupal way of life, consiste à faire une surcharge. Soit 4 étapes simples :
- Repérez le module responsable de la mise en page que vous voulez modifier,
- Faites l'une des opérations suivantes :
- si le module fournit un gabarit de mise en page, copiez le fichier gabarit .tpl.php dans le dossier de votre thème (voir Core Templates and Suggestion pour la liste des thèmes principaux)
OU - Dans le code-source du module, identifiez la fonction qui gère le balisage à modifier et copiez-là dans votre fichier de thème template.php. Vous aurez besoin de modifier le préfixe theme_ ou template_ pour qu'il corresponde au nom de votre thème. Par exemple, theme_breadcrumb deviendra montheme_breadcrumb; template_preprocess_page deviendra montheme_preprocess_page.
- Modifiez le code HTML dans la fonction ou dans le template copié,
- Rafraichissez le cache du thème.
Ces quatre étapes sont expliquées en détail dans les pages suivantes.
Cette façon de faire vous semblera peut-être intimidante si vous n'êtes pas familier avec le PHP, mais vous n'aurez sans doute pas à comprendre quoi que ce soit au PHP. Tant que vous savez quel code HTML vous voulez afficher, vous n'aurez qu'à modifier la partie du code HTML concernée.
Comme pour tout travail sur les thèmes, il vaut mieux éviter d'effectuer ces modifications sur un site en production sauf si, au préalable, vous avez soigneusement testé les modifications sur un site de développement.
Beaucoup de modules fournissent des feuilles de style qui spécifient l'apparence et le comportement par défaut de leurs affichages. Ces feuilles de style peuvent également être surchargées. Pour plus d'informations, reportez-vous à Overriding style sheets from modules and base themes.
Quelques modules tiers populaires qui surchargent l'affichage HTML par défaut
Quelques modules tiers ont leurs propres guides de thèmes. Voir également http://www.kolossaldrupal.org/docs/surcharger-feuilles-de-style-modules-et-themes-parents.
Les modules dont il existe une documentation pour leurs thèmes sont listés ci-dessous, classés par version de Drupal.
Modules compatibles Drupal 7
Modules compatibles Drupal 6
- CCK
- Views 2
- Views 2 Slideshow
- Panels
- Flag
- Nice Menus
- Menu Block
- Simplenews
- Browser Theme Settings
Guide du débutant pour surcharger les affichages personnalisables
Traduction de la page http://drupal.org/node/457740
publiée / actualisée le 27 Novembre 2010 sur drupal.org
L'idée de base dans la conception de thèmes Drupal est la surcharge des données affichées par les modules et le noyau Drupal. Au lieu de modifier un module pour modifier ce qu'il affiche (ce qui n'est pas à faire car cela compliquerait les mises à jours ultérieures), on modifie l'aspect de ce qui est affiché, en ajoutant des fichiers ou des fonctions au thème. Ces fichiers et fonctions sont prioritaires sur les paramètres du module pour ce qui concerne la mise en forme et la production du code HTML.
La surcharge se fait soit en surchargeant des fonctions du thème, soit en surchargeant des fichiers du thème, le choix de la méthode dépend de la façon dont l'affichage est créé par Drupal.
S'éviter d'avoir à tout surcharger
Avant de décider que ce qu'affiche de Drupal ou de l'un des modules de votre site doit être modifié, examinez les possibilités suivantez - vous vous éviterez peut-être l'ensemble du processus :
Pouvez-vous simplement modifier un paramètre ? Par exemple, cliquer sur le lien "Configurer" d'un bloc vous permettra de 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 de modifier des parties de ce qu'ils affichent grâce à leurs pages de configuration (libellés pour des champs texte, ordre d'affichage, etc). Pour trouver ces pages, cliquez sur Administrer puis sur Par module et regardez ce qui est proposé.
D'autres paramètres sont accessibles via la page de configuration des thèmes, et d'autres paramètres encore 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 obtenir ce que vous souhaitez via les styles CSS ? Presque tout ce qui est affiché par Drupal est encadré par des DIV qui utilisent des ID ou des classes spécifiques, vous pouvez ainsi ne personnaliser qu'une 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 CSS 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.
Surcharger les fonctions de thème
Une fonction de thème est une fonction PHP de Drupal dont le nom commence par theme_, comme par exemple theme_username. Pour surcharger une fonction de thème :
Ouvrez votre fichier template.php dans un éditeur de texte.
Copiez la fonction de thème trouvée dans votre fichier template.php (une façon de trouver la fonction est de chercher son nom dans http://api.drupal.org. Devel indique aussi la référence des fonctions dans son menu).
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.
Modifiez la fonction pour qu'elle fasse ce que vous souhaitez.
Uploadez le fichier template.php sur votre site, dans le dossier de votre thème.
Rafraîchissez le cache de thème (voir le registre de thèmes)
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 !
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 :
- soit une fonction de thème (une fonction PHP appelée theme_xyz, comme theme_search ou theme_aggregator_block_item)
- soit une fonction de pré-traitement de thème (une fonction PHP appelée template_preprocess_xyz)
- soit 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 par .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 de 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 ce 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 Fichiers gabarits du noyau (core templates).
Une fois que vous avez localisé la bonne fonction ou le fichier à surcharger, suivez l'une des deux voies décrites dans les pages suivantes (actualisation en cours - Avril 2011 - NdK).
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 sans doute pas faire de modifications avec les seules fonctions. Vous devrez probablement consulter les forums ou de contacter le développeur du module pour trouver comment modifier son affichage.
Introduction à PHP pour la conception de thèmes
Traduction de la page
http://drupal.org/node/348916
publiée / actualisée le 29 Janvier 2011 sur drupal.org
Vous enseigner le PHP sort largement du cadre de ce document, mais voici quelques-unes des techniques élémentaires qu'il est important de connaître pour travailler avec les thèmes.
Découvrir vos données
Utiliser le module Devel
La façon la plus facile pour voir les variables utilisées par un fichier gabarit est d'utiliser le module Devel. Il vous donnera non seulement accès direct, intéractif aux variables utilisées dans la création des pages, mais il dispose également de nombreuses fonctions pour débogguer les données pendant que vous travaillez.Coder en dur
Si pour une quelconque raison vous ne pouvez (ou ne voulez pas) utiliser le module Devel, il est possible d'utiliser une fonction PHP pour voir toutes les variables passées à votre fichier gabarit.
Pour cela, ajoutez le code suivant à n'importe quel fichier gabarit (tpl.php) de votre thème :
<?php
$vars = get_defined_vars();
print_r($vars);
?>les deux techniques précédentes utilisent beaucoup de ressources etpeuvent dévoiler des informations sensibles aux internautes. Aussi, vous ne devriez jamais les utiliser sur un site en exploitation.
Utiliser l'information dont vous disposez
Une fois que vous avez utilisé une des techniques précédentes, vous verrez de nombreuses variables et tableaux. Si vous le souhaitez, vous pouvez spécifier l'une de ces variables dans le fichier gabarit.
Par exemple, pour afficher le titre, vous pourrez ajouter le code suivant à votre fichier tpl.php :
<?php
print $title;
?>Pour afficher le titre du node, avec un lien pointant sur ce node et un peu de balisage, ajoutez le code suivant :
<a href="<?php print $node_url; ?>" title="<?php print $title; ?>"><?php print $title; ?></a>
</h2>
[/HTML]
<h3>Tableaux</h3>
<p>La technique du <span class="codeinline">print_r</span> montrée ci-dessus affichera probablement un certain nombre de tableaux. </p>
<p>Par exemple, si vous utilisez une taxonomie, vous pourriez obtenir quelque chose comme ceci :</p>
[html]
[taxonomy] => Array
Un tableau permet le regroupement organisé de données ayant un rapport entre elles. Si vous voulez n'afficher qu'un item d'un tableau, vous spécifierez cet item en utilisant sa clé.
Par exemple, supposons que print_r vous affiche le tableau suivant :
(
[lid] => 3
[name] => My Place
[street] => 235 King Edward Avenue
[additional] =>
[city] => Ottawa
[province] => ON
[postal_code] => K1N 7L8
[country] => ca
[latitude] => 45.431993
[longitude] => -75.688390
[source] => 3
[is_primary] => 0
[province_name] => Ontario
[country_name] => Canada
)
Si vous ne voulez afficher que la ville, ajoutez le code suivant à votre fichier .tpl.php :
<?php print $location['city'] ?>
Il y a d'autres façons de manipuler votre contenu avec PHP. Pour plus d'informations à ce sujet, consultez un des manuels de référence PHP disponibles sur le web.
La surcharge des thèmes
Traduction de la page
http://drupal.org/node/173880
publiée / actualisée le 11 Décembre 2010 sur drupal.org
Ce qui suit ne s'applique que si vous avez besoin de modifier le balisage par défaut. Vous pouvez sauter ces explications si votre présentation ne s'effectue que par le biais de feuilles de style.
Il y a trois étapes pour surcharger un thème. La première consiste à localiser la source des données, la seconde consiste à surcharger et la troisième consiste à comprendre son type.
Notez que les données du thème sont conservées en cache par Drupal, via le registre de thèmes (theme registry), ce registre doit être vidé lors de la mise en place des « surcharges ».
1. Localiser la source des données
La source des données affichées peut être difficile à déterminer étant donné la hiérarchie des appels de thèmes, qui peuvent provenir de n'importe où dans le système.
La plupart des éléments de la page sont généralement appelés avec theme('page') et placés dans le gabarit page.tpl.php après mise en forme des éléments... (traduction incomplète, voir le texte an anglais ci-dessous)
Most of the page elements are typically pulled with theme('page') and placed inside the page.tpl.php template after rendering navigation bits, the bits within the navigation bits, block regions, the blocks within the block regions, etc. Each chunk of themed data is often referred to as a theming "hook".
Remarque : les fonctions de thèmes et de gabarit seront désormais dénommées « theming hook ». Le système comprend de nombreux hooks qui n'ont rien à voir avec les thèmes. Les hooks dont nous parlerons ici ne concerneront que les thèmes.
Obtenir l'origine de toute partie de code mis en forme peut se faire grâce au module Theme developer. Il dispose d'un outil de développement de thème qui permet d'afficher facilement l'origine de tout affichage, son type et de nombreuses autres données du thème. Reportez-vous au screencast pour une démonstration. Cet outil n'est pas disponible dans les versions Drupal antérieures à la 6, en raison de limitations techniques.
2. Le système de surcharges
Le système de surcharges possède un ordre de cascades spécifique, comportant peu de dérogations. Le core Drupal et les modules fournissent un balisage par défaut géré par les hooks du thème. Si ce balisage ne convient pas aux exigences de votre thème, vous pouvez le remplacer par un autre, ce qui empêchera alors le chargement des valeurs par défaut. Les valeurs par défaut seront ainsi ignorées et toutes les modifications spécifiques au thème seront localisées dans le thème lui-même. C'est pourquoi vous ne devez jamais bricoler les fichiers en dehors de votre thème.
Si votre thème nécessite des contrôles qui ne peuvent être effectués dans le cadre des surcharges, vous pouvez alors intervenir sur le registre de thèmes ).
Remarque : bien que cela soit encore possible, le moteur PHPTemplate de Drupal 6 ne surcharge plus les fonctions de thème. Dans Drupal 5, c'est ce qui permettait l'utilisation de quelques theming hooks dans les gabarits de mise en page. Ce n'est plus nécessaire.
3. Les fonctions comparées aux gabarits
Il y a deux façons d'implémenter un theming hook : par le biais de fonctions ou par par le biais de gabarits. La méthode que vous utiliserez dépendra du but à atteindre ou de la nature de l'élément à personnaliser. Le core et les modules peuvent construire leurs sorties des deux façons, et les thèmes peuvent employer la même façon, ou la changer.
Diagramme de la version 5, pour comparaison : Flow map for 5
Les fonctions sont légèrement plus rapides que les gabarits, mais elles sont plus difficiles à appréhender par les concepteurs de thèmes habitués à travailler directement en xHTML. La rapidité dépendra de la nature du hook multiplié par le nombre de fois où il est appelé dans une page. Par exemple, l'utilisation de gabarits pour les theming hook "links" peut grandement impacter les performances pour des sites complexes et sollicités étant donné leur usage répété.
Voici deux exemples de surcharge à l'aide de Devel themer.
Surcharger des fonctions
La fonction theme_menu_local_tasks affiche les onglets primaires et secondaires. Son theming hook est menu_local_tasks. Pour le surcharger, le préfixe « theme » du nom de la fonction doit être remplacé par le nom de votre thème. (Dans Drupal 6, vous pouviez aussi utiliser le nom du moteur de thème qui exécutait le thème, mais ce n'était pas une pratique conseillée. Cette possibilité a été supprimé dans Drupal 7).
Cet exemple, tiré de Drupal 6, montre Garland utilisant le nom du moteur de thème pour la surcharge. Une fois encore, dans Drupal 6 il est conseillé d'utiliser le nom du thème et dans Drupal 7, il est obligatoire d'utiliser le nom du thème.
Placer le code suivant dans le fichier template.php du thème surchargera les valeurs par défaut après avoir vidé le registre des thèmes.
Remplacez « drop » par le nom de votre thème.
<?php
function mytheme_menu_local_tasks() {
$output = '';
if ($primary = menu_primary_local_tasks()) {
$output .= "<ol class=\"tabs primary\">\n". $primary ."</ol>\n";
}
if ($secondary = menu_secondary_local_tasks()) {
$output .= "<ol class=\"tabs secondary\">\n". $secondary ."</ol>\n";
}
return $output;
}
?>
La seule modification ici est le remplacement du balisage
Un listing de toutes les fonctions de thème (theme functions) est disponible dans api.drupal.org.
Surcharger les gabarits
Si c'est un gabarit qui implémente les valeurs par défaut, copier son fichier source dans votre thème le surchargera automatiquement, une fois que vous aurez vidé le registre de thème.
Voici un exemple pour search-theme-form.tpl.php. Notez que, dans ce cas, le point d'entrée est search_theme_form avec le gabarit utilisant des traits d'union au lieu de signes souligné.
C'est tout ce que vous avez besoin de faire. Ouvrez le gabarit copié dans un éditeur de texte pour faire vos modifications. Tous les fichiers tpl.php du core sont documentés. Cela vous donnera de bonnes informations sur ce qui peut être fait avec les sorties.
Remarque : les gabarits peuvent être placés dans n'importe quel dossier du thème. Cela permet une meilleure gestion et évite le désordre dans le dossier racine du thème.
Pages liées :
- Pour personnaliser les variables à l'intérieur des gabarits, reportez-vous à la page Preprocess functions.
- Un listing de tous les gabarits de thème est disponible à la page Core templates and suggestions.
Convertir des fonctions en gabarit
Convertir une fonction en gabarit demande un certain travail initial mais une fois réalisé, il est plus facile de travailler avec. Si vous travaillez avec un designer, la conversion lui permettra de se concentrer sur la seule conception et pas sur le codage.
Plusieurs gabarits sont déjà disponibles dans le core et beaucoup d'autres seront convertis dans les futures versions. Les modules additionnels qui respectent les bonnes pratiques devraient aussi avoir des gabarits disponibles. Ces instructions sont fournies pour les hooks des thèmes qui ne sont pas encore disponibles en gabarits.
La reconnaissance d'un hook comme gabarit est automatisée dans Drupal. Voici les seules règles pour déclencher cette modification :
- Le nom du gabarit doit correspondre au point d'entrée.
- Les signes soulignés du point d'entrée doivent être remplacés par des traits d'union.
- Le gabarit doit avoir tpl.php comme extension (cette extension peut varier en fonction du moteur du thème utilisé)
Prenons la fonction theme_user_signature. Ici, le hook est user_signature. La création d'un fichier nommé user-signature.tpl.php dira à Drupal, lorsque le registre aura été vidé, que le hook est maintenant ce gabarit.
Tout contenu dans ce fichier remplacera la fonction. La tâche qui demande le plus de travail est le paramétrage des variables à utiliser dans ce fichier et cela se fait par le biais des fonctions de pré-traitement (pre-process functions).
Quelques remarques :
- Bien qu'il soit possible de coder directement dans le gabarit, ce n'est pas une bonne pratique. Toute la logique de programmation ne doit pas se trouver dans le fichier tpl.php mais dans les fonctions de pré-traitement. Le code restera propre et sa gestion facilitée.
- C'est également une question de sécurité. La séparation du code minimise les risques d'attaques par cross-site scripting pouvant provenir d'un contenu utilisateur malveillant. Quand vous remettez les fichiers gabarits à votre designer, toutes les sorties seront « propres » et il n'aura pas à s'occuper des questions de sécurité.
- Si votre thème implémente une fonction de thème et un gabarit pour un hook donné, la fonction de thème sera toujours utilisée.
- La détection automatique des surcharges de thème est réalisée par le moteur PHPTemplate, en conséquence, assurez-vous que le moteur soit paramétré dans le fichier .info.
- Comparez les fonctions de thèmes de Drupal 5 (theming functions in 5) aux conversions de gabarits de Drupal 6 pour les forums (template conversions in 6). Vous pouvez les utiliser comme exemple de conversion d'un type à l'autre.
Le registre de thème :
Le registre de thème de Drupal conserve en cache les données des hooks du thème et la façon de les manipuler.
Pour beaucoup de développeurs, le registre ne doit pas être traité directement. Rappelez-vous simplement de le vider quand vous ajoutez ou modifiez des gabarits ou des fonctions de thème. La modification de fonctions ou de gabarits existants ne demande pas de reconstruire le registre.
Pour vider le registre de thèmes, faites l'une des opérations suivantes :
- Dans la page Administrer » Configuration du site » Performance, cliquez sur le bouton Supprimer les données du cache.
- Avec le bloc Devel activé (livré avec le module Devel), cliquez sur le lien Vider le cache.
- La fonction API drupal_rebuild_theme_registry.
Le registre de thèmes contient des données mises en cache indiquant à Drupal les hooks disponibles du thème et la façon de les manipuler selon leurs types. Dans les précédentes versions tous les appels de thème étaient exécutés à la volée. Comme beaucoup de travail est désormais effectué « sous le capot » par l'application, la mise en cache des instructions accélère les traitements, surtout en ce qui concerne les gabarits. Le moteur de thème qui exécute votre thème doit en principe automatiquement enregistrer pour vous les hooks de thème.
Il y a des situations particulières pour lesquelles vous aurez besoin de travailler directement avec le registre. Quand votre thème aura besoin d'enregistrer un nouveau hook qui n'était pas précédemment implémenté dans les couches inférieures du thème (celles du core, des modules, du moteur). Cela concerne des formulaires dont la présentation n'était pas explicitement réalisée par le core ou les modules mais était rattachée à la présentation défaut.
- Plus de détails disponibles dans la page The theme registry for special cases.
- Ne confondez pas le registre de thème avec le fichier .info du thème qui est lui aussi mis en cache. Les points 1 et 2 indiqués pour vider le cache videront les deux caches.
- Votre thème doit utiliser le moteur PHPtemplate pour que ses gabarits et fonctions soit pris en compte. D'autres moteurs devraient avoir le même comportement. Pour les thèmes qui n'utilisent pas de moteur, la prise en compte doit se faire manuellement.
Reportez-vous à phptemplate_theme pour voir comment faire.
Initialisation des variables pour leur utilisation dans un gabarit (fonctions de pré-traitement)
Traduction de la page http://drupal.org/node/223430publié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 :
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 :
Référence des variables par défaut
Traduction de la page http://drupal.org/node/226776
publiée/actualisée le 11 Mars 2011 sur Drupal.org
Ce qui suit est la référence des variables disponibles dans tous les fichiers gabarits. Elles sont générées par les fonctions de pré-traitement (preprocessor function) et template_preprocess. Les variables propres à un thème sont documentées dans leur fichier.
Nouvelles variables disponibles dans Drupal 7
Variables disponibles dans Drupal 6 et Drupal 7
Le chemin du thème, relatif à l'installation de base. Exemple :sites/all/themses/monTheme.$is_admin
Personnalisation et surcharge du Login Utilisateur, enregistrement et réinitialisation du mot de passe
Traduction de la page http://drupal.org/node/350634
publiée / actualisée le 1 Mars 2011 sur drupal.org
Personnaliser le login Utilisateur, l'enregistrement et la réinitialisation du mot de passe est assez simple et utilise les concepts suivants :
- pré-traitement pour initialiser les variables
- dépôt des fonctions dans le registre de thèmes
- création d'un ou plusieurs gabarits de thèmes.
Étape 1
Dans le dossier principal de votre thème, créez ou éditez votre fichier template.php.
Étape 2
Recherchez une fonction appelée yourtheme_theme() et modifiez-la pour lui ajouter ces valeurs retour ou, si elle n'existe pas, ajoutez le code suivant :
<?php
/**
* Registers overrides for various functions.
*
* In this case, overrides three user functions
*/
function yourtheme_theme() {
return array(
'user_login' => array(
'template' => 'user-login',
'arguments' => array('form' => NULL),
),
'user_register' => array(
'template' => 'user-register',
'arguments' => array('form' => NULL),
),
'user_pass' => array(
'template' => 'user-pass',
'arguments' => array('form' => NULL),
),
);
}
?>
Remarques sur ce code :
- Modifiez le nom de la fonction : remplaçez « yourtheme » par le nom de votre thème.
- La valeur de template peut être la même pour les trois items. Dans cet exemple, on utilise un gabarit différent pour chaque cas : user-login, user-register et user-pass.
- Le nom du gabarit doit utiliser un tiret et non un signe souligné.
- C'est bien user_pass et non user_password.
Étape 3
Maintenant, implémentez trois fonctions de pré-traitement (pre-process functions). Il y a de meilleures façons de coder ce qui suit, mais ça marche aussi très bien comme ça, alors n'hésitons pas !
<?php
function yourtheme_preprocess_user_login(&$variables) {
$variables['intro_text'] = t('This is my awesome login form');
$variables['rendered'] = drupal_render($variables['form']);
}
function yourtheme_preprocess_user_register(&$variables) {
$variables['intro_text'] = t('This is my super awesome reg form');
$variables['rendered'] = drupal_render($variables['form']);
}
function yourtheme_preprocess_user_pass(&$variables) {
$variables['intro_text'] = t('This is my super awesome insane password form');
$variables['rendered'] = drupal_render($variables['form']);
}
?>
Remarques sur ce code :
- Modifiez le nom de la fonction : remplaçez « yourtheme » par le nom de votre thème.
- La ligne $variables['intro_text'] place le texte qui la suit dans la variable $variables, qui est, par la suite, acheminée au gabarit via la variable $intro_text.
- La deuxième ligne façonne le formulaire et ajoute le code dans le tableau $variables, qui est passé au gabarit via la variable $rendered.
Étape 4
Créez les gabarits dont les noms correspondront aux valeurs passées à l'item template. Dans cet exemple nous n'avons besoin que de deux fichiers : user-login.tpl.php et user-register.tpl.php (veillez à taper un tiret et non un signe souligné)
Étape 5
Copiez le code suivant dans le fichier user-login.tpl.php. Modifiez-le si besoin pour user-login.tpl.php et user-register.tpl.php:
<?php print $intro_text ; ?> </p>
<div class="my-form-wrapper">
<?php print $rendered ; ?>
</div>
?>
Étape 6
Sauvegardez ces fichiers dans le dossier principal de votre thème.
Étape 7
Reconstruisez le cache : menu Administrer » Configuration du site » Performance » clic sur « Supprimer les données du cache » en bas de la page.
Maintenant, votre page de connexion Utilisateur contiendra le nouveau texte issu de la fonction de pré-traitement, et les fichiers tpl.php pourront être modifiés pour répondre aux besoins de votre site.
Exemple : affichage personnalisable
Traduction de la page
http://drupal.org/node/581786
publiée / actualisée le 1 Mars 2011 sur drupal.org
Comment personnaliser le code HTML du bloc de recherche
Cet exemple explique comment personnaliser le code HTML pour le bloc de recherche proposé par défaut. Ce bloc est créé par le module Search.
Cela peut se faire en utilisant la méthode fichier tpl.php :
- Depuis la racine de votre site, aller dans le dossier modules/search.
- Copier le fichier modules/search/search-block-form.tpl.php dans sites/all/themes/votretheme/search-block-form.tpl.php.
Vous allez maintenant modifier le fichier qui se trouve dans le dossier de votre thème.
Dans search-block-form.tpl.php vous trouverez ce code-source :
Dans le code qui suit, on a enlevé l'instruction d'affichage précédente et on l'a remplacé par nouveau code HTML en charge de l'affichage, comme indiqué dans les directives figurant au début du fichier:
<?php $search['search_block_form'] = '
<div class="form-item" id="edit-search-block-form-1-wrapper">
<input type="text" maxlength="128" name="search_block_form" id="edit-search-block-form-1" size="15" value="" title="Enter the terms you wish to search for." class="form-text" />
<br />
<label for="edit-search-block-form-1">Search posts and comments</label>
</div>';
print $search['search_block_form'];
print $search['submit'];
print $search['hidden'];
?>
</div>
Ce code HTML a simplement été prélevé dans le code-source de la page d'origine (via Firebug, ou en affichant le code-source de la page) puis a été réorganisé. Vous pouvez bien évidemment ajouter d'autres balises, des CSS ou d'autres contenus dont vous auriez besoin. Assurez-vous cependant de ne pas modifier les noms et les ID des éléments, faute de quoi le formulaire ne sera pas correctement traité.
La destination des variables affichées dans ce code-source modifié est expliquée dans le fichier search-block-form.tpl.php initial (situé dans racine_du-site/modules/search/search-block-form.tpl.php).
Voici les clés de $search, disponibles dans les commentaires :
- $search['search_block_form']: zone de saisie du texte, encadrée dans un div.
- $search['submit']: Bouton d'envoi du formulaire.
- $search['hidden']: Éléments cachés du formulaire. Utilisée pour valider le formulaire lorsqu'il est envoyé.
Identifier les composants du noyau (core)
Traduction de la page http://drupal.org/node/778900
publiée/actualisée le 1 Mars 2011 sur drupal.org
Une liste de composants du noyau Drupal (core) et comment les surcharger.
ID CSS des blocs du noyau
Traduction de la page http://drupal.org/node/778884
publiée/actualisée le 1 Mars 2011 sur drupal.org
Le noyau Drupal génére des blocs qui disposent chacun d'un ID CSS unique. Avec Drupal 7, la plupart de ces ID ont été changés pour indiquer plus clairement le but du bloc.
- Sujets de forum actifs
- Drupal 6 : block-forum-0
- Drupal 7 : block-forum-active
- Infos sur l'auteur
- Drupal 6 : block-profile-0
- Drupal 7 : block-profile-author-information
- Navigation de livre
- Drupal 6 : block-book-0
- Drupal 7 : block-book-navigation
- Sélecteur de langue
- Drupal 6 : block-locale-0
- Drupal 7 : block-locale-language-switcher
- Sondage le plus récent
- Drupal 6 : block-poll-0
- Drupal 7 : block--poll-recent
- Navigation
- Drupal 6 : block-user-1
- Drupal 7 : block-system-navigation
- Nouveaux sujets de forum
- Drupal 6 : block-forum-1
- Drupal 7 : block-forum-new
- Contenu populaire
- Drupal 6 : block-statistics-0
- Drupal 7 : block-statistics-popular
- Powered by Drupal
- Drupal 6 : block-system-0
- Drupal 7 : block-system-powered-by
- Billets de blog récents
- Drupal 6 : block-blog-0
- Drupal 7 : block-blog-recent
- Commentaires récents
- Drupal 6 : block-comment-0
- Drupal 7 : block-comment-recent
- Formulaire de recherche
- Drupal 6 : block-search-0
- Drupal 7 : block-search-form
- Syndication
- Drupal 6 : block-node-0
- Drupal 7 : block-node-syndicate
- Login utilisateur
- Drupal 6 : block-user-0
- Drupal 7 : block-user-login
- Who's new
- Drupal 6 : block-user-2
- Drupal 7 : block-user-new
- Qui est en ligne
- Drupal 6 : block-user-3
- Drupal 7 : block-user-online
Déclaration de style CSS, à la sauce Drupal 6 :
#block-user-0 {
font-size: 1.5em;
}
Déclaration de style CSS, à la sauce Drupal 7 :
#block-user-login {
font-size: 1.5em;
}
« Objectif du site » et région en « surbrillance »
Traduction de la page http://drupal.org/node/779016
publiée/actualisée le 1 Mars 2011 sur drupal.org
Drupal 6.x
Dans Drupal 6, le fichier de mise en page reçoit une variable particulière nommée $mission. Elle contient l'objectif du site et l'affiche en page d'accueil. Les thèmes Drupal 6 disposent également d'une option dans leurs pages de configuration pour décider de l'affichage ou pas de l'objectif du site.
Dans .info :
Dans page.tpl.php :
<?php
print $mission;
?>Drupal 7.x
Dans Drupal 7, le paramètre Objectif du site est supprimé, ainsi que son paramètre d'affichage. A la place, on utilise le système d'affichage des blocs dans des régions. Le système de thèmes de Drupal 7 dispose désormais d'une région nommée « highlighted » qui utilise le même affichage que l'objectif du site de Drupal 6. Le contenu de cette zone dépend désormais des paramètres d'affichage des blocs et il n'est plus limité à la page d'accueil du site.
Si votre thème déclare des régions personnalisées et n'incorpore pas une région « highlighted », vous pouvez déclarer la région en l'ajoutant à la liste des régions énumérées dans votre fichier .info. Si le thème ne déclare pas de régions dans le fichier .info, les régions fournies par le noyau seront automatiquement héritées et vous n'aurez qu'à vous assurer qu'elles soient traitées dans votre fichier page.tpl.php.
Dans .info :
Dans page.tpl.php :
<?php
print render($page['highlighted']);
?>Navigation
Traduction de la page http://drupal.org/node/778906
publiée/actualisée le 1 Mars 2011 sur drupal.org
Les liens Primaire et Secondaire de Drupal 6 ont été renommés en Main et Secondary dans Drupal 7. Les thèmes qui les utilisent doivent être actualisés pour utiliser les nouveaux noms de variables.
6.x : Primary et Secondary
[php]
if (isset($secondary_links)) { ?><?php print theme('links', $secondary_links, array('class' => 'links', 'id' => 'subnavlist')); ?><?php } ?>
<?php if (isset($primary_links)) { ?><?php print theme('links', $primary_links, array('class' => 'links', 'id' => 'navlist')) ?><?php }
[/php]
</div>
7.x : Main et Secondary
[php]
if (isset($secondary_menu)) { ?><?php print theme('links', $secondary_menu, array('class' => 'links', 'id' => 'subnavlist')); ?><?php } ?>
<?php if (isset($main_menu)) { ?><?php print theme('links', $main_menu, array('class' => 'links', 'id' => 'navlist')) ?><?php }
[/php]
</div>
Taxonomie
Traduction de la page http://drupal.org/node/778922
publiée/actualisée le 1 Mars 2011 sur drupal.org
Drupal dispose de la Taxonomy, une fonctionnalité du noyau qui permet aux utilisateur de « tagger » du contenu.
Les liens de taxonomie non mis en forme désormais indisponibles en tant que variable distincte dans node.tpl.php
Traduction de la page
http://drupal.org/node/778926
publiée / actualisée sur drupal.org le 1 Mars 2011
Dans Drupal 6, les fichiers node.tpl.php peuvent utiliser la variable $taxonomy s'ils ont besoin d'accéder à un tableau de liens de taxonomie, non mis en forme, associé au node en cours.
Ce n'est plus le cas dans Drupal 7. A la place, tous les liens ont été déplacés dans l'objet $node.
Le tableau de liens de taxonomie non mis en forme se trouve désormais dans $node->content['links']['terms']['#value'] (à noter que ce tableau doit être utilisé avec précautions, puisque le texte qu'il contient n'a pas été « échappé » pour éviter les attaques XSS).
Les liens de taxonomie mis en forme n'ont pas été touchés; les fichiers node.tpl.php continuent d'y accéder comme avant, via la variable $terms. Dans la plupart des cas, c'est cette variable $terms que vous voudrez utiliser dans votre thème, et vous voudrez peut-être remplacer par elle les références à $taxonomy,comme dans l'exemple suivant :
6.x
7.x
Styliser les menus
Traduction de la page
http://drupal.org/node/988842
publiée / actualisée sur drupal.org le 1 Mars 2011
La nouvelle fonction theme_links($variables) de Drupal 7 ne reçoit qu'un tableau associatif pour toute la structure du lien. Comme vous pouvez le lire dans la documentation, vos liens doivent être passés en tant que tableaux associatifs via un argument links, mais ne décrit pas où et comment vous trouver cette variable.
L'exemple suivant explique comment faire avec le menu utilisateur :
<?php
$user_menu = menu_navigation_links('user-menu');
print theme('links', array(
'links' => $user_menu,
'attributes' => array(
'id' => 'user-menu',
'class' => array('links', 'clearfix'),
),
'heading' => array(
'text' => t('User menu'),
'level' => 'h2',
'class' => array('element-invisible'),
),
));
?>Qu'est donc l'argument user-menu dans la fonction menu_navigation_links($menu_name, $level = 0) ? C'est le nom du menu qui doit être affiché. Vous trouverez le nom du menu de cet exemple dans la page d'administration User menu (Administration > Structure > Menus > User menu ) ou http://example.com/admin/structure/menu/manage/user-menu/edit de votre site.
Dans cet exemple, la variable $user_menu n'est pas obligatoire, mais en procédant de la sorte, vous pourrez l'utiliser ensuite dans une instruction conditionnelle qui est plus courante dans un gabarit.
Surcharger un menu dans un bloc
Traduction de la page
http://drupal.org/node/988694
publiée / actualisée sur drupal.org le 1 Mars 2011
Créez une fonction override dans votre fichier template.php :
<?php
function themename_links__system_MENUNAME_menu($variables) {}
?>Un paramètre $variables est passé et il contient un index nommé links. Chaque lien contient, entre autres, un href et un title.
A l'intérieur de votre fonction override, parcourez les liens :
<?php
foreach ($variables['links'] as $link) {}
?>Si nous voulons juste afficher une balise <a>, sans utiliser Drupal, nous écririons normalement :
<?php
echo "<a href="{$link['href']}">{$link['title']}</a>";
?>Cependant, Drupal dispose d'une fonction l() qui crée les liens pour nous. Il vaut mieux l'utiliser car elle traite les cas particuliers comme le lien <front>.
Aussi, nous ferons plutôt ça :
<?php
echo l($link['title'], $link['href'], $link);
?>La fonction l() s'occupera d'ajouter une classe active si le lien est destiné à la page en cours.
Au finale, votre fonction override ressemblera à ceci :
<?php
function themename_links__system_MENUNAME_menu($variables) {
$output = '';
foreach ($variables['links'] as $link) {
$output .= l($link['title'], $link['href'], $link);
}
return $output;
}
?>Le registre de thèmes pour les cas particuliers
Traduction de la page http://drupal.org/node/223463publiée/actualisée le 1 Mars 2011 sur drupal.org
Vous devez être familiarisé avec la raison d'être du registre de thème (purpose) avant de poursuivre la lecture de cette page. Les explications qui suivent portent sur l'enregistrement manuel d'un point d'entrée de thème et sur comment le manipuler (manipulated)
Le cas le plus fréquent demandant l'enregistrement manuel des points d'entrée sont les formulaires. Le design des éléments de formulaire est personnalisable mais il existe un autre aspect concernant la façon dont ils sont traités.
Dans un formulaire, on peut trouver des éléments génériques tels que cases à cocher, boutons radios, listes déroulantes, boutons, etc. Chacun de ces éléments est personnalisable et surcharger leurs styles n'implique pas de devoir enregistrer manuellement les points d'entrée qui leurs sont associés.
Le nouvel aspect dont il est question vient avec les formulaires personnalisés dans lesquels chaque élément est disposé de façon très particulière. Dans certains formulaires, ces éléments viennent déjà organisés, designés et enregistrés. Pour ces formulaires, l'enregistrement manuel n'est pas nécessaire.
The forms that are not explicitly themed will default to how form API renders them.
Exemple de formulaire enregistré :
Voici un exemple pour deux des formulaires de recherche enregistrés par le module Search, la boite de recherche et le bloc de recherche. Chaque formulaire est associé à un identifiant unique.
L'enregistrement des identifiants sert également de point d'entrée de thème. Dans cet exemple, il s'agit de search_theme_form et search_block_form.
<?php
function search_theme() {
return array(
'search_theme_form' => array(
'arguments' => array('form' => NULL),
'template' => 'search-theme-form',
),
'search_block_form' => array(
'arguments' => array('form' => NULL),
'template' => 'search-block-form',
),
...
);
}
?>
L'API Form passe le contrôle de sa présentation au handler du point d'entrée enregistré.
Form API passes control of its presentation along to the handler of the registered hook.
Dans cet exemple, il est enregistré avec le type de gabarit et ses arguments par défaut. La sortie sera facilement modifiée par le thème puisqu'il a déjà été déclaré comme gabarit (template).
L'auto-découverte des points d'entrée ne se produit qu'avec les points d'entré de thèmes enregistrés avant la couche du thème (voir illustration : http://www.kolossaldrupal.org/docs/la-surcharge-themes#theming-overrides)
Formulaires déclarés et non déclarés :
Il y a un autre formulaire de recherche qui n'est pas enregistré. C'est le formulaire avec l'identifiant search_form utilisé dans la page de recherche principale. Les données du formulaire sont construites dans une fonction (constructed in a function), tout comme n'importe quel autre formulaire, mais on laisse l'API Form s'occuper de la présentation en la basant sur la structure de données du formulaire.
Pour pouvoir la surcharger, vous devez l'enregistrer depuis votre thème avec un hook_theme. Mettez le code suivant dans votre fichier template.php en remplaçant le préfixe « drop » par le nom de votre thème. Le point d'entrée est l'identifiant du formulaire :
<?php
function drop_theme() {
return array(
'search_form' => array(
'arguments' => array('form' => NULL),
),
);
}
?>Les formulaires au design personnalisé ont toujours un argument form. Puisque le gabarit n'a pas été spécifié, le point d'entrée sera vu comme une fonction de thème et non comme un gabarit. Une fonction de thème doit avoir un préfixe correspondant au thème qui l'a enregistré. phptemplate_* ne marchera pas. Aussi, avec la valeur précédente, la fonction de thème ressemblera à ceci :
<?php
function drop_search_form($form) {
$advanced = '';
$simple = '';
foreach (element_children($form) as $element) {
if ($element == 'advanced') {
$advanced .= drupal_render($form[$element]);
}
else {
$simple .= drupal_render($form[$element]);
}
}
return $advanced . $simple;
}
?>
La seule chose modifiée ici est le positionnement du formulaire de recherche avancé.
- Les sous-thèmes qui surchargent un formulaire enregistré dans leurs thèmes parents n'ont pas à redéclarer manuellement le formulaire. Rappelez-vous que l'enregistrement permet l'auto-découverte pour les couches situées au-dessus et que les sous-thèmes ne sont rien d'autre qu'une couche au-dessus des thèmes parents.
- Ceci sera plus automatisé dans les version futures. Les développeurs sont conscient de la charge de travail que cela impose aux concepteurs de thèmes.
Manipulation manuelle
La manipulation manuelle du registre de thème est une fonctionnalité avancée. Vous pouvez en prendre connaissance en cliquant sur « Theme registry » dans le bloc fourni par le module Devel. Il peut également être retourné avec theme_get_registry.
A compléter...
(c'est la version anglaise qui indique : A compléter...)
Travailler avec des « templates suggestions »
Traduction de la page http://drupal.org/node/223440
publiée/actualisée le 11 Mars 2011 sur Drupal.org
Les « templates suggestions » sont des maquettes de mise en pages (gabarits) alternatives basés sur des fichiers .tpl.php existants.
Ces « suggestions » sont utilisées quand une circonstance particulière est rencontrée et qu'un fichier correspondant existe. 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 mise en page adaptée à 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 nombreuses fournies par le core. Si vous avez besoin de les enrichir davantage, ajoutez un pré-traitement pour le hook de thème dans votre fichier template.php. L'exemple ci-dessous ajoute des suggestions pour les hooks node et page. On peut en ajouter à n'importe quel hook implémenté en tant que gabarit.
Drupal 7
Drupal 6
Une liste de toutes les suggestions du core est disponible sur la page Drupal 6, suggestions de modèles de mise en page.
Le préfixe « drop » doit être remplacé par le nom de votre thème.
<?phpfunction drop_preprocess_page(&$variables) {
global $user;
// Add a single suggestion based on the throttle module in core.
if (module_invoke('throttle', 'status') && isset($user->roles[1])) {
$variables['template_file'] = 'page-busy';
}
// Add multiple suggestions for pages based on the logged in user's roles.
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;
}
}
}
?>
Personnaliser la mise en page selon un type de contenu arbitraire
Vous pouvez améliorer le code précédent pour avoir des suggestions pour chaque type de contenu de votre site.
if ($variables['node']->type != "") {
$variables['template_files'][] = "page-node-" . $variables['node']->type;
}
}
Ensuite, créez votre fichier de mise en page sous la forme page-node-votre_type_de_contenu. Si ce fichier est manquant, ce sera la mise en page par défaut qui sera utilisée.
Il y a deux façons d'ajouter ces suggestions :
- 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.
- 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 précédent, 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, le 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.
- Préfixez la suggestion avec le nom du hook auquel 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.
<?php
// Ne faites pas ceci :
$variables['template_files'] = array('hook-suggestion');
// Faites plutôt cela :
$variables['template_files'][] = 'hook-suggestion';
?>Aperçu de l'architecture des thèmes
Traduction de la page http://drupal.org/node/171188
publiée/actualisée le 3 Janvier 2010 sur drupal.org
Cette page fournit des informations de base sur l'architecture sous-jacente des thèmes. Elle intéressera ceux qui ont besoin d'une compréhension plus poussée sur la façon dont fonctionnent les surcharges.
Une pratique courante en programmation consiste à dissocier la partie programmation proprement dite de la partie présentation des données. Il y a de nombreuses raisons à cela, la plus évidente étant que les compétences requises pour la programmation sont très différentes de celles demandées pour l'élaboration d'une charte graphique ou d'une interface utilisateur efficace.
En tant que concepteur de thème, vous pouvez contrôler certains aspects des données disponibles, mais vous ne pouvez agir que sur leur présentation. Seuls le core Drupal et les modules travaillent avec les données saisies. Par exemple, un module peut implémenter un formulaire avec une présentation par défaut et une gestion des saisies utilisateur, puis sauvegarder les données dans la base de données. Le rôle du thème consiste simplement à modifier la présentation.
Dans Drupal, cette abstraction est assurée par le biais des fonctions de thème. C'est un accès vers le sous-système des thèmes. Il permet aux moteurs de thème de fournir une couche intermédiaire, facultative, à destination des « tagging languages » tels que PHPTAL ou Smarty. Il permet aussi aux thèmes de contrôler toutes les balises de présentation. Les moteurs de thèmes sont facultatifs en tant que « tagging languages ». PHPTemplate est le moteur par défaut. Comme son nom l'indique, il utilise le langage PHP lorsque les variables affichées sont mélangées avec du balisage xHTML.
A partir de Drupal 6, les exigences pour la création de thèmes ont été sensiblement réduites.
Toutes les couches peuvent implémenter une personnalisation de l'affichage des données, mais (à quelques exceptions près) la surcharge ne peut avoir lieu qu'à l'intérieur des couches du thème. Les moteurs de thème peuvent surcharger la présentation des sorties provenant du core ou des modules, tandis que les thèmes peuvent surcharger tout le reste.
Notez que le moteur PHPTemplate ne surcharge aucune sortie mais que d'autres moteurs de thèmes peuvent le faire. Il existe le cas particulier d'un module pouvant modifier les sorties en partie ou en totalité, mais il a été prévu pour des situations très particulières qui ne devraient en principe pas se produire dans les cas courants. Il s'agit du module devel theme qui surcharge toutes les sorties, pour aider à la conception des thèmes (aid theme development). D'autres infos sont exposées dans cette section.
Vous pouvez ignorer tout ceci en grande partie si votre thème est entièrement basé sur des styles CSS, mais si c'est le balisage qui doit être modifié, vous devez savoir comment localiser sa création pour pouvoir le modifier.
- Notez que le core Drupal et de nombreux modules utilisent toujours des fonctions de thème et des fichiers gabarits pour afficher le balisage de présentation. Ne modifiez jamais ces fichiers en-dehors du dossier de votre thème, faute de quoi vous vous exposeriez à pas mal de difficultés lors d'une éventuelle mise à jour. Faire ceci s'appelle « forking ». La puissance de l'open source réside dans l'existence d'une communauté qui corrige les bugs et ajoute de nouvelles fonctionnalités. Si vous faites un « fork » vous créez un système fermé et perdez les avantages apportés par la communauté. Drupal fournit toutes les fonctionnalités pour surcharger la couche de présentation. Si vous avez à modifier les fichiers en-dehors du thème c'est que, soit vous faites fausse route, soit vous avez déniché un bug. Dans ce dernier cas, signalez plutôt le bug (http://drupal.org/node/317). Ou, mieux, fournissez un patch qui le corrige.
- Pour ceux qui s'étaient familiarisés avec le moteur de PHPTemplate présent dans les versions précédentes, presque toutes les fonctionnalités ont été enfouies plus profondément dans le core. Le travail de PHPTemplate se réduit maintenant à découvrir les fonctions de thème et les gabarits basés sur le nom du thème. Il agit moins en moteur et davantage en aide pour les thèmes. PHPTemplate fut écrit à l'origine par Adrian Rossouw pour la version 4.7 de Drupal. Les changements pour la version 6 furent l'œuvre de Earl Miles. Un forum de discussion explique les raisons de la création initiale du moteur.