V. Développer avec PHPBoost

Système de Templates

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.



La syntaxe des templates





Un template se compose de différents éléments de syntaxe.

  • Du texte simple
  • Des variables
  • Des conditions
  • Des boucles
  • Des inclusions de sous-templates
  • Des expressions qui écrivent dans le template
  • Des expressions qui n'écrivent pas dans le template
  • Du PHP





Texte simple





Code TPL :
Il est possible d'écrire du texte simplement dans un template, c'est le contenu par défaut


Le résultat :

Code HTML :
Il est possible d'écrire du texte simplement dans un template, c'est le contenu par défaut


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 : \, $, #, {, }




Variables


Le moteur de templates supporte différents types de variables. Dans cette partie, nous détaillerons les variables simples et les variables de langues.



Variable Simple


Une variable simple sera remplacée par la valeur assignée à la variable côté PHP.

Code TPL :
Il est possible d'écrire du texte avec des {VARS}


Code PHP :
$template->put('VARS', 'variables');


Le résultat :

Code HTML :
Il est possible d'écrire du texte avec des variables




Variable de langue


Code TPL :
#{resources('monmodule/meslangues')}
{@hello.world}


Le fichier de langues associé se trouvant dans le répertoire /monmodule/french/meslangues.php

Code PHP :
$lang = array('hello.world' => 'Bonjour');


Le résultat :

Code HTML :
Bonjour


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 :

Code TPL :
{@hello.world}


Code PHP :
$template->add_lang(LangLoader::get('meslangues', 'monmodule'));


Le fichier de langue associé se trouvant dans le répertoire /monmodule/french/meslangues.php

Code PHP :
$lang = array('hello.world' => 'Bonjour');


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.



Conditions


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.



Condition simple


Le template


Code TPL :
# IF VAR1 #
la variable "VAR1" vaut TRUE
# ELSE #
la variable "VAR1" vaut FALSE
# END #
 


Code PHP :
$template->put('VAR1',  true);


Le résultat :

Code HTML :
la variable "VAR1" vaut TRUE




Condition négative


Code TPL :
# IF NOT DayTime::is_lunch_time() #
Ce n'est pas l'heure de manger
# ELSE #
A table
# END #
 


Le résultat si la statique méthode
DayTime::is_lunch_time()
retourne
false


Code HTML :
A table




Boucles


Boucle simple


Code TPL :
# START boucle #
Code répété dans la boucle
# END boucle #


Code PHP :
$my_loop = array();
for ($i = 0; $i < 3; $i++) {
    $my_loop[] = array();
}
$template->put('boucle', $my_loop);


Le résultat :

Code HTML :
Code répété dans la boucle
Code répété dans la boucle
Code répété dans la boucle




Boucle simple avec des variables


Code TPL :
Nom de la boucle : ${LOOP_NAME}
# START boucle #
${boucle.I} * 2 = ${boucle.2I}
# END boucle #


Code PHP :
$template->put('LOOP_NAME' => 'table de 2');
$my_loop = array();
for ($i = 0; $i < 3; $i++) {
    $my_loop[] = array('I' => $i, '2I' => $i * 2));
}
$template->put('boucle', $my_loop);


Le résultat :

Code HTML :
Nom de la boucle : table de 2
0 * 2 = 0
1 * 2 = 2
2 * 2 = 4




Boucles imbriquées


Code TPL :
# START boucle1 #
Code répété dans la boucle 1: {boucle1.VARBOUCLE_1}
    # START boucle1.boucle2 #
    Code répété dans la boucle 2: {boucle1.boucle2.VARBOUCLE_2}
    # END boucle1.boucle2 #
# END boucle1 #


Code PHP :
$loop1 = array();
for ($i = 1; $i <= 3; $i++) {
   $loop2 = array();
   for ($j = 1; $j <= 2; $j++) {
       $loop2[] = array('VARBOUCLE_2' => $j);
   }
   $loop1[] = array('VARBOUCLE_1' => $i, 'boucle2' => $loop2);
}
$template->put('boucle1', $loop1);
 


Le résultat :

Code HTML :
Code répété dans la boucle 1: 1
    Code répété dans la boucle 2: 1
    Code répété dans la boucle 2: 2
Code répété dans la boucle 1: 2
    Code répété dans la boucle 2: 1
    Code répété dans la boucle 2: 2
Code répété dans la boucle 1: 3
    Code répété dans la boucle 2: 1
    Code répété dans la boucle 2: 2




