Utilisation d'un moteur de templates : Talus' TPL

Ah, j'allais oublier. Je vais donc brièvement vous présenter l'utilité d'un tel script.

Rappels / notions concernant un moteur de templates

En général, vous avez souvent un seul fichier par page, qui contient aussi bien le code d'affichage que les requêtes à MySQL notamment, comme ceci :

Code : PHP - Script de news basique

Un moteur de templates vous permet de séparer ce fichier en deux. L'un est chargé de l'affichage du code xHTML, l'autre d'effectuer les requêtes à MySQL, et d'appeler le second fichier.

Vous lirez souvent "utiliser PHP comme moteur de templates". Cela signifie que le second fichier contient alors du code PHP, et qu'il est appelé par un include.

Ce que nous allons voir ici consiste à remplacer le code PHP par un pseudo-langage, présentant les avantages suivants.

• Ce langage est assez simple. On retrouve l'équivalent d'expressions PHP. Cela rend ce langage idéal pour être utilisé par un graphiste, qui n'a ainsi pas à apprendre à utiliser PHP, mais juste ce langage, forcément plus simple.
• Nous venons donc à un deuxième avantage : la présentation est totalement séparée de la logique du code, et de la récupération des données. On peut toucher au style du site sans toucher au code PHP, et vice-versa.

Mais bien entendu, il y a des inconvénients à utiliser un tel système.

• Le script pourra être plus long à charger. Néanmoins, le moteur que je vais vous présenter reste très léger.
• Un autre langage que PHP doit évidemment être appris.

Notez enfin qu'un tel moteur s'interface très bien avec un modèle MVC (un autre de mes tutos décrivant cette structure).

Présentation et téléchargement de Talus' TPL

Talus'TPL est un moteur portant le nom de son concepteur, Talus. Il est disponible depuis le 2 février 2008, date de sortie de sa version 1.0.0. Il a depuis d'autres versions. La dernière est la 1.2.0. C'est avec celle-ci que nous allons travailler. Ce que je vous apprendrai ici sera valable avec toutes les versions, sauf qu'il est possible que quelques fonctionnalités récentes ne soient pas évoquées. J'essaierai de maintenir le tuto à jour autant que possible.

Commencez donc par télécharger le script sur son forum officiel, rubrique Releases. Prenez la version la plus récente (je rappelle qu'au moment de l'écriture, la version la plus récente était la 1.2.0). Dans le premier message du sujet, vous trouverez les liens pour télécharger le script en .tar.gz ou en .zip.

Ensuite, décompressez l'archive et mettez-la sur votre site avec votre logiciel FTP favori. Vous pouvez mettre les fichiers à la racine ou bien dans un sous-dossier (comme includes, libs, etc.). Notez que vous n'aurez besoin que d'un des deux fichiers require_ftp.php et require_sql.php. Ils servent à gérer le cache. Si vous pouvez écrire dans des dossiers depuis PHP, préférez utiliser require_ftp.php. Sinon, utilisez require_sql.php. Les caches seront alors stockés en base de données (la requête pour créer la base se trouve dans le fichier ).

Aucune installation n'est nécessaire, il suffira d'inclure ces deux scripts (soit talus_tpl.php et require_ftp.php, soit require_sql.php) dans vos pages PHP. Les autres fichiers ne sont pas nécessaires, il y a notamment les différences entre la version courante et la version précédente.

Nous allons donc commencer par voir comment utiliser les fonctions principales de Talus' TPL. La première chose à faire est d'instancier un objet de type Talus_TPL. Ce vocabulaire est celui de la Programmation Orientée Objet (ou POO pour les intimes ). Je vous expliquerai rapidement tout ce qui est utile ici à ce propos. Pour en savoir plus, référez-vous au tuto de Keeper.

Création de l'objet

Voici le code permettant de créer l'objet Talus_TPL évoqué plus haut :
Code : PHP
En POO, l'opérateur new est indispensable pour créer une instance de l'objet. Pour définir les deux dossiers, j'ai personnellement recours à la fonction dirname. Souvent, on se demande par rapport à quoi les chemins doivent être définis (dans un include situé dans un fichier déjà inclus lui-même, par exemple ). Ce bout de code affiche le chemin complet du fichier :
Code : PHP
__FILE__ est une constante contenant automatiquement le nom du fichier courant. Alors, pour inclure un fichier situé dans un dossier parent, je fais :
Code : PHP

Tout ça pour dire que je vais employer la méthode suivante pour définir les deux dossiers. Voici donc le code final :
Code : PHP

