Le moteur de template de Jelix est disponible en version standalone, c'est à dire une version qui ne nécessite pas d'installer le framework Jelix.
Cette page parle principalement de la version 1.0pre. Elle ne concerne pas la version 1.0 beta de jTpl standalone.
De plus cette version 1.0pre est obsolète. En effet, le projet a été renommé sous le nom “Castor”, et une version 1.0 est sortie en novembre 2015. Elle est disponible via Composer. Castor a une API légèrement différente. Voyez plutôt la documentation sur github.
Ce qui manque dans cette version mais prévue plus tard :
Décompressez l'archive où vous voulez. On considère dans la suite que vous avez renommé le répertoire de jtpl en jtpl/.
Dans vos scripts php, incluez le fichier jtpl_standalone_prepend.php. Exemple:
<?php include ("jtpl/jtpl_standalone_prepend.php");
Un objet jTplConfig est à votre disposition pour paramétrer le moteur de template.
Les propriétés les plus importantes:
$templatePath : indique le chemin complet vers le répertoire où se trouve les templates. par défaut, il s'agit du répertoire jtpl/templates/.$cachePath : indique le répertoire qui contiendra les fichiers compilés de jTpl. par défaut, jtpl/temp/.Exemple:
jTplConfig::$cachePath = realpath(JTPL_PATH.'temp/') . '/'; jTplConfig::$templatePath = realpath(JTPL_PATH.'templates/') . '/';
Notez que le chemin doit toujours se terminer par “/”.
Il y a d'autres propriétés, voir les commentaires dans le fichier jtpl_standalone_prepend.php
L'objet jTpl sert à générer le contenu indiqué dans un fichier template, à partir des données que vous lui fournissez, et en suivant les instructions contenues dans le template.
Pour commencer à l'utiliser :
$tpl = new jTpl();
Voici les méthodes les plus importantes à connaître.
$tpl->assign($nom, $valeur);
Cette méthode vous permet de créer une variable de template. Une variable de template n'est accessible qu'au niveau du template. C'est avec cette méthode que vous pouvez donc passer des données (valeurs statiques, objets, itérateurs, etc..) au template pour vous en servir à générer du contenu.
Vous pouvez également créer ou modifier une variable directement dans le fichier tpl en utilisant.
{assign $nom = 'valeur'}
Important : le nom de la variable de template doit respecter les conventions de nommage des noms de variables PHP. Par exemple, le nom ne doit pas contenir de tiret ou d'autres signes de ponctuations. Il ne doit contenir que des lettres avec éventuellement des chiffres et le caractère souligné (_).
Idem que assign, à ceci prés que la valeur est passée par référence, ce qui évite une copie et donc une consommation de la mémoire excessive. À utiliser par exemple si vous passez des tableaux volumineux.
Idem que assign, mais la valeur est assignée à la variable uniquement si celle-ci n'existe pas.
Si vous voulez récupérer la valeur d'une variable de template déjà initialisée, vous pouvez utiliser cette méthode.
$value = $tpl->get('foo');
Une fois que les variables sont initialisées, vous pouvez appeler la méthode fetch pour générer le contenu du template et le récupérer. Vous donnerez à cette méthode le nom du fichier de template.
$contenu = $tpl->fetch('mytemplate.tpl');
Il existe une autre méthode, display, qui évalue le contenu du template et l'envoi directement au navigateur.
$tpl->display('mytemplate.tpl');
Les templates sont des fichiers portant l'extension “.tpl” et se trouvant dans le répertoire des templates, déclaré dans la configuration.
Un fichier de template contient du HTML, du XUL ou ce que vous voulez d'autres. Il contient aussi des instructions pour incorporer des valeurs que vous aurez fournies, des instructions pour générer répétitivement des portions de HTML, XUL etc.
La syntaxe utilisée dans jTpl est à mi chemin entre celle utilisée dans le moteur de template Smarty, et la syntaxe PHP. Le but étant d'avoir des templates suffisamment lisibles, faciles à modifier en n'imposant pas une syntaxe trop éloignée de PHP, tout en proposant des facilités que ne possède pas PHP et propres à jTpl.
Les instructions jTpl sont spécifiées entre accolades : {instruction....}.
Si vous voulez inclure des accolades dans le source, sans que ce soit interprété par jTpl, vous pouvez utiliser {ldelim} pour {, et {rdelim} pour }. Si vous avez un bloc contenant plusieurs accolades (comme du code javascript), vous pouvez aussi utiliser l'alternative avec {literal} :
<script type="text/javascript"> {literal} for(i=0;i<max;i++) { if(foo){ ...} } {/literal} </script>
Si vous voulez mettre des commentaires qui ne seront pas inclus dans le contenu généré, utilisez {*...*}
<p>bla bla</p> {* ceci est un commentaire *}
Vous pouvez étaler une instruction sur plusieurs lignes :
<div> {zone 'foo~bar', array( 'foo1'=>$foo1, 'foo2'=>$foo2)} </div>
Une expression jTpl est identique à une expression PHP et renvoie, comme dans PHP, une valeur. Vous pouvez utiliser les opérateurs PHP classiques, les objets, etc… Vous utiliserez les expressions au niveau des arguments des instructions jtpl. On peut utiliser les variables de templates qu'on a passé à jTpl, comme des variables classiques en PHP. Voici un exemple d'expression simple :
$nom_variable_de_template
Une expression peut contenir aussi des clés de locales, en utilisant une syntaxe spécifique à jTpl. Ces clés doivent être placé entre “@”. jTpl ira chercher la chaîne correspondante dans le fichier de locales correspondant à la langue :
@cle.chaine.localisee@."fooo bar"
La chaîne correspondant à cle.chaine.localisee sera récupérée et concaténée à "fooo bar".
À l'intérieur du nom de la clé, on peut indiquer un nom de variable de template. Cela permet ainsi de construire un nom de clé dynamiquement.
@cle.chaine.$nom_variable_template.autre@."fooo bar"
si $nom_variable_template vaut "foo", alors la clé sera "cle.chaine.foo.autre".
TODO: pas de documentation sur le fonctionnement et la configuration de la localisation pour le moment.
Il faut mettre l'expression entre accolades. Elle doit commencer par un nom de variable ou par un sélecteur de locale :
{$mavariable}
{$mavariable * 3}
{$mavariable." - ".@mod~message.ok@}
{@une.cle.de.locale@."-".$uneAutreVariable}
{@une.cle.$dynamique@."-".$uneAutreVariable}
Ceci est équivalent en php à
<?php echo $mavariable; ?> <?php echo $mavariable * 3; ?> <?php echo $mavariable." - ".jLocale::get("mod~message.ok"); ?> <?php echo jTplConfig::$localesGetter("une.cle.de.locale")."-".$uneAutreVariable; ?> <?php echo jTplConfig::$localesGetter("une.cle.".$dynamique)."-".$uneAutreVariable; ?>
Pour les expressions plus complexes ne commençant pas par un nom de variable ou de locale, on peut utiliser le signe “=” :
{=$mavariable} {=intval($mavariable) * 65}
Pour apporter une certaine facilité, des variables de templates prédéfinies sont disponibles :
Un modificateur est en fait une fonction qui va modifier le contenu qui va être affiché. Cela fonctionne comme dans Smarty. On peut mettre plusieurs modificateurs à la suite :
{$unevariable|upper}
{$unevariable|upper|escxml}
{$uneUrl|escurl}
Ceci est en fait équivalent à :
<?php echo strtoupper($unevariable);?> <?php echo htmlspecialchars(strtoupper($unevariable));?> <?php echo rawurlencode($uneUrl);?>
Les modificateurs indiqués en exemple sont de simples alias à des fonctions existantes, mais vous pouvez créer vos propres modificateurs, pouvant accepter plusieurs arguments.
Les modificateurs existants et leur équivalent php :
D'autres sont fournis. Voir la liste sur la référence API.
Il peut y avoir des modificateurs qui acceptent des paramètres. Vous devez mettre ceux-ci, séparés par des virgules (,) , après le nom du modificateur et deux-points (:).
Exemple avec le modificateur date_format :
<p>la date est {$myDate|date_format:"%b %e, %Y"}.</p>
Elles sont équivalentes à celle en PHP, excepté que les expressions ou conditions n'ont pas besoin d'être encadrés par des parenthèses.
{if condition_1}
// code ici
{elseif condition_2}
// code ici
{else}
// code ici
{/if}
Notez aussi qu'il peut y avoir des plugins pour faire des “if” spécifiques comme iftruc 'machin' pour tester quelque chose de spécifique. Avec tout ces plugins en “if”, vous pouvez utiliser un else.
Boucle conditionnelle:
{while condition}
// code ici
{/while}
Boucle sur un iterateur ou un tableau:
{foreach $iterateur_ou_tableau as $cle => $valeur}
// code ici
{/foreach}
{for expression}
// code ici
{/for}
L'expression est bien sûr semblable à celle du “for” en PHP.
Ce sont des fonctions classiques mais appelables uniquement dans un template. Certaines sont disponibles en standard et vous pouvez en réaliser en créant un plugin de template. Leur syntaxe est :
{nom_fonction paramètres}
Les paramètres sont des expressions jTpl, donc similaires aux expressions PHP. Cependant, contrairement en PHP, il ne faut pas entourer les paramètres par des parenthèses.
Si vous voulez avoir des fonctions ou modificateurs supplémentaires, vous pouvez réaliser des plugins de templates. Voir la documentation sur ce sujet. C'est assez simple à faire.
Une deuxième solution est de déclarer les modificateurs ou fonctions à la volée au moteur de template. Vous avez pour cela deux méthodes registerModifier() et registerFunction(). Vous leur indiquez le nom “jtpl” du modificateur ou de la fonction, ainsi que le nom de la fonction php qui sera executée par le template. Cette fonction doit accepter les même arguments que pour une fonction de plugin de template.
Il existe une balise assez spéciale : {meta}. Elle n'influence pas l'interprétation du template, ne génère aucun contenu, et ne peut être influencée par d'autres instructions de template (la mettre dans un {if} par exemple ne sert à rien, elle sera interprétée quoi qu'il arrive). Cette balise permet simplement de fournir des informations sur le template qui pourraient être réutilisées par un programme utilisant le template, avant que le contenu du template soit fetché ou affiché.
{meta nom expression}
Exemple :
{meta auteur 'laurent'}
On peut en mettre plusieurs bien sûr. Ces informations sont récupérables via la méthode meta() de l'objet jTpl :
$tpl = new jTpl(); $metas = $tpl->meta('le_fichier_template'); echo $metas['auteur']; // affiche 'laurent'
Note : si vous utilisez une variable dans l'expression dans un tag meta, cette variable doit être créée via la méthode assign() de l'objet jtpl, et non pas avec un tag jtpl comme {assign ...}.
Dans un template, nous avons vu que nous pouvons utiliser {@truc.foo@} pour inclure des chaînes localisés. Cependant, il peut arriver qu'il y en ai beaucoup dans un même template, pouvant rendre alors celui-ci pas très lisible, et surtout plus lent à s'afficher.
Une solution existe : créer des templates pour chaque langue. Bien sûr, cela fait de la duplication de code, aussi, à vous de peser le pour et le contre : maintenance versus performance.
Pour faire un template pour chaque langue, créer des sous-repertoires dans le repertoire de templates, et qui ont pour nom le code de la langue. Exemple, dans un module: templates/fr_FR, templates/en_EN etc.. Et placez y dans chacun d'eux un exemplaire de votre template traduit.
Les templates jTpl sont “compilés” sous forme de fichiers purs PHP, et stockés dans un cache pour améliorer les performances. Vous pouvez donc voir l'équivalence d'un de vos fichiers templates dans temp/.
Vous pouvez créer aussi des plugins de templates, pour ajouter vos propres “tags” dans la syntaxe jtpl. Voir http://docs.jelix.org/fr/manuel-1.1/plugins/tpl.