Mémento Smarty
Catégorie : Fiches techniques

INTRODUCTION

Ce document a pour but d'expliquer le rôle joué par Smarty au sein de Xoops, et de décrire l'essentiel á connaitre de Smarty dans le cadre de son utilisation avec Xoops :
- les méthodes pour les scripts,
- les fonctions et variables pour les templates.

Pour tout savoir sur Smarty, une documentation três complête, et en français, est disponible sur le site offficiel de Smarty

Sommaire

1) Généralités sur Smarty
- Les templates
- Le rôle de Smarty
- Le cache

2) Notions de base

3) Les méthodes pour les scripts

4) Les variables Smarty

5) Les fonctions Smarty


1) Généralités sur Smarty

Les templates
Les templates ont été créés pour permettre la séparation entre le traitement de l'information et son affichage. On a ainsi :

le Php pour le traitement des données: interfaçage avec la base de données, calculs, gestion des cookies et sessions, traitement des chaines de caractêres, etc.

le Html, associé aux feuilles de style, pour la présentation des données dans des tableaux, avec couleurs et images.

Les templates sont donc des fichiers Html particuliers, dans lesquels on trouvera :
- des variables (<{$story.title}>, <{$story.text}>.) qui seront remplacées, au moment de l'appel de la page, par le contenu que leur aura assigné le script Php
- des fonctions (<{if $show_articles == true}> , <{include file="db:news_item.html" story=$story}> ) permettant de conditionner l'affichage de certaines parties au résultat d'un test, d'inclure un autre template, ou encore de balayer un tableau de données transmis par le script Php.

Les templates permettent donc de modifier facilement l'apparence d'une page avec un éditeur Html, sans avoir á intervenir dans le code Php.

Le rôle de Smarty
Smarty est une application indépendante de Xoops que ce dernier utilise pour l'affichage par templates, ainsi que leur compilation et la gestion du cache.
C'est ce que l'on appelle un moteur de template dont le rôle est d'assurer l'interfacage entre le script Php et le template.
La configuration générale de Smarty est réalisée par Xoops, qui se charge également de l'interface utilisateur pour le paramétrage du cache, qui, nous le verrons ensuite, est une fonctionnalité de Smarty (et non de Xoops).
L'une des particularité de Smarty est d'intégrer un compilateur de templates, lesquels seront enregistrés dans la base de données. C'est la raison pour laquelle, aprês toute modification de template, il faut exécuter une mise á jour du module ou du systême pour que ces modifications soient prises en compte.

Le cache
L'un des inconvénients de l'utilisation d'un moteur de templates est qu'il a besoin lui aussi de ressources serveur pour fonctionner. Le temps de traitement d'une page utilisant les templates sera donc plus long qu'un affichage direct par le script Php.
Pour compenser cet inconvénient, les développeurs de Smarty ont donc intégré un systême de mise en cache : certaines pages, ou portions de pages, ne sont pas générées á chaque appel du navigateur, mais stockées directement en Html, prêtes á l'emploi, dans un répertoire spécifique (templates_c).
Lá encore, même si le paramêtrage du cache et l'interfacage avec l'utilisateur pour les modules ou blocs á mettre en cache est réalisé par Xoops, ce systême de cache est totalement géré par Smarty.

Retour au sommaire

[pagebreak]

2) Notions de base

Méthodes
Les méthodes sont utilisées dans les scripts Php.
Elles permettent d'assigner des valeurs aux variables smarty par valeur ou référence, sous forme de valeurs simples ou de tableaux.
La classe XoopsTpl étant une classe dérivée de la classe Smarty, toutes les méthodes de Smarty peuvent être utilisées avec
$xoopsTpl->methode_Smarty (ex. xoopsTpl->append('stories', $story) )
Méthodes Smarty

Délimiteurs
Les constantes, variables et fonctions, utilisées dans les templates, doivent être délimitées.
Smarty autorisant la personnalisation des délimiteurs, les symboles <{ et }> sont ceux défini par Xoops.

Commentaires
Il est possible d'insérer des commentaires dans les templates sous la forme :
<{* Ceci est un commentaire*}>
Attention, ils n'apparaitront pas dans le code source de la page, contrairement aux commentaires Html.

