Utilisation d'un moteur de templates : Talus' TPL

Introduction du cours

Bonjour à tous. :)

Si vous venez ici, c'est par envie d'en savoir plus sur les moteurs de templates, et en particulier sur l'un d'entre eux : Talus' TPL. Comme vous l'avez sans doute remarqué, il existe déjà des tutos sur d'autres moteur de templates : Twig (voir le tuto) ou encore Smarty (voir le tuto). Ce tuto n'a pas pour but de leur faire de la concurrence mais de vous initier à un autre moteur existant. Il utilise une syntaxe de type XML.

Pré-requis :

• avoir lu les cours de M@teo21 en entier, toujours mieux pour avoir de bonnes bases ;

• avoir PHP 5.1 (ou plus) installé sur son serveur ;

• un petit plus : avoir lu le tutoriel de vyk12 sur la POO en PHP.

Sur ce, je vous souhaite une bonne lecture à la découverte de ce script.

Téléchargement et découverte

Eh, attends : c'est quoi, un moteur de templates ?

Ah, j'allais oublier. :D 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 :

<h1>Les news du site</h1> <?php // $pdo : instance de PDO, initialisée par vos soins $q = $pdo->query("SELECT id, auteur, titre, DATE_FORMAT(date, '%d/%m/%Y %Hh%i') AS date_formatee, contenu FROM news ORDER BY date DESC"); foreach($q as &$data){ echo ' <div class="news"> <h2>' . $data['titre'] . '</h2> <p>News postée le '.str_replace(' ', ' à ', $data['date_formatee']).' par ' . $data['auteur'] . '</p> <p>'.$data['contenu'].'</p> </div>'; } $q = null;

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... et est constitué à 90% d'echo, et autres if / foreach.

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 en 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 à la logique, 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 (cet autre tutoriel pourra vous en apprendre plus).

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.12. C'est avec celle-ci que nous allons travailler. Ce que je vous apprendrai ici sera valable avec toutes les versions après celle-ci, sauf qu'il est possible que quelques fonctionnalités récentes ne soient pas évoquées. J'essaierai de maintenir le tutoriel à 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.12). Dans le premier message du sujet, vous trouverez les liens pour télécharger le script en .tgz ou en .zip. Pensez à revenir régulièrement pour vous tenir à jour.

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. Notez le dossier "lib" à la racine de l'archive : c'est celui-ci qui nous intéresse. Libre à vous de le renommer comme bon vous semble (comme includes, libs, etc.).

Aucune installation n'est nécessaire, il suffira d'inclure le script PHP principal contenu dans l'archive (soit, par défaut, /lib/Talus_TPL/Engine.php) dans vos pages PHP. Les autres fichiers .php contenus dans le répertoire lib/Talus_TPL/ seront inclus automatiquement suivant les besoins du moteur... et vous retrouverez, à la racine de l'archive, des fichiers d'informations tels que le changelog ou encore la licence du moteur.

Notions de base

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 :p ). Je vous expliquerai rapidement tout ce qui est utile ici à ce propos.

Création de l'objet

Voici le code minimal permettant de créer l'objet Talus_TPL évoqué plus haut :

<?php $tpl = new Talus_TPL_Engine($dossier_templates, $dossier_cache); ?>

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 :

<?php echo dirname(__FILE__); ?>

__FILE__ est une constante contenant automatiquement le nom du fichier courant. Alors, pour inclure un fichier situé dans un dossier parent, je fais :

<?php include dirname(__FILE__).'/../fichier.php'; ?>

Notez que depuis la version 5.3 de PHP, il est possible de simplement utiliser la constante __DIR__.

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

<?php $tpl = new Talus_TPL_Engine(dirname(__FILE__).'/templates/', dirname(__FILE__).'/cache/'); ?>

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.

Ça marche pas ton code, tu m'as bien eu. :'(

Ah, en effet. Mais vous devriez savoir pourquoi. :)
...
...
Si vous avez trouvé, bravo. Il suffisait en effet de penser à inclure le script contenant la classe PHP, lib/Talus_TPL/Engine.php.

Création des deux fichiers

