V. Développer avec PHPBoost

Système de Templates

Dernière mise à jour : 12/12/2013 à 20h29
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 8746 fois