Vue Smarty

1Pré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 la documentation Smarty.

2Installation

La vue Smarty est compatible avec les versions 4 et 5 de la bibliothèque.

Référez-vous à la documentation de l'installation de Temma pour savoir comment installer Smarty.

3Fichiers 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>

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>

4Variables

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

$this['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

5Listes

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

$this['fruits'] = [
    'orange',
    'banane',
    'fraise',
];

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

{$fruits[2]}

Et vous obtiendrez : 

fraise

6Tableaux 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 : 

$this['colors'] = [
    'red'   => '#ff0000',
    'green' => '#00ff00',
    'blue'  => '#0000ff',
];

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

{$colors.red}

Ce qui donnera : 

#ff0000

7Conditions

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['user'] = $user;

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

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

8Boucles

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['users'] = $users;

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

<ul>
    {foreach $users as $user}
        <li>{$user.name}</li>
    {/foreach}
</ul>

9É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, Temma active par défaut l'option d'auto-échappement des variables de Smarty. Ainsi, tous les caractères spéciaux sont automatiquement convertis (< en &lt;, > en &gt;, & en &amp;, etc.).

Pour qu'une variable ne soit pas échappée automatiquement, il faut utiliser le filtre raw.

Exemples :

{$txt = "a & b"}
{* variable échappée automatiquement : écrit "a &amp; b" *}
{$txt}
{* variable non échappée : écrit "a & b" *}
{$name|raw}

Pour désactiver l'auto-échappement, il faut ajouter une directive dans la configuration étendue x-smarty-view (fichier etc/temma.php) : 

<?php

return [
    'x-smarty-view' => [
        'autoEscape' => false,
    ]
];

Smarty propose aussi le filtre escape, qui effectue l'échappement des caractères spéciaux. Par défaut, avec l'auto-échappement activé, ce modificateur ne fait rien (il n'y a pas de double échappement). Mais il est possible d'utiliser ce modificateur avec différentes options ("htmlall", "url", "urlpathinfo", "quotes", "hex", "hexentity", "javascript", "mail") qui auront un impact sur la variable modifiée. Il est aussi possible d'utiliser le paramètre "force" qui aboutira à un double échappement lorsque l'auto-échappement est activé.

Il s'utilise de la manière suivante : 

{$name|escape}
{$user.name|escape:'hex'}
{$user.firstname|escape:'force'}

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}

10Plugins

Smarty a son propre système de plugins, qui permet 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.php) : 

<?php

return [
    'x-smarty-view' => [
        'pluginsDir' => '/chemin/vers/le/répertoire',
    ]
];

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

<?php

return [
    'x-smarty-view' => [
        'pluginsDir' => [
            '/chemin/vers/le/répertoire1',
            '/chemin/vers/le/répertoire2',
            '/chemin/vers/le/répertoire3',
        ]
    ]
];