Dernière news le 19/04/2012

PHPBoost

Support

Téléchargements

Développement

Communauté

Annonces
Question aléatoire

Qu'est-ce que PHPBoost ?
Livre d'or

Par koopa'z

Bien que j'ai pas toute les fonctionnalités, phpboost est canon !

Livre d'or

Mini sondage
Etes-vous satisfait du support PHPBoost ?










Résultats

 
[4.0] Système de templates
 



Afin d'offrir de nouvelles possibilités, le moteur de template de PHPBoost 3.1 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 pourrait être interprétés par le moteur de template en les faisant précéder par un antislash : “\”.

La liste de ces caractères spéciaux qu'il peut être nécessaire d'échapper est la suivante : \, $, #, {, }

Variables


Le moteur de template supporte différents types de variables. Dans cette partie, nous détaillerons les variables simples et les variables de langues. Les variables de boucles ne seront pas abordées dans cette partie mais dans la partie concernant les boucles.

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. Ce langue sera déterminée à 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. Par exemple, ceci est équivalent :
Code TPL :
{@hello.world}

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

Le fichier de langues associé se trouvant dans le répertoire /monmodule/french/meslangues.php
Code PHP :
$lang = array('hello.world' => 'Bonjour');

Deuxièmement, la variable de langue est appelé en utilisant la syntaxe @nomDeLaVariableDeLangue. Cette syntaxe est un raccourci pour l'appel suivant i18n('nomDeLaVariableDeLangue'). Cette seconde méthode sera couverte plus en détails dans la partie méthode de template.

Conditions


Le moteur de template 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éthodes 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 comprends bien l'intérêt des expressions pour modifier la mise en page de 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 maintenance futur du module beaucoup plus compliqué, car en plus de changer la logique dans le code PHP du module, il faudra également retravailler de façon appronfondi 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 ailleur en donnant un rendu sous forme de chaîne de caractère. Ce second cas rend très compliquée la gestion des echos qui pourraient être fait dans le code PHP appelé.
    La solution utilisée par le moteur de template 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ès 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 était 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 de les 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 si 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 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 certains nombre de variables sont par défaut assignés au template. En voici la liste :

  • THEME : le nom du dossier du theme courant
  • LANG : le nom du dossier de la langue courante
  • IS_USER_CONNECTED : true si l’utilisateur est connecté
  • 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 http://fr.wikipedia.org/wiki/Cross-site_request_forgery


Compatibilité


Le moteur de template 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 3.1 (à de rares exceptions près).

 
Cette page a été vue 281 fois
Annonces