Fonctions
Les fonctions de Smarty sont les fonctions utilisables dans les templates:
Elles permettent notamment :
- l'inclusion d'autres templates
- des instructions conditionnelles
- le parcours de tableaux pour en afficher les données
Ne seront détaillées que les fonctions utilisées couramment avec Xoops (include, section, if, etc.)
Fonctions Smarty

Variables
 Les variables sont utilisées dans les templates :
- soit pour être affichées directement
- soit pour être utilisées comme arguments de fonctions ou au sein d'instructions conditionnelles.
On distingue 3 types de variables :
- Les variables réservées Smarty
- Les variables chargées depuis des fichiers de configuration (non développé ici)
- Les variables assignées depuis Php; nous listerons les variables assignées par Xoops, comme <{xoops_isadmin}> ou <{xoops_footer}>
Variables Smarty

Modificateurs de variables
Les modificateurs de variables peuvent être appliqués aux variables, fonctions et chaines de caractêres.
Ils sont utilisés pour des modification du texte : mise en majuscules, minuscules, troncature, suppression d'espace, etc.
Indiqués pour mémoire, n'étant en principe pas utilisés avec Xoops, les traitements de chaines de caractêres étant réalisés dans le Php.
Ex : <{$sujet | truncate:40:"..."}> troncature du texte 'sujet' á 40 caractêres, suivi de ...


Retour au sommaire

[pagebreak]

Smarty : méthodes

La classe xoopsTpl (fichier class/template.php) est une classe dérivée de la classe Smarty.
Toutes les méthodes de la classe Smarty peuvent donc être utilisées.
Sauf exception (voir display ), cette classe n'a pas besoin d'être instanciée, puisque la création de l'objet template est fait par xoops dans header.php :
require_once XOOPS_ROOT_PATH.'/class/template.php';
$xoopsTpl = new XoopsTpl();

assign Smarty assignation d'une valeur
assign_by_ref Smarty assignation d'une valeur par référence
append Smarty ajout d'une valeur
append_by_ref Smarty ajout d'une valeur par référence
display Smarty affichage du template
xoops_template_clear_module_cache xoopsTpl Effacement du cache du module

NB: de nombreuses méthodes (de la classe Smarty, ou de la classe dérivée) ne sont pas décrites, étant utilisées principalement par le core de Xoops.

assign
Permet d'assigner une valeur à  un template.
La valeur est soit une chaine, soit un tableau associatif.

assign (string | array $tpl_var, mixed $value = null)

$tpl_var string ou array nom de la variable de template à  créer
$value mixed valeur à  lui transmettre


Exemples

// Passage d'une paire nom/valeur
$xoopsTpl->assign('displaynav', false);

// Passage d'un tableau associatif
$xoopsTpl->assign(array(
"lang_partner" => _MD_PARTNER,
"lang_desc" => _MD_DESCRIPTION,
"lang_hits" => _MD_HITS, ));

assign_by_ref
Identique à  assign, sauf que la donnée est passée par référence (et non par valeur).

assign_by_ref (string | array $tpl_var, mixed $value = null)

$tpl_var string ou array nom de la variable de template à  créer
$value mixed Référence de la valeur à  lui transmettre

append
Permet d'ajouter une valeur à  une variable tableau d'un template.
Si le tableau n'existe pas, il est d'abord créé.
Dans le template, le tableau peut être parcouru avec la fonction foreach ou section.

append (string | array $tpl_var, mixed $value = null)

Exemples (avec fonction section dans le template)

// Dans le code¨Php
for ( $i = 0; $i < $partner_count; $i++ ) {
$partner[$i]['hits'] = $array_partners[$i]['hits'];
$partner[$i]['title'] = $array_partners[$i]['title'];
$partner[$i]['descr'] = $array_partners[$i]['description'];
$xoopsTpl->append("partners", $partner[$i]);
}

<{* Dans le template* }>
<{section name=partner loop=$partners}>
<tr>
<td><{$partners[partner].title}> <br/><{$partners[partner].descr}></td>
<td><{$partners[partner].hits}></td>
</tr>
<{/section}>


append_by_ref
Identique à  append, sauf que la donnée est passée par référence (et non par valeur)

Exemple (avec boucle foreach dans le template)