Inclusions


Inclusion directe


Le template


Code TPL :
Ceci est # INCLUDE  SUBTEMPLATE # dans un autre


Le template à inclure


Code TPL :
un template inclus


Le PHP


Code PHP :
$subtemplate = // un objet de type Template ou View
$template->put('SUBTEMPLATE', $subtemplate);


Le résultat


Code HTML :
Ceci est un template inclus dans un autre




Inclusion dans une boucle


Le template


Code TPL :
Ceci est # START loop # # INCLUDE  loop.SUBTEMPLATE # # END # dans un autre


Le premier template à inclure

Code TPL :
un temp


Le second template à inclure

Code TPL :
late inclus


Le PHP

Code PHP :
$subtemplates = array($subtemplate1, $subtemplate2); // Objets de type Template ou View
$loop = array();
for ($subtemplates as $subtemplate) {
   $loop[] = array('SUBTEMPLATE' => $subtemplate);
}
$template->put('loop', $loop);


Le résultat :

Code HTML :
Ceci est un template inclus dans un autre




Expressions qui écrivent dans le template


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.



Méthodes de templates


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 :



  • resources(String languageFile) : Charge le fichier de langue et l'associé au template.
  • i18n(String messageId) : retourne le message de langue identifier par l'identifiant messageId trouvé dans les fichiers de langues chargés par la méthode resources() ci-dessus. Le caractères XML '<', '>', '"' et '&' sont échappés
  • i18nraw(String messageId) : pareil que i18n, mais n'échappe pas le xml
  • i18njs(String messageId) : pareil que i18n mais échappe les "'" et les "\n"
  • i18njsraw(String messageId) : pareil que i18nraw mais échappe les "'" et les "\n"
  • setvars(String message, String[String] variables) : remplace les occurences des éléments de la forme ":nom" par la valeur associée à la clé "nom" dans le dictionnaire variables
  • escape(String message) : échappe le xml
  • escapejs(String message, boolean add_quotes = true) : échappe le javascript. Par défaut, la chaîne résultante est entourée de 'simples guillements'



Pour plus d'informations sur ces méthodes, il faut se reporter à la PHPDoc de la classe TemplateFunctions



Code TPL :
${i18n('welcome.message')}


Le résultat :

Code HTML :
Le message de bienvenue contenu dans le fichier langue




Méthode statique


Code TPL :
${LangLoader::get_message('step.welcome.message', 'install', 'install')}


Le résultat :

Code HTML :
Bienvenue dans l'assistant d'installation de PHPBoost




Expressions qui n'écrivent pas dans le template


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.



Association d'un fichier de langue


Code TPL :
#{resources('install/install')}
<h1>${i18n('step.welcome.message')}</h1>


Le résultat:

Code HTML :
<h1>Bienvenue dans l'assistant d'installation de PHPBoost</h1>


Dans le cas ou le #{resources()} n'aurait pas été fait, il aurait fallut faire cette association en php de la façon suivante :
Code PHP :
$template->add_lang(LangLoader::get('install', 'install'));


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.



PHP


Il est possible d’inclure du PHP dans les templates, cependant, ceci est à proscrire pour plusieurs raisons :



  1. 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.
  2. 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 .
  3. 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.



Exemple


Code TPL :
ceci est du <?php echo ?PHP?; ?>


Le résultat :

Code HTML :
ceci est du PHP




Les Templates en PHP


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.



Création / instanciation d'un objet Template


A partir d'un fichier : FileTemplate


Code PHP :
$my_template = new FileTemplate('mymodule/mytpl.tpl');


Ce bout de code va chercher à créer un objet Template en utilisant le premier fichier de template existant.



  1. /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.
  2. /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.





A partir d'une chaîne de caractère : StringTemplate


Code PHP :
$my_template = new StringTemplate('Ceci est mon template');




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.



Assignation automatique


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 :



  • THEME : le nom du dossier du thème courant
  • LANG : le nom du dossier de la langue courante
  • IS_USER_CONNECTED : true si l’utilisateur est connecté
  • IS_ADMIN : true si l'utilisateur est un administrateur
  • IS_MODERATOR : true si l'utilisateur est un modérateur
  • PATH_TO_ROOT : le chemin jusqu’à la racine de PHPBoost
  • TOKEN : le token de session permettant de se prémunir des attaques CSRF. Pour plus d’informations, lire Cross-Site Request Forgery





Compatibilité


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

Cette page a été vue 5852 fois