Je me place donc dans mon cas personnel où le fichier se trouve à la racine du site, mes templates dans un dossier /templates/ et mon dossier de cache dans /cache/. Adaptez bien sûr à votre cas.


Ah, en effet. Mais vous devriez avoir trouvé pourquoi.
...
...
Si vous avez trouvé, bravo. Il suffisait en effet de penser à inclure le script contenant la classe PHP talus_tpl.php, puis le require_xxx.php (j'en avais déjà parlé, et vous y avez peut-être pensé tout seuls ).

Création des deux fichiers

Si vous avez bien tout compris, chaque fichier PHP va se trouver scindé en deux : un fichier PHP différent et un fichier de templates. Avec Talus' TPL, le fichier de template porte l'extension .html. Sa syntaxe est de type XML. Pour plus d'infos, ce tuto de Tangui fait un point complet sur le langage XML. La syntaxe des fichiers de template ainsi que les fonctions PHP seront toutes détaillées par la suite.

Sachez que dans le fichier de template, vous aurez en gros deux types de structures :

• du code xHTML qui sera conservé,
• du code utilisant la syntaxe particulière de Talus' TPL, qui sera converti en PHP lors de l'affichage, de façon transparente.

Affecter un template à un script, et afficher le template

Dans cette partie, nous allons voir quelque chose de primordial : comment afficher un fichier de template. En effet, il ne suffit pas de faire un include. Vous devez passer par une méthode dédiée.

Pour affecter un fichier à un objet Talus_TPL (que j'instancie toujours dans une variable $tpl, question d'habitude), on doit passer par la fonction set_file.

Code : PHP

Le chemin est -par rapport au chemin des fichiers de templates- indiqué lors de la création de $tpl (reportez-vous ci-dessus si ce n'est pas clair ).

Enfin, la méthode parse vous permet de... parser le template. Comprenez que lorsque vous faites cela, toute la syntaxe spécifique de Talus' TPL est convertie en PHP, qui est enregistré (pour éviter de le retraduire à chaque fois). Ce code PHP est ensuite exécuté. Le fichier PHP est modifié à chaque fois que votre template change, de façon automatique. Ce fichier intermédiare est stocké dans le dossier de cache défini à l'instancitation de Talus_TPL.
Il existe des paramères optionnels à cette fonction, et une autre fonction de parsage, mais nous la verrons plus tard. Retenez juste ce schéma pour l'instant :

Code : PHP

Nous sommes maintenant prêts à voir ces fameuses instructions. Vous pourrez alors apprécier la puissance de ce script, et juger de ses différences par rapport à d'autres systèmes.

Affecter et afficher une variable

Une des opérations les plus simples à faire avec votre nouveau moteur de templates est de pouvoir afficher des variables. Comme toute opération (ou presque), elle se passera en deux temps :

• vous devrez commencer par ajouter un morceau de code côté PHP pour assigner la variable au moteur ;
• ensuite, il faudra l'afficher depuis votre template.

Côté PHP

Vous disposez de deux fonctions pour assigner des variables.
Code : PHP

Quelques remarques donc sur ce code.
La fonction assign_var prend deux arguments : le nom de la variable qui sera utilisée côté template, et sa valeur. Le nom de la variable doit toujours être en majuscules, pour permettre une meilleure lisibilité des fichiers .html. Les variables suivent les mêmes règles de nommage que pour PHP. Vous pouvez ensuite assigner une valeur de n'importe quel type, donc aussi bien un array qu'une chaîne de caractères qu'un entier. Les variables côté PHP et côté template ne doivent pas nécessairement porter le même nom.
L'assignation avec assign_vars permet d'affecter plusieurs variables en une fois. La fonction reçoit un array, avec dans les clés le nom de la variable côté template et en valeur sa valeur ( ).

Côté template

L'affichage d'une variable est très simple :
Code : XML
affichera le contenu de la variable VAR. Vous pouvez aussi de la même manière accéder aux clés d'un array :
Code : XML

Échapper une variable

Pour que VAR ne soit pas affichée, utilisez cela :
Code : XML
Il s'affichera alors :
Citation : Rendu
On dit qu'on échappe la variable.

Utiliser la variable sans l'afficher

Pendant que j'y suis, une autre chose à connaître est la manière d'obtenir la variable sans l'afficher. Cela servira quand nous verrons les conditions.
Code : XML
L'intruction renvoie la valeur de la variable, mais sans l'afficher.

Constantes

Enfin pour finir ce chapitre, voyons l'utilisation des constantes. Vous n'avez pas à les assigner à nouveau, elles sont accessibles depuis le fichier de template sans code additionnel côté PHP.
Code : XML
Il suffit donc juste de l'entourer de deux tirets bas __. Pour obtenir leur valeur, même topo que précédemment :
Code : XML

Vous vous demandez sans doute à ce stade comment effectuer des tests simples sur les variables. Bien sûr que Talus' TPL vous l'autorise, et nous allons le voir maintenant.


Il existe trois balises de noms, identiques à ceux en PHP, à employer côté template. Notez qu'il n'y a aucune manipulation spéciale à effectuer du côté de PHP. Ces balises sont :

• if
• elseif
• else.

Il y a un argument à passer aux balises if et elseif : la condition. En pratique, procédez comme suit (je pars du principe que j'ai créé une variable VAR dans le code PHP) :
Code : XML

Simple, non ? Notez au passage l'utilisation de l'échappement pour afficher le nom de la variable. N'oubliez pas non plus le signe dollar $ devant la variable (on ne veut pas l'afficher mais récupérer sa valeur).

Justement, ça tombe bien, j'y viens. Les boucles sont très utilisées, que ce soit pour parcourir des array, ou récupérer un résultat provenant d'une base de données contenant plusieurs lignes.

Parcourir un array avec foreach

Vous êtes sans doute habitués à vous balader dans des array avec la fonction foreach en PHP. Eh bien, bonne nouvelle, vous pouvez faire la même chose avec Talus' TPL du côté des templates. La syntaxe est cette fois-ci un peu différente de celle utilisée en PHP. Vous utiliserez la balise foreach, mais en lui fournissant un seul argument : l'array à parcourir.

Code : XML

Une fois entre les deux balises du foreach, vous pouvez accéder soit à la clé, soit à la valeur contenue dans l'array. À chaque itération, ces deux données changent bien évidemment, comme en PHP. Vous devez donc concrètement spécifier si vous voulez la clé ou la valeur, et de quel array (cela vous permet d'imbriquer des foreach).
Code : XML

Vous pouvez donc soit afficher les valeurs des variables ({KEY,ARRAY} et {VALUE,ARRAY}), soit obtenir leurs valeurs pour effectuer des tests dessus ({KEY,$ARRAY} et {VALUE,$ARRAY}).

Notez pour finir que la possibilité de renommer un array est apparue, comme en PHP. Cela vous permet d'imbriquer des array, éventuellement identiques. Procédez comme suit :
Code : XML

Utiliser des blocs

Notez que vous pouvez dès à présent afficher des données obtenues depuis votre base de données en les stockant dans un array et en les affichant grâce à l'instruction vue ci-dessus. Mais il y a une autre méthode, adaptée spécifiquement à ce cas : les blocs. Chaque bloc est caractérisé par un nom. Vous pouvez lui assigner une valeur que vous récupèrerez via une clé. La différence est que si vous demandez à affecter une valeur à une clé déjà définie, au lieu d'être écrasée, une nouvelle entrée est créée ! De la sorte, vous pouvez affecter diverses variables dans un mysql_fetch_assoc, par exemple. C'est un cas très utilisé. Petit exemple :
Code : PHP

Et pour récupérer ce petit monde :
Code : XML

Vous avez une fois de plus la possibilité d'utiliser {$bloc.ID} pour récupérer la valeur et {\bloc.ID} pour échapper. Nottez aussi la balise blockelse qui affiche son contenu si le bloc n'a pas été exécuté (souvent s'il est vide).
Code : XML

Des variables sont automatiquement affectées au bloc, sans que vous n'ayez rien à faire. Il s'agit de :

• FIRST : booléen indiquant si c'est la première occurence du bloc ;
• LAST : booléen indiquant si c'est la dernière occurence du bloc ;
• SIZE_OF : entier indiquant le nombre d'occurences du bloc ;
• CURRENT : entier indiquant l'occurence courante.

Vous les récupérez de la manière classique :
Code : XML

Enfin, notez la possible imbrication de blocs dans des blocs. Le nom du sous-bloc est alors composé avec les noms des blocs parents à gauche, et en dernier son propre nom, chaque nom étant séparé du précédent par un point. Vous pouvez alors arriver à un bloc : parent.fils.petit_fils.bebe . Pour le récupérer dans le template, spécifiez uniquement le nom du parent le plus proche (donc petit_fils pour bebe, fils pour petit_fils et rien pour parent) :
Code : XML

Vous pouvez inclure un template depuis un autre fichier de template. Il vous suffit d'utiliser la balise include, en envoyant comme argument le chemin vers le template à inclure. Enfin, vous pouvez spécifier si vous désirez ne l'inclure qu'une fois (à savoir que s'il a déjà été inclus, il ne pourra pas l'être à nouveau plus tard ; c'est l'équivalent de include_once / require_once en PHP ), en envoyant un boolean (true ou false);.

Code : XML

Simple, clair et efficace.

Avant de finir notre étude théorique du moteur de template, nous allons passer en revue deux autres syntaxes très pratiques.

Manipuler des variables depuis le template

Vous avez la possibilité de manipuler les variables directement depuis le template. En général, il n'est pas conseillé de le faire, car vous perdez ainsi la séparation entre code logique et code d'affichage. Cependant cette fonction existe, il peut être bon de la connaître quand même.

Code : XML

Avec ce petit code, on affecte à la variable VAR la valeur "une chaine de caractères". Notez que vous n'avez pas besoin d'utiliser la syntaxe avec les accolades {}, mais que le nom doit rester en majuscules. Si une telle variable existait déjà, son ancienne valeur est écrasée ; sinon une nouvelle variable de template est créée.

Vous pouvez également procéder de même dans les blocs (voir la partie sur les boucles, si vous avez déjà tout oublié les concernant ) :

Code : XML

Utiliser des fonctions utilisateur

Derrière ce nom se cache une fonctionnalité très pratique de Talus' TPL. Vous pouvez en effet ajouter vos propres fonctions au moteur de templates, ce qui le rend extensible très facilement. Il y a des tâches que nous avons à effectuer couramment dans des templates. Je prendrai ici l'exemple de l'affichage d'un pseudo, coloré avec la couleur de son groupe et menant vers le profil. Vous ferez en général quelque chose comme :

Code : PHP

Mais si vous voulez changer cet affichage pour changer le lien vers le profil par exemple, vous devrez changer tous vos templates. Une meilleure solution consiste à utiliser une fonction utilisateur !

La fonction se caractérise par un nom et une liste d'arguments (ou pas ). Entre les balises de définition, vous spécifiez le texte qui sera affiché à son appel. La fonction se définit et s'utilise uniquement côté template.

Code : XML

Ceci est un exemple des seules capacités de la fonction. Comme d'habitude, les arguments doivent être nommés en respectant les règles de nommage des variables. Vous pouvez utiliser les variables passées en argument, ou bien des variables globales à utiliser de la façon suivante :
Code : XML

Pour appeler votre fonction, utiliser call, en spécifiant les arguments, dans le même ordre que lorsque vous avez défini la fonction. L'argument donné peut avoir un nom différent de celui utilisé dans la définition de la fonction, comme en PHP.

Code : XML

Vous pouvez bien sûr passer des variables de template à vos fonctions, y compris dans des foreach ou des blocs, où elles révèlent toute leur puissance :

Code : XML

Gestionnaire d'erreurs

Pour cette fonction, vous n'avez rien à faire. Seulement, dès qu'une erreur est rencontrée, au lieu de recevoir un obscure erreur PHP dont la source serait talus_tpl.php, vous avez droit à une erreur PHP plus classique, avec en bonus, les lignes où se situent l'erreur.

A noter que cette fonction est désactivée par défaut car elle bug de temps en temps, pour une erreur en cours de résolution.

Reprenons l'exemple usé jusqu'à la corde du système de news. Je vais vous donner un code PHP "banal", et à vous de l'adapter à ce moteur de template.

Voici le code pour créer une table news avec quelques éléments déjà insérés :

Code : SQL

Copiez-collez ce code dans phpMyAdmin, onglet SQL, pour créer votre table.

Et voici le code PHP. Je ne le commenterai pas ; si vous avez du mal à le comprendre, relisez les cours de M@teo21.

Code : PHP

Bon, maintenant au boulot ! Vous devez me transformer ce script pour y intégrer Talus' TPL. Vous devrez donc créer un second fichier, contenant le template. Bonne chance !




Bien ! Voici maintenant le corrigé, pour comparer nos travaux. Je commence par news.php :
Code : PHP

Le code se comprend facilement si vous avez lu tout ce qui précède. Je considère que le template est dans le même dossier, et que vous diposez d'un dossier cache/ à la racine. Et voici le template news.html :
Code : XML