Si vous avez bien tout compris, chaque fichier PHP va se trouver scindé en deux : la partie logique du code (en PHP toujours), et le fichier de template (utilisant la syntaxe de Talus' TPL). Avec Talus' TPL, le fichier de template porte l'extension .html. Sa syntaxe est de type XML. Pour plus d'infos, ce tutoriel de Tangui fait un point complet sur le 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. Une fois la conversion effectuée, elle restera en cache (d'où l'utilité du dossier cache !), et le fichier résultant sera exécuté tel quel.

Tout code PHP dans le template sera affiché tel quel, et ne sera donc pas exécuté !

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.

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édiaire est stocké dans le dossier de cache défini à l'instanciation de Talus_TPL_Engine. Vous pouvez forcer la compilation à se reproduire en spécifiant le second argument de parse() à false.

Lorsque vous appelez la méthode parse() de votre objet Talus_TPL_Engine (que j'instancie toujours dans une variable $tpl, question d'habitude), vous devez spécifier le nom du fichier de template à parser. 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). Voici donc un schéma à retenir :

<?php // Création de l'objet de template $tpl = new Talus_TPL_Engine(dirname(__FILE__).'/templates/', dirname(__FILE__).'/cache/'); /* Diverses opérations que nous allons voir par la suite */ // Parsage ! $tpl->parse('template.html');

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.

Utiliser des variablesAffecter 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 d'une fonction au nom simple à retenir pour assigner des variables : Talus_TPL::set(). Elle peut s'utiliser de deux manières :

<?php // Première méthode : on assigne 'abcd' à VAR $tpl->set('VAR', 'abcd'); // Variante : on assigne 'abcd' à VAR par l'intermédiaire d'une variable PHP $texte = 'abcd'; $tpl->set('VAR', $texte); // Seconde méthode : on assigne des variables multiples via un array $tpl->set(array('VAR1'=>'abcd', 'VAR2'=>'efgh', 'AUTRE_VAR'=>12.5));

Quelques remarques donc sur ce code.
La fonction Talus_TPL::set() prend deux arguments : le nom de la variable qui sera utilisée côté template, et sa valeur. 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... sauf un objet. Les variables côté PHP et côté template ne doivent pas nécessairement porter le même nom.

L'assignation avec Talus_TPL::set() permet aussi d'affecter plusieurs variables en une seule fois. La fonction reçoit un array, avec dans les clés le nom de la variable côté template et dans les valeurs... sa valeur.

Côté template

L'affichage d'une variable est très simple :

{VAR}

affichera le contenu de la variable VAR. Vous pouvez aussi de la même manière accéder aux clés d'un array :

{VAR[1]['cle1']}

... ainsi qu'aux propriétés d'un objet (pour peu qu'elle soit publique, ou que la méthode __get() soit correctement implémentée) !

{VAR->attribute}

Pour des raisons techniques (limitation des expressions régulières), il est pour le moment impossible d'utiliser le symbole ']' dans la clé d'un array.

Échapper une variable

Et si je veux afficher {VAR} dans mon fichier .html, sans que cela soit interprété ?

Pour que VAR ne soit pas affichée, utilisez cela :

{\VAR}

Il s'affichera alors :

Citation : Rendu

{VAR}

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 et autres fonctionnalités de la syntaxe Talus' TPL.

{$VAR}

L'instruction renvoie la valeur de la variable, mais sans l'afficher. Un peu comme si vous faisiez de la manière suivante :

<?php $VAR; 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. :magicien:

{__CONSTANTE__}

Il suffit donc juste de l'entourer de deux tirets bas __. Pour obtenir leur valeur, même topo que précédemment :

{__$CONSTANTE__}

A propos de constantes, vous pouvez également utiliser des constantes de classes comme suite :

{__Classe::CONST__} {__$Classe::CONST__} Utiliser les filtres

Un ajout intéressant de Talus' TPL par rapport à d'autres moteurs de templates est l'utilisation de filtres. Ils fonctionnent de la même manière que dans Django. Leur rôle est d'appliquer une transformation à la variable. Ils peuvent s'utiliser indifféremment à l'affichage ou à la récupération d'une variable. Pour les utiliser, ajoutez-les à la suite de la...