Helper Smarty

---

1Présentation

Ce helper est utile pour traiter des templates Smarty au sein d'une application, pour générer des flux (texte, HTML, XML ou autre) en dehors du traitement de la vue par le framework.

Comme la vue Smarty, ce helper est compatible avec les versions 4 et 5 de la bibliothèque Smarty. (Ce n'était pas le cas auparavant : le helper était limité à Smarty 4.)

Il s'instancie via le composant d'injection de dépendances.

Sa méthode render() prend en paramètre le chemin vers le template Smarty à utiliser (chemin absolu ou chemin relatif sous le répertoire templates/ du projet), et un tableau associatif optionnel contenant les variables à rendre accessible dans le template.

Sa méthode eval() s'utilise de manière similaire, mais attend en premier paramètre le contenu d'un template Smarty, et non pas un chemin vers un fichier.

Sa méthode templateExists() prend en paramètre le chemin vers un template, et retourne un booléen indiquant si le template existe ou non.

---

2Utilisation

Exemple simple :

// définition du template
$template = 'chemin/vers/template.tpl';

// données de template
$data = [
	'var1' => 'value1',
	'var2' => 'value2',
];

// instanciation via le loader
$html = $this->_loader['\Temma\Utils\Smarty']->render($template, $data);

Exemple avancé :

use \Temma\Exceptions\IO as TµIOException;

// données de template
$data = [
	'name'   => 'Luke',
	'mentor' => 'Yoda',
];

try {
    // chemin vers le fichier de template
    $path = 'path/to/template.tpl';
    // traitement du template
    $html = $this->_loader['\Temma\Utils\Smarty']->render($path, $data);
} catch (TµIOException $e) {
    // variable contenant du code Smarty
    $smarty = "Hi {$name}, disciple of {$mentor}";
    // traitement du template
    $html = $this->_loader['\Temma\Utils\Smarty']->eval($smarty, $data);
}

// vérification de l'existence d'un fichier de template
if ($this->_loader['Temma\Utils\Smarty']->templateExists($path)) {
    print("Le template existe.");
}

---

3Échappement HTML

Comme dans la vue Smarty, l'auto-échappement HTML des variables est activé par défaut : les variables rendues dans les templates traités par le helper sont automatiquement échappées (les caractères spéciaux <, >, &, etc. sont convertis en entités HTML). Ce n'était pas le cas auparavant.

Ce comportement se règle globalement via la section de configuration x-smarty (clé autoEscape) ; voir la section échappement de la vue Smarty pour le détail.

Les méthodes render() et eval() acceptent en outre un troisième paramètre optionnel $autoEscape permettant de forcer le comportement le temps d'un seul appel :

• true : force l'échappement pour cet appel ;
• false : désactive l'échappement pour cet appel ;
• null (valeur par défaut) : utilise le réglage configuré.

// rendu avec le réglage configuré (échappement activé par défaut)
$html = $this->_loader['\Temma\Utils\Smarty']->render($template, $data);

// rendu sans échappement, le temps de cet appel
$raw = $this->_loader['\Temma\Utils\Smarty']->render($template, $data, false);

// le tableau de données est optionnel
$html = $this->_loader['\Temma\Utils\Smarty']->render($template);

---

4Plugins

Le helper enregistre exactement les mêmes plugins Smarty que la vue : ceux du répertoire lib/smarty-plugins de votre projet, ceux des répertoires listés dans la configuration x-smarty (clé pluginsDir), ainsi que les plugins de temma-ui s'il est installé.

Les modificateurs et fonctions personnalisés que vous utilisez dans vos templates sont donc également disponibles dans les templates traités par le helper.