Retour à la documentation développeur

Développer avec Smartyer

Smartyer est le moteur de templates (vues) que nous utilisons.

Dans un développement orienté MVC (Modèle-Vue-Contrôleur), Smartyer est ce qui permet l'affichage des vues depuis le contrôleur.

Smartyer

Smartyer une version plus légère et plus simple de Smarty, compatible avec les anciens moteurs Template_Lite et Dwoo notamment.

Techniquement il n'a que peu de différences avec Smarty et la documentation de Smarty s'y applique globalement, sauf les différences suivantes :

Exécution de code PHP

Smartyer autorise l'exécution de code PHP inclus dans un fichier Smartyer, c'est le résultat du fait que les instructions Smartyer sont remplacées par du code PHP, et que ce fichier généré est ensuite directement exécuté.

C'est un choix de design, qui permet de garder le moteur Smartyer simple, et de permettre d'intégrer du PHP si on a besoin de faire des choses plus complexes. Mais normalement dans les vues (ou templates) on ne doit pas faire de choses particulièrement complexes, toute la complexité doit être dans le modèle et le contrôleur. Cependant pour certains besoins spécifiques, c'est assez pratique.

Un exemple de code PHP + Smartyer combiné possible serait :

{foreach from=$membres item="membre"}
<?php
$class = ($membre->statut === "Président") ? 'chef' : 'membre';
?>
    <h2 class="{$class}">{$membre.nom}</h2>
{/foreach}

Le résultat de ce choix de design est qu'il est possible d'exécuter n'importe quel code PHP à l'intérieur d'un template Smartyer.

Sécurité !

De ce fait, il est strictement interdit de permettre à un non-développeur de modifier un template Smartyer.

Exemple d'utilisation interdite : édition ou génération de template Smartyer depuis un plugin Garradin. Le risque dans ce cas est, en cas de faille, qu'un attaquant puisse faire exécuter du code PHP dans une installation Garradin.

Échappement automatique des variables

Exemple : si $nom vaut <b>Test, {$nom} retournera &lt;b&gt;Test.

C'est une mesure de sécurité automatique qui permet d'empêcher l'injection HTML/CSS.

Pour désactiver l'échappement automatique (avec des variables ne contenant que des choses dont on est absolument sûr du contenu !), utiliser le modificateur raw : {$nom|raw}

Pour utiliser un échappement différent, utiliser le modificateur escape qui remplace l'échappement automatique : <a href="/page.php?nom={$nom|escape:"url"}">

A noter que cet échappement ne s'applique qu'aux variables affichées directement par Smartyer, les fonctions utilisateur doivent échapper elle-même les variables reçues en paramètres.

Variables dans les chaînes de de caractère

Il n'est pas possible d'intégrer des variables à l'intérieur de chaînes de caractère (contrairement à Smarty).

Exemple : {fonction_test argument="Coucou $nom !"} passera Coucou $nom ! à la fonction, mais pas Coucou Anouk !.

Pour remplacer des variables à l'intérieur de chaînes de caractère, utiliser le modificateur args (alias de la fonction PHP sprintf.

Par exemple : {fonction_test argument="Coucou %s !"|args:$nom}.

Fonctionnalités non supportées

  • Modificateur escape : le second argument du jeu de caractère n'est pas supporté. Le premier argument supporte également json comme type d'échappement, permettant de transformer une variable en structure JSON.
  • Fichiers de configuration
  • Variables réservées de type {$smarty....}
  • Système de cache
  • Opérations mathématiques de type {$numero+3}

Fonctions non supportées

{capture}
{config_load}
{include_php}
{insert}
{php}
{section},{sectionelse}
{strip}

{counter}
{cycle}
{debug}
{eval}
{fetch}
{html_checkboxes}
{html_image}
{html_options}
{html_radios}
{html_select_date}
{html_select_time}
{html_table}
{mailto}
{math}
{popup}
{popup_init}
{textformat}

Modificateurs non supportés

capitalize
count_characters
count_paragraphs
count_sentences
count_words
default
indent
lower
spacify
string_format
strip
strip_tags
upper
wordwrap

Ils peuvent être implémentés facilement au besoin. Par exemple :

$tpl = Template::getInstance();
$tpl->register_modifier('wordwrap', 'wordwrap');

Formulaires

Garradin offre quelques fonctions Smartyer utiles pour traiter les formulaires.

form_field

Cette fonction permet de renseigner la valeur d'un champ à partir de ce qui a été envoyé par l'utilisateur (cas d'un formulaire déjà soumis), ou une valeur préalablement enregistrée dans un tableau, un objet ou une variable.

Paramètres :

  • name : nom du champ à utiliser
  • data : variable source (objet ou tableau) contenant une clé identique à ce qui a été passé dans name, pour récupérer la valeur d'une entité existante
  • default : la valeur par défaut à renvoyer (chaîne de caractère), si la clé indiquée par name n'existe ni dans $_POST, ni dans le tableau ou objet passé dans data
  • checked : spécifique pour les champs de type case à cocher, renverra checked="checked" (à la place de la valeur) si la valeur récupérée correspond à la valeur passée dans cet argument
  • selected : pour les champs de type <select> ou bouton radio, même fonctionnement que pour checked

Exemple pour un formulaire de création :

<dt><label for="f_libelle">Libellé</label> <b title="(Champ obligatoire)">obligatoire</b></dt>
<dd><input type="text" name="libelle" id="f_libelle" value="{form_field name="libelle"}" required="required" /></dd>

Ici nous ne renseignons que le nom du champ (doit être équivalent au name du champ HTML), car l'entité n'existe pas encore, donc il n'y pas d'autre donnée à utiliser. Dans ce cas form_field ira récupérer $_POST['libelle'] si cette variable existe et l'affichera.

Exemple pour un formulaire de modification :

<dt><label for="f_libelle">Libellé</label> <b title="(Champ obligatoire)">obligatoire</b></dt>
<dd><input type="text" name="libelle" id="f_libelle" value="{form_field name=libelle data=$compte}" required="required" /></dd>

Ici nous ajoutons le paramètre data qui ira chercher la clé $compte.libelle si $_POST['libelle'] est vide.