Documentation : Templates Smarty

Présentation

Smarty est un moteur de templates très répandu. Il offre l'avantage d'une syntaxe simple à comprendre pour des non-informaticiens (graphistes, web-designers).
Commencez par regarder la présentation qui en est faite dans l'introduction.

Nous allons vous présenter ici quelques instructions de base. Pour plus de renseignement, veuillez vous rendre sur le site Smarty.net.

Fichiers de template et inclusion

Les fichiers de template sont de simples fichiers texte, qui sont prévus pour contenir du code HTML.

Vous pouvez très facilement segmenter vos pages en faisant des inclusions de templates.
Par exemple, imaginons que vous ayez deux actions, list et show, qui affichent des pages différentes en utilisant respectivement les fichiers list.tpl et show.tpl. Si ces deux pages affichent le même en-tête de page, il vaut mieux le séparer pour ne pas avoir à le recopier dans chaque page.
Smarty offre la possibilité d'inclure des templates les uns dans les autres grâce à l'instruction include.

Vous pourriez ainsi avoir le fichier header.tpl, qui ressemblerait à ceci :

<html>
<head>
    <title>Titre générique de page</title>
</head>
<body>

    <!-- code de l'en-tête -->
						

Nos deux templates de pages ressembleraient alors à ça :

<!-- fichier list.tpl -->
{include file="header.tpl"}

<h1>LISTE</h1>

</body>
						

<!-- fichier show.tpl -->
{include file="header.tpl"}

<h1>AFFICHAGE</h1>

</body>
						
Variables

Un des premiers besoins est de pouvoir afficher le contenu d'une variable.
Imaginons que le contrôleur contienne le code suivant :

$this->set('name', 'Anakin');
						

Vous pouvez très simplement afficher la valeur de la variable name dans votre template :

{$name}
						

Ce qui aura pour effet d'afficher le texte suivant :

Anakin
						

Listes

Imaginons que votre contrôleur définisse une variable de template qui contient une liste :

$list = array(
    'orange',
    'banane',
    'fraise'
);
$this->set('fruits', $list);
						

Vous pouvez facilement afficher l'une des valeurs de la liste :

{$fruits[2]}
						

Et vous obtiendrez :

fraise
						

Tableaux associatifs et objets

Il est possible d'afficher le contenu d'un élément d'un tableau associatif à partir de sa clé, ou d'un attribut d'un objet à partir de son nom. Par exemple :

$list = array(
    'red'   => '#ff0000',
    'green' => '#00ff00',
    'blue   => '#0000ff''
);
$this->set('colors', $list);
						

Pour afficher une couleur, il suffit d'écrire :

{$colors.red}
						

Ce qui donnera :

#ff0000
						
Conditions

Pour faire du traitement conditionnel, vous pouvez utiliser l'inscription if, qui utilise les variables suivant la syntaxe vue précédemment.

Par exemple, si votre contrôleur définit une variable de template contenant les informations d'un utilisateur :

$user = $this->_dao->get($userId);
$this->set('user', $user);
						

Vous aurez ensuite la possibilité d'afficher un lien seulement si l'utilisateur est un administrateur :

{if $user.isAdmin}
    <a href="/user/show/{$user.id}">Voir mon compte</a>
{/if}
						
Boucles

Il arrive très fréquemment de devoir appliquer un traitement à un groupe d'éléments. Cela se présente habituellement sous la forme d'une liste d'items récupérés de la base de données, que l'on souhaite afficher les uns après les autres.
Pour ce faire, Smarty offre l'instruction foreach.

Imaginons que le contrôleur récupère une liste d'utilisateurs depuis la base de données :

$users = $this->_dao->search();
$this->set('users', $users);
						

Il est très facile de boucler sur tous les utilisateurs pour afficher leur nom :

<ul>
    {foreach from=$users item=user}
        <li>{$user.name}</li>
    {/foreach}
</ul>
						
Échappement

Si une variable contient des caractères spéciaux ("<", ">", "&", ...), il ne faut pas prendre le risque de l'écrire telle quelle dans le template, sous peine de générer un flux HTML non conforme.
Pour cela, Smarty propose le filtre escape, qui convertit à la volée les caractères en question.

Il s'utilise de la manière suivante :

{$name|escape}
						

Vous ne pouvez pas placer directement des caractères accolade ("{", "}") dans un template, car ils seraient interprétés par des instructions Smarty. Il faut donc utiliser l'instruction literal, qui empêche l'interprétation Smarty.

Par exemple, pour écrire du code Javascript dans une page, vous pourriez écrire :

{literal}
    <script type="text/javascript"><!--
        function something() {
            ...
        }
    //--></script>
{/literal}
						
Plugins

Smarty peut être étendu par des plugins, qui permettent par exemple de créer des filtres de manipulation des données.

Par exemple, vous pourriez créer un filtre qui servent à remplacer toutes les lettres "T" par un point (ça ne sert à rien, mais c'est pour l'exemple) :

function smarty_modifier_warp($text{
    return str_replace('T', '.', $text);
}
						

Vous l'utiliseriez ainsi dans vos templates :

{$variable|warp}
						

Pour que votre plugin soit utilisable par Smarty, il faut placer votre fonction dans un fichier nommé modifier.warp.php. Ce dernier doit être situé dans le répertoire lib/smarty/plugins de votre projet.
Dans le cas où vous avez un autre répertoire contenant des plugins Smarty, vous devrez ajouter son chemin dans la configuration du projet (fichier etc/temma.json) :

{
    "x-smarty-view": {
        "pluginsDir": "/chemin/vers/le/répertoire"
    }
}
						

Si vous avez plusieurs répertoires contenant des plugins Smarty, vous pouvez tous les lister :

{
    "x-smarty-view": {
        "pluginsDir": [
            "/chemin/vers/le/répertoire1",
            "/chemin/vers/le/répertoire2",
            "/chemin/vers/le/répertoire3"
        ]
    }
}