// Dans le code¨Php
while (list($id, $name) = $xoopsDB->fetchRow($result)) {
$category = array();
$category['name'] = $name;
$category['id'] = $id;
$sql = 'SELECT faq_id, faq_title FROM '.$xoopsDB->prefix('xoops_faq').' WHERE cat_id='.$id;
$result = $xoopsDB->query($sql);
while ($myrow = $xoopsDB->fetchArray($result)) {
$category['questions'][] = array('id' => $myrow['faq_id'], 'title' => $myrow['faq_title']);
}
$xoopsTpl->append_by_ref('categories', $category);
unset($category);
}

<{* Dans le template* }>
<{foreach item=question from=$category.questions}>
<{$question.title}>
<{* ... suite du code* }>


display
Affichage du template.
Pas nécessaire lorsque l'on utilise l'affichage par le template prinipal (template_main) puisque le footer.php se charge d'exécuter cette action.
A n'utiliser que dans les cas particuliers d'affichage sans le thême (exemples : site closed, redirect header, image_manager,...)

$xoopsTpl->display (string $template)

Exemple

include_once XOOPS_ROOT_PATH.'/class/template.php';
$xoopsTpl = new XoopsTpl();
$xoopsTpl->assign(array('sitename' => $xoopsConfig['sitename'], 'xoops_themecss' => .... ));
$xoopsTpl->xoops_setCaching(1);
$xoopsTpl->display('db:system_siteclosed.html');
exit();

xoops_template_clear_module_cache
Permet de vider le cache du module.

xoops_template_clear_module_cache (int $mid)
$mid int identifiant du module


Exemple (aprês une m à j dans l'admin d'un module)

include_once XOOPS_ROOT_PATH.'/class/template.php';
xoops_template_clear_module_cache($xoopsModule->getVar('mid'));

Retour au sommaire Smarty


Version Xoops de référence: 2.06
C. Felix AKA theCat le 22/06/04

[pagebreak]

Smarty : variables

Ces variables smarty, qu'elles soient assignées par Xoops ou réservées pour Smarty sont utilisables dans tous les templates.

Variables assignées

- Variables assignées par Xoops dans le fichier header.php, á partir des données de la Bdd.
Ces valeurs sont celles enregistrées dans la page Admin systême >> Préférences >> Méta balises et pied de page

<{xoops_meta_keywords}> Balise méta: mots clefs
<{xoops_meta_description}> Balise méta: description
<{xoops_meta_author}> Balise méta: auteur
<{meta_copyright}> Balise méta: copyright
<{meta_robots}> Balise méta: robots
<{xoops_footer}> Pied de page


- Variables assignées par xoops dans le fichier header.php

<{xoops_sitename}> Nom du site *
<{xoops_pagetitle}> Titre de la page *
<{xoops_theme}> Nom du thême *
<{xoops_themecss}> Url de la feuille de style du thême *
<{xoops_js}> Inclusion de javascript du fichier include/xoops.js *
<{xoops_banner}> Affichage banniêre *
<{xoops_content}> Affichage du contenu de la page *
<{xoops_showcblock}> 0 ou 1 selon que le bloc centre doit être affiché *
<{xoops_showlblockr}> 0 ou 1 selon que le bloc gauche doit être affiché *
<{xoops_showrblock}> 0 ou 1 selon que le bloc droit doit être affiché *

<{xoops_requesturi}>

Url demandée, ayant conduit sur cette page

<{xoops_slogan}>

Slogan du site

<{xoops_imageurl}>

Url des images du theme *

<{xoops_isadmin}>

1 si administrateur

<{xoops_isuser}>

1 si user

<{xoops_userid}>

id de l'user, 0 si anonyme

<{xoops_uname}>

pseudo de l'user, sinon terme choisi pour anonyme

* Variables nécessaires au template du thême: theme.html

- Variables assignées par xoops dans le fichier template.php

<{xoops_charset}> Ex. ISO-8859-1
<{xoops_langcode}> Code de la langue 2 caratêres: en, fr, etc.
<{xoops_url}> Url du site
<{xoops_rootpath}> Chemin physique du répertoire de xoops
<{xoops_version}> Version de Xoops (ex. Xoops 2.0.5.1)
<{xoops_upload_url}> Url du répertoire d'upload


Variables réservées

<{$smarty.const}>
Permet d'accéder directement aux constantes Php depuis le template.
Utilisable en particulier pour afficher les 'defines' de langage, sans passer par un xoopsTpl->assign dans le Php.
Ex : <{$smarty.const._NW_ARTICLES}>

<{$smarty.now}>
Permet d'afficher le timestamp courant
Ex : <{$smarty.now | date_format : "%d-%m-%Y "}>

Variables de requêtes
Pour mémoire.
Permettent d'accéder á différentes variables de GET, POST, COOKIES, SERVER, ENVIRONNEMENT et SESSION

Retour au sommaire

C. Felix AKA theCat le 15/06/04

[pagebreak]

Smarty : fonctions

Smarty dispose en standard de plusieurs fonctions utilisables dans les templates.
On distingue les fonctions natives (directement intégrées au langage) et les fonctions utilisateurs (répertoire class/smarty/plugins).
Ne seront décrites que les fonctions utilisées habituellement avec Xoops.
De même tous les attributs des fonctions ne sont pas forcément décrits.
Consultez le site Smarty pour une information plus complête.

include

native

 inclusion d'un template dans un autre
if, elseif, else

native

 instruction conditionnelle
foreach, foreachelse

native

 parcours d'un tableau associatif simple
section, sectionelse

native

 parcours d'un tableau associatif complexe
cycle

utilisateur

 détermination cyclique de valeurs



include
 Permet d'inclure un template à  l'intérieur d'un autre template.
Il est possible de transmettre des variables au template inclus, sous forme d'attributs de la fonction.
Xoops stockant les templates en Bdd, le nom du template inclus sera précédé de db :

Nom attribut Requis Type Description
file Oui string nom du template à  inclure
[var...] Non mixed variable(s) à  passer au template


Include simple
 <{include file='db:system_notification_select.html'}>

Include avec passage de variable (story)
<{include file="db:news_item.html" story=$stories[i]}>


if, elseif, else
Instruction conditionnelle permettant l'exécution de tests.
Doit obligatoirement se terminer par la balise <{/if}>.
Permet d'utiliser les opérateurs logiques (forme littérale ou symbolique).
Attention, les opérateurs doivent être entourés d'espaces.

Opérateurs

= =

!=

>

>=

<

<=

!

||

&&

eq

neq

gt

gte

lt

lte

not

or

and

is even

is odd

is not even

is not odd

is even by

is odd by

div by

mod

Exemple
<{if $gender == 'male'}>
Bonjour Monsieur
<{elseif $gender == 'female'}>
Bonjour Madame
<{else}>
Bonjour
<{/if}>

Exemple avec opérateurs
<{if ($price >= 100 and $nbre > 9) or $code == 'promo' }>
Remise de 10%
<{/if}>

Exemple pour affichage sur 3 colonnes
Dans une table, passage à  la ligne suivante lorsque la valeur du compteur est un multiple de 3.
<{if $category.count is div by 3}>
</tr><tr>
<{/if}>

foreach, foreachelse
 Permet de parcourir un tableau associatif simple.
Doit obligatoirement se terminer par la balise <{/foreach}>
Les boucles peuvent être imbriquées (pas de limitation de nombre).
foreachelse sera executé si aucune valeur n'est trouvée dans la variable de l'attribut from

Nom attribut Requis Type Description
from Oui string nom du tableau à  parcourir
item Oui string nom de la variable pour accéder à  l'élément en cours
name Non string nom de la boucle foreach pour accéder à  ses propriétés


Exemple
 Parcours du tableau associatif $topics contenant les paires clefs/valeurs : post_image, post_title, poster_uname.
<{foreach item = sujet from = $topics}>
<td><{$sujet.post_image}> <{$sujet.post_title}></td>
<td><{$sujet.poster_uname}></td>
<{/foreach}>


section, sectionelse
 Permet de parcourir un tableau. Utilisée pour les tableaux complexes( multidimensionnels p.ex.).
Doit obligatoirement se terminer par la balise <{/section}>
Les sections peuvent être imbriquées (pas de limitation de nombre).
sectionelse sera executé si aucune valeur n'est trouvée.

Nom attribut Requis Type Descrip
<a href="http://creativecommons.org/licenses/by-nc-sa/2.0/fr/" title="Licence, certains droits réservés"><img src="http://www.frxoops.org/images/cdr_bouton.gif" alt="Licence, certains droits réservés" /></a>