Afin d'offrir de nouvelles possibilités, le moteur de template de PHPBoost 4.0 a été entièrement revu.
Cette page décrit en détails les possibilités (les nouvelles comme les anciennes) offertes par le moteur de template de PHPBoost.
Un template se compose de différents éléments de syntaxe.
Texte simple
Le résultat :
Il est possible d'échapper des caractères spéciaux qui pourraient être interprétés par le moteur de template en les faisant précéder par un antislash : “\”.
La liste des caractères spéciaux qu'il peut être nécessaire d'échapper est la suivante : \, $, #, {, }
Le moteur de templates supporte différents types de variables. Dans cette partie, nous détaillerons les variables simples et les variables de langues.
Une variable simple sera remplacée par la valeur assignée à la variable côté PHP.
Le résultat :
Le fichier de langues associé se trouvant dans le répertoire /monmodule/french/meslangues.php
Le résultat :
Dans cette exemple on voit deux choses. Tout d'abord, il faut associer la langue au Template avec la méthode resources qui prend en argument le chemin vers la langue à charger. Cette langue sera prise en compte à l'exécution pour savoir si il faut aller la chercher dans le répertoire french, english ou autre.
Ceci peut également se faire directement en PHP. L'exemple suivant est équivalent :
Le fichier de langue associé se trouvant dans le répertoire /monmodule/french/meslangues.php
Ici, la variable de langue est appelée en utilisant la syntaxe @nomDeLaVariableDeLangue. Cette syntaxe est un raccourci pour l'appel i18n('nomDeLaVariableDeLangue'). Cette seconde méthode sera détaillée dans la partie méthode de template.
Le moteur de templates supporte les conditions de type IF (not) une condition / ELSE. La condition peut être une variable, une constante, ou bien le retour d'une méthode.
Le résultat :
Le résultat si la statique méthode
DayTime::is_lunch_time()
retourne
false
Le résultat :
Le résultat :
Le résultat :
Le premier template à inclure
Le second template à inclure
Le PHP
Le résultat :
Les expressions permettent d'appeler du PHP directement depuis un template. Ceci est utile car cela permet de ne plus assigner les langues dans le PHP et de mettre en forme les messages directement dans les templates.
Pour cela, il est possible d'appeler soit des fonctions de templates, soit des méthodes statiques sur de vraies classes PHP.
Les méthodes de templates sont des méthodes qui permettent d'appeler certains services directement depuis le template. Voici la liste de ces méthodes :
Pour plus d'informations sur ces méthodes, il faut se reporter à la PHPDoc de la classe TemplateFunctions
Le résultat :
Le résultat :
Si l'on comprend bien l'intérêt des expressions pour modifier la mise en page des variables passées au template, il est peut-être plus difficile de comprendre l'intérêt des expressions qui n'écrivent rien dans les templates. Pourtant elles sont également très importantes.
En effet, pour associer un fichier de langue à un template, on peut soit le faire en PHP, soit directement dans le template. Dans le cas où cela se fait directement dans le template, aucun élément ne sera à écrire dans le template.
Le résultat:
Dans le cas ou le #{resources()} n'aurait pas été fait, il aurait fallut faire cette association en php de la façon suivante :
Si aucune de ces deux méthodes n'est employée alors un message d'erreur indiquera que la langue n'a pas été trouvée.
Il est possible d’inclure du PHP dans les templates, cependant, ceci est à proscrire pour plusieurs raisons :
- Cela risque fort de mener à avoir des traitements dans le template qui n’ont rien à voir avec la mise en page, ce qui rend la future maintenance du module beaucoup plus compliquée, car en plus de changer la logique dans le code PHP du module, il faudra également retravailler de façon approfondie les templates.
- Cela n’est pas performant. En effet le moteur de rendu de PHPBoost permet d’afficher le template directement avec une instruction echo, ou bien de pouvoir l’injecter ailleurs en donnant un rendu sous forme de chaîne de caractères. Ce second cas rend la gestion des echos qui pourraient être fait dans le code PHP appelé très compliquée .
- La solution utilisée par le moteur de templates pour supporter ces echos consiste à stocker dans le buffer de sortie ce qui va être écrit. Or l’opération visant à préserver ce buffer est extrêmement coûteuse en terme de performances.
Si malgré ceci vous avez tout de même besoin d’utiliser du PHP dans vos templates, voici un exemple.
Le résultat :
Nous venons de voir comment écrire des templates et quels étaient les mécanismes PHP pour communiquer avec ceux-ci.
Nous allons maintenant voir quelques fonctionnalités côté PHP permettant de créer un objet Template et l'utiliser assez simplement.
Ce bout de code va chercher à créer un objet Template en utilisant le premier fichier de template existant.
- /templates/$theme/modules/mymodule/mytpl.tpl : C’est le fichier de template fourni par le thème utilisé. Il est utilisé prioritairement s'il est trouvé car il est en accord avec le thème.
- /mymodule/templates/mytpl.tpl : C’est le fichier de template fourni par le module à utiliser si le thème ne propose pas sa propre version.
Dans les deux cas précédent, un objet template à été créé. Il se comportement indifféremment, peu importe que le template soit issu d’un fichier ou d’une chaîne de caractères.
Afin de faciliter le travail des développeurs, un certain nombre de variables sont assignés au template par défaut. En voici la liste :
Le moteur de templates de PHPBoost 4.0 est (presque) entièrement compatible avec les templates de la version 3.0.
Ceci signifie que tous les templates de la 3.0 continueront à fonctionner sans nécessiter d'adaptation sur la 4.0 (à de rares exceptions près).
Pour adapter un thème 3.0 en version 4.0, utilisez cette procédure : Mettre à jour son thème 3.0 en 4.0