smarty-php/smarty
1
0
Fork 0
mirror of https://github.com/smarty-php/smarty.git synced 2025-10-04 16:20:55 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
d199b7ea83e43ce921b4c35b10c33bbd24c8e4b1
smarty/docs/fr/programmers.sgml
mohrt c99671e968 fix special chars
2003-05-22 16:36:06 +00:00

3092 lines
114 KiB
Plaintext
Raw Blame History

<part id="smarty.for.programmers">
<title>Smarty pour les programmeurs</title>
<chapter id="smarty.constants">
<title>Constantes</title>
<para></para>
<sect1 id="constant.smarty.dir">
<title>SMARTY_DIR</title>
<para>
Il doit s'agir du chemin complet du répertoire où
se trouvent les fichiers classes de Smarty.
S'il n'est pas défini, Smarty essaiera alors d'en
déterminer automatiquement la valeur.
S'il est défini, le chemin doit se terminer par un slash.
</para>
<example>
<title>SMARTY_DIR</title>
<programlisting>
// définit le chemin du répertoire de Smarty
define("SMARTY_DIR","/usr/local/lib/php/Smarty/");
require_once(SMARTY_DIR."Smarty.class.php");</programlisting>
</example>
</sect1>
</chapter>
<chapter id="api.variables">
<title>Variables</title>
<sect1 id="variable.template.dir">
<title>$template_dir</title>
<para>
C'est le nom par défaut du répertoire des templates.
Si vous ne spécifiez aucun chemin lors de l'utilisation de templates, Smarty
les cherchera à cet emplacement.
Par défaut, il s'agit de "./templates", ce qui signifie
qu'il va chercher le répertoire templates
dans le répertoire où se trouve le script PHP en cours d'exécution.
</para>
<note>
<title>Note technique</title>
<para>
Il n'est pas conseillé de mettre ce répertoire
dans l'arborescence Web.
</para>
</note>
</sect1>
<sect1 id="variable.compile.dir">
<title>$compile_dir</title>
<para>
C'est le nom du répertoire où se trouvent les templates
compilés. Par défaut, il s'agit de "./templates_c",
ce qui signifie que Smarty va chercher ce répertoire
dans le même répertoire que le script PHP en cours d'exécution.
</para>
<note>
<title>Note technique</title>
<para>
Ce réglage doit être soit un chemin absolu, soit un chemin
relatif. include_path n'est pas utilisé pour écrire des fichiers.
</para>
</note>
<note>
<title>Note technique</title>
<para>
Il n'est pas conseillé de mettre ce répertoire
sous la racine de l'arborescence Web.
</para>
</note>
</sect1>
<sect1 id="variable.config.dir">
<title>$config_dir</title>
<para>
Il s'agit du répertoire utilisé pour stocker les
fichiers de configuration utilisés dans les templates.
La valeur par défaut est "./configs", ce qui signifie
que Smarty va chercher ce répertoire
dans le même répertoire que le script PHP qui s'exécute.
</para>
<note>
<title>Note technique</title>
<para>
Il n'est pas conseillé de mettre ce répertoire
sous la racine de l'arborescence Web.
</para>
</note>
</sect1>
<sect1 id="variable.plugins.dir">
<title>$plugins_dir</title>
<para>
Ce sont les répertoire dans lesquels Smarty ira chercher les plugins
dont il a besoin. La valeur par défaut est "plugins" sous le
répertoire SMARTY_DIR. Si vous donnez un chemin relatif, Smarty
regardera d'abord relativement au SMARTY_DIR, puis relativement au rtc (répertoire
de travail courant), puis relativement à chaque entrée de votre répertoire
d'inclusion PHP.
</para>
<note>
<title>Note technique</title>
<para>
Pour des raisons de performances, ne réglez pas votre plugins_dir
pour qu'il utilise votre include_path PHP. Utilisez un
chemin absolu ou un chemin relatif à SMARTY_DIR ou au rtc.
</para>
</note>
</sect1>
<sect1 id="variable.debugging">
<title>$debugging</title>
<para>
Cela active la
<link
linkend="chapter.debugging.console">console de débogage</link>.
La console est une fenêtre javascript qui vous informe des templates
inclus et des variables assignées dans la page courante.
</para>
</sect1>
<sect1 id="variable.debug.tpl">
<title>$debug_tpl</title>
<para>
C'est le nom du fichier template utilisé pour la
console de débuggage. Par défaut debug.tpl, il se situe dans <link
linkend="constant.smarty.dir">SMARTY_DIR</link>
</para>
</sect1>
<sect1 id="variable.debugging.ctrl">
<title>$debugging_ctrl</title>
<para>
Cela permet d'avoir différents moyens pour activer
le débogage. URL signifie que si SMARTY_DEBUG se
trouve dans QUERY_STRING, le débuggage
est activé à l'invocation du script. Si $debugging
est à vrai, cette valeur est sans effet.
</para>
</sect1>
<sect1 id="variable.global.assign">
<title>$global_assign</title>
<para>
C'est une liste de variable qui sont toujours
implicitement assignées au moteur de templates.
Ceci est commode pour rendre des variables globales
ou des variables du serveur accessibles à tous les templates
plutôt que de devoir les assigner à la main. Chaque élément
de $global_assign doit être soit le nom de la variable
globale, soit une paire clef/valeur, où clef est le
nom du tableau global et valeur le tableau de variable
assignées depuis ce tableau global.
$SCRIPT_NAME est globalement assigné par défaut depuis
$HTTP_SERVER_VARS.
</para>
<note>
<title>Note technique</title>
<para>
On peut accéder aux variables du serveur avec la variable
$smarty, par exemple {$smarty.server.SCRIPT_NAME}.
Se reporter à la section sur la variable
<link linkend="language.variables.smarty">$smarty</link>.
</para>
</note>
</sect1>
<sect1 id="variable.undefined">
<title>$undefined</title>
<para>
Cela règle la valeur de $undefined, null par défaut.
N'est actuellement utilisé que pour initialiser
des variables non-définies dans $global_assign à des
valeurs par défaut.
</para>
</sect1>
<sect1 id="variable.autoload.filters">
<title>$autoload_filters</title>
<para>
Si vous désirez charger des filtres à chaque invocation
de templates, vous pouvez le spécifier en utilisant cette
variable. Les types de filtres et les valeurs sont des
tableaux comportant le nom des filtres.
<informalexample>
<programlisting>
$smarty-&gt;autoload_filters = array('pre' =&gt; array('trim', 'stamp'),
'output' => array('convert'));
</programlisting>
</informalexample>
</para>
</sect1>
<sect1 id="variable.compile.check">
<title>$compile_check</title>
<para>
A chaque invocation de l'application PHP, Smarty fait
un test pour voir si le template courant a été modifié
(date de dernière modification différente) depuis sa
dernière compilation. S'il a changé, le template est recompilé.
Si le template n'a pas encore été compilé, il le sera
quelle que soit la valeur ce réglage.
Par défaut cette valeur est à vrai. Quand
une application est mise en production (les templates
ne changent plus), cette vérification n'est pas nécessaire.
Assurez-vous de mettre $compile_check à "false" pour des performances
maximales. Notez que si vous mettez ce paramètre à "false" et qu'un
template est modifié, vous ne verrez *pas* le changement
car le template ne sera *pas* recompilé. Si le processus de cache
est activé et que $compile_check l'est aussi, alors les fichiers
du cache seront regénérés si un template concerné ou un fichier de
configuration concerné est modifié. Voir aussi <link
linkend="variable.force.compile">$force_compile</link> ou <link
linkend="api.clear.compiled.tpl">clear_compiled_tpl</link>.
</para>
</sect1>
<sect1 id="variable.force.compile">
<title>$force_compile</title>
<para>
Cela oblige Smarty à (re)compiler les templates à chaque
invocation. Ce réglage supplante $compile_check. Par défaut, il
est désactivé. Ceci est commode pour le développement et le
débogage mais ne devrait jamais être utilisé dans un environnment
de production. Si le système de cache est actif, les
fichiers du cache seront regénérés à chaque appel.
</para>
</sect1>
<sect1 id="variable.caching">
<title>$caching</title>
<para>
Ce paramètre demande à Smarty de mettre ou non en cache la sortie des
templates.
Par défaut ce réglage est à 0 (désactivé). Si vos templates
génèrent du contenu redondant, il est conseillé d'activer le
cache. Cela permettra un gain de performance conséquent.
Vous pouvez aussi avoir de nombreux fichiers de cache pour un même template.
Une valeur de 1 ou 2 active le cache. 1 indique à Smarty d'utiliser
la variable $cache_lifetime pour déterminer si le fichier de cache a expiré.
Une valeur de 2 indique à Smarty d'utiliser la valeur
$cache_lifetime spécifiée à la génération du cache. Ainsi vous pouvez régler
la durée de vie d'un fichier de cache avant de récupérer le template pour avoir
un certain contrôle quand ce fichier en particulier expire. Voir
aussi <link linkend="api.is.cached">is_cached</link>.
</para>
<para>
Si $compile_check est actif, le contenu du cache sera regénéré
si un des templates ou un des fichiers de configuration qui fait partie
de ce fichier de cache a été modifié. Si $force_compile est actif, le contenu
du cache est toujours regénéré.
</para>
</sect1>
<sect1 id="variable.cache.dir">
<title>$cache_dir</title>
<para>
Il s'agit du nom du répertoire où les caches des templates
sont stockés. Par défaut il s'agit de "./cache", ce qui signifie
que Smarty va chercher ce répertoire
dans le même répertoire que le script PHP en cours d'exécution.
</para>
<note>
<title>Note technique</title>
<para>
Ce réglage doit être soit un chemin absolu, soit un chemin
relatif. include_path n'a aucune influence lors de l'écriture des fichiers.
</para>
</note>
<note>
<title>Technical Note</title>
<para>
Il n'est pas conseillé de mettre ce répertoire
dans l'arborescence Web.
</para>
</note>
</sect1>
<sect1 id="variable.cache.lifetime">
<title>$cache_lifetime</title>
<para>
Il s'agit de la durée en secondes pendant laquelle un cache de template
est valide. Une fois cette durée dépassée, le cache est regénéré.
$caching doit être à "true" pour que $cache_lifetime ait une
quelconque utilité. Avec une valeur de -1, le cache n'expire jamais.
Avec une valeur de 0, le cache est toujours regénéré (utile
à des fins de tests seulement. Une meilleure façon de désactiver
le cache est de mettre <link
linkend="variable.caching">$caching</link> à "false").
</para>
<para>
Si <link linkend="variable.force.compile">$force_compile</link> est
activé, les fichiers du cache seront regénérés à chaque fois,
désactivant ainsi le cache. Vous pouvez effacer tous les fichiers du cache
avec la function
<link linkend="api.clear.all.cache">clear_all_cache()</link>
ou de façon individuelle (ou groupée)
avec la fonction <link
linkend="api.clear.cache">clear_cache()</link>.
</para>
<note>
<title>Note technique</title>
<para>
Si vous souhaitez donner à certains templates leur propre durée de vie
en cache, vous pouvez le faire en réglant
<link linkend="variable.caching">$caching</link> à 2,
puis $cache_lifetime à une unique valeur juste avant d'appeler
display ou fetch().
</para>
</note>
</sect1>
<sect1 id="variable.cache.handler.func">
<title>$cache_handler_func</title>
<para>
Vous pouvez utiliser votre propre fonction de gestion du cache plutôt que
d'utiliser celle livrée avec Smarty.
Référez-vous à la section sur la fonction de gestion de cache
personnalisée pour plus de détails.
</para>
</sect1>
<sect1 id="variable.cache.modified.check">
<title>$cache_modified_check</title>
<para>
Si cette variable est à vrai, Smarty respectera l'en-tête
If-Modified-Since envoyé par le client. Si la date de dernière
modification du fichier de cache n'a pas changé depuis la dernière
visite, alors un en-tête "304 Not Modified" sera envoyé à la place
du contenu. Cela ne fonctionne qu'avec du contenu mis en cache hors de la
balise <command>insert</command>.
</para>
</sect1>
<sect1 id="variable.config.overwrite">
<title>$config_overwrite</title>
<para>
Si cette variable est à vrai, les variables lues dans les fichiers
de configuration peuvent s'écraser entre elles. Sinon les variables
seront mises dans un tableau. Très utile si vous voulez stocker
des tableaux de données dans des fichiers de configuration, listez
simplement chaque élément plusieurs fois. Mise à faux par défaut.
</para>
</sect1>
<sect1 id="variable.config.booleanize">
<title>$config_booleanize</title>
<para>
Si cette variable est à vrai, les valeurs on/true/yes et off/false/no
dans les fichiers de configuration sont automitiquement converties
en booléen. De cette façon vous pouvez utiliser ces valeurs dans le
template de la façon suivante : {if #foobar#} ... {/if}. Si foobar
est à on, true ou yes, l'instruction {if} sera exécutée. vrai
par défaut.
</para>
</sect1>
<sect1 id="variable.config.read.hidden">
<title>$config_read_hidden</title>
<para>
Si cette variable est à vrai, les sections cachés (dont les noms
commencent par un point) dans les fichiers de configuration peuvent
être lues depuis les templates. On laisse habituellement cela à faux, de
cette façon vous pouvez stocker des données sensibles dans les fichiers
de configuration, comme par exemple des paramètres de base de données,
sans vous soucier de la façon dont les templates les chargent.
Mise à faux par défaut.
</para>
</sect1>
<sect1 id="variable.config.fix.newlines">
<title>$config_fix_newlines</title>
<para>
Si cette variable est mise à vrai, les caractères de nouvelles lignes mac et dos
(\r et \r\n) sont convertis en \n quand ils sont analysés. vrai par défaut.
</para>
</sect1>
<sect1 id="variable.default.template.handler.func">
<title>$default_template_handler_func</title>
<para>
Cette fonction est appelée quand un template ne peut pas être
obtenu avec sa ressource.
</para>
</sect1>
<sect1 id="variable.php.handling">
<title>$php_handling</title>
<para>
Indique à Smarty comment interpréter le code PHP
intégré dans les templates. Il y a quatre valeurs possibles, par
défaut SMARTY_PHP_PASSTHRU. Notez que cela n'affecte PAS le code
PHP entouré des balises
<link linkend="language.function.php">{php}{/php}</link>
dans le template.
</para>
<itemizedlist>
<listitem><para>SMARTY_PHP_PASSTHRU - Smarty écrit les balises
telles quelles.</para></listitem>
<listitem><para>SMARTY_PHP_QUOTE - Smarty transforme les balises
en entités HTML.</para></listitem>
<listitem><para>SMARTY_PHP_REMOVE - Smarty supprime les balises
des templates.</para></listitem>
<listitem><para>SMARTY_PHP_ALLOW - Smarty exécute les balises
comme du code PHP.</para></listitem>
</itemizedlist>
<para>
NOTE : Intégrer du code PHP dans les templates est vivement
déconseillé. Préférez les
<link linkend="language.custom.functions">fonctions utilisateurs</link>
ou les <link linkend="language.modifiers">modificateurs de variables</link>.
</para>
</sect1>
<sect1 id="variable.security">
<title>$security</title>
<para>
Cette variable est à faux par défaut. $security est de rigueur
quand vous n'êtes pas complètement sûr des personnes qui éditent les templates
(par ftp par exemple) et que vous voulez réduire le risque que
la sécurité du système soit compromise par le language de template.
Activer cette option de sécurité applique les règles suivantes
au langage de template, à moins que $security_settings ne spécifie
le contraire :
</para>
<itemizedlist>
<listitem><para>Si $php_handling est réglée à SMARTY_PHP_ALLOW,
cela est implicitement changé à SMARTY_PHP_PASSTHRU.</para></listitem>
<listitem><para>Les fonctions PHP ne sont pas autorisées dans les
instructions IF, à part celles déclarées dans
$security_settings.</para></listitem>
<listitem><para>Les templates ne peuvent être inclus que depuis
des répertoires listés dans le tableau $security_dir.</para></listitem>
<listitem><para>Les fichiers locaux ne peuvent être récupérés que depuis
les répertoires listés dans le tableau $security_dir en
utilisant {fetch}.</para></listitem>
<listitem><para>Les balises {php}{/php} ne sont pas autorisées.</para></listitem>
<listitem><para>Les fonctions PHP ne sont pas autorisées en tant
modificateurs, à part celles spécifiées dans $security_settings.</para></listitem>
</itemizedlist>
</sect1>
<sect1 id="variable.secure.dir">
<title>$secure_dir</title>
<para>
Il s'agit d'un tableau contenant tous les répertoires locaux qui sont
considérés comme sécurisés. {include} et {fetch} l'utilisent quand
la sécurité est activée.
</para>
</sect1>
<sect1 id="variable.security.settings">
<title>$security_settings</title>
<para>
Ces réglages servent à écraser ou spécifier les paramètres de sécurité
quand celle-ci est activée. Les réglages possibles sont les suivants :
</para>
<itemizedlist>
<listitem><para>PHP_HANDLING - true/false. Si vrai, le
réglage $php_handling n'est pas vérifié.</para></listitem>
<listitem><para>IF_FUNCS - Le tableau des noms de fonctions
PHP autorisées dans les intructions IF.</para></listitem>
<listitem><para>INCLUDE_ANY - true/false. Si vrai,
les templates peuvent être inclus de n'importe où, quelque soit
le contenu de $secure_dir.</para></listitem>
<listitem><para>PHP_TAGS - true/false. Si vrai,
les balises {php}{/php} sont autorisées dans les templates.</para></listitem>
<listitem><para>MODIFIER_FUNCS - Le tableau des noms de fonctions
autorisées à être utilisées comme modificateurs de variables.</para></listitem>
</itemizedlist>
</sect1>
<sect1 id="variable.trusted.dir">
<title>$trusted_dir</title>
<para>
$trusted_dir n'est utilisée lorsque $security est activée. C'est un
tableau de tous les répertoires qui peuvent être considérés comme sûrs.
Les répertoires sûrs sont ceux qui contiennent des scripts PHP qui
sont exécutés directement depuis les templates avec
<link linkend="language.function.include.php">{include_php}</link>.
</para>
</sect1>
<sect1 id="variable.left.delimiter">
<title>$left_delimiter</title>
<para>
Il s'agit du délimiteur gauche utilisé par le moteur de templates. La
valeur par défaut est "{".
</para>
</sect1>
<sect1 id="variable.right.delimiter">
<title>$right_delimiter</title>
<para>
Il s'agit du délimiteur droit utilisé par le moteur de templates.
La valeur par défaut est "}".
</para>
</sect1>
<sect1 id="variable.compiler.class">
<title>$compiler_class</title>
<para>
Spécifie le nom de la classe du compilateur qui va être utilisée pour
compiler les templates. Le compilateur par défaut est
'Smarty_Compiler'. Réservé aux utilisateurs avancés.
</para>
</sect1>
<sect1 id="variable.request.vars.order">
<title>$request_vars_order</title>
<para>
L'ordre dans lequel les variables de requêtes sont enregistrées,
identique à variables_order dans php.ini.
</para>
</sect1>
<sect1 id="variable.compile.id">
<title>$compile_id</title>
<para>
Identifiant persistant du compilateur. On peut passer le même compile_id
à chaque appel de fonction mais une alternative consiste à régler ce
compile_id, qui sera utilisé implicitement.
</para>
</sect1>
<sect1 id="variable.use.sub.dirs">
<title>$use_sub_dirs</title>
<para>
Régler cela à faux si votre environnement PHP n'autorise pas Smarty à créer
des sous-répertoires. Les sous-répertoires sont efficaces, utilisez-les quand
vous le pouvez.
</para>
</sect1>
<sect1 id="variable.default.modifiers">
<title>$default_modifiers</title>
<para>
Il s'agit d'un tableau de modificateurs utilisé pour assigner
une valeur par défaut à chaque variable dans un template.
Par exemple, pour par défaut échapper les caractères HTML de chaque variable,
utilisez array('escape:"htmlall"'); Pour rendre une variable indépendante
des modificateurs par défaut, passez-lui en paramètre le modificateur
"nodefaults" : {$var|nodefaults}.
</para>
</sect1>
</chapter>
<chapter id="api.functions">
<title>Méthodes</title>
<sect1 id="api.append">
<title>append</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>append</function></funcdef>
<paramdef>mixed <parameter>var</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>void <function>append</function></funcdef>
<paramdef>string <parameter>varname</parameter></paramdef>
<paramdef>mixed <parameter>var</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>void <function>append</function></funcdef>
<paramdef>string <parameter>varname</parameter></paramdef>
<paramdef>mixed <parameter>var</parameter></paramdef>
<paramdef>boolean <parameter>merge</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Utilisée pour ajouter un élément à un tableau assigné. Si vous utilisez
cette fonction avec une chaîne de caractère, elle est convertie en
tableau auquel on ajoute ensuite l'élément. Vous pouvez explicitement passer
des paires nom/valeur. Si vous passez le troisième paramètre
(optionel) à vrai, la valeur sera fusionnée avec le tableau plutôt que
d'être ajoutée.
</para>
<note>
<title>Note technique</title>
<para>
Le paramètre de fusion respecte les clés des tableaux, ainsi si vous
fusionnez deux tableaux indexés numériquement, ils pourront s'écraser
l'un l'autre ou donner des clés qui ne se suivent pas. Cela diffère
donc de la fonction PHP array_merge() qui supprime les clés numériques
et les renumérote.
</para>
</note>
<example>
<title>append</title>
<programlisting>
// passe des paires nom/valeur
$smarty->append("Name","Fred");
$smarty->append("Address",$address);
// passe un tableau associatif
$smarty->append(array("city" => "Lincoln","state" => "Nebraska"));</programlisting>
</example>
</sect1>
<sect1 id="api.append.by.ref">
<title>append_by_ref</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>append_by_ref</function></funcdef>
<paramdef>string <parameter>varname</parameter></paramdef>
<paramdef>mixed <parameter>var</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>void <function>append_by_ref</function></funcdef>
<paramdef>string <parameter>varname</parameter></paramdef>
<paramdef>mixed <parameter>var</parameter></paramdef>
<paramdef>boolean <parameter>merge</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Utilisée pour ajouter des valeurs à un template par référence plutôt que
par copie. Si vous ajoutez une variable par référence puis changez sa
valeur, le changement est aussi répercuté sur la valeur assignée.
Pour les objets, append_by_ref ne fait pas de copie en mémoire de l'objet
assigné. Voir la documentation PHP pour plus d'informations sur les
références de variable.
Si vous passez le troisième paramètre à vrai, la valeur sera fusionnée
avec le tableau courant plutôt que d'être ajoutée.
</para>
<note>
<title>Note technique</title>
<para>
Le paramètre de fusion respecte les clés des tableaux, ainsi si vous
fusionnez deux tableaux indexés numériquement, ils pourront s'écraser
l'un l'autre ou donner des clés qui ne se suivent pas. Cela diffère
donc de la fonction PHP array_merge() qui supprime les clés numériques
et les renumérote.
</para>
</note>
<example>
<title>append_by_ref</title>
<programlisting>
// ajoute des paires nom/valeur
$smarty->append_by_ref("Name",$myname);
$smarty->append_by_ref("Address",$address);</programlisting>
</example>
</sect1>
<sect1 id="api.assign">
<title>assign</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>assign</function></funcdef>
<paramdef>mixed <parameter>var</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>void <function>assign</function></funcdef>
<paramdef>string <parameter>varname</parameter></paramdef>
<paramdef>mixed <parameter>var</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Utilisée pour assigner des valeurs aux templates. Vous pouvez
explicitement passer des paires nom/valeur, ou des tableaux
associatifs contenant des paires nom/valeur.
</para>
<example>
<title>assign</title>
<programlisting>
// passe des paires nom/valeur
$smarty->assign("Name","Fred");
$smarty->assign("Address",$address);
// passe un tableau associatif
$smarty->assign(array("city" => "Lincoln","state" => "Nebraska"));</programlisting>
</example>
</sect1>
<sect1 id="api.assign.by.ref">
<title>assign_by_ref</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>assign_by_ref</function></funcdef>
<paramdef>string <parameter>varname</parameter></paramdef>
<paramdef>mixed <parameter>var</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Utilisée pour assigner des valeurs aux templates par référence plutôt
que par copie. Référez-vous au manuel PHP pour une explication plus précise
sur les références des variables.
</para>
<note>
<title>Note technique</title>
<para>
Si vous assignez une variable par référence puis changez sa
valeur, le changement est aussi répercuté sur la valeur assignée.
Pour les objets, assign_by_ref ne fait pas de copie en mémoire de l'objet
assigné. Référez-vous au manuel PHP pour une explication plus précise sur
les références de variable.
</para>
</note>
<example>
<title>assign_by_ref</title>
<programlisting>
// passe des paires noms/valeurs
$smarty->assign_by_ref("Name",$myname);
$smarty->assign_by_ref("Address",$address);</programlisting>
</example>
</sect1>
<sect1 id="api.clear.all.assign">
<title>clear_all_assign</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>clear_all_assign</function></funcdef>
<paramdef><parameter></parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Utilisée pour effacer les valeurs de toutes les variables assignées.
</para>
<example>
<title>clear_all_assign</title>
<programlisting>
// efface toutes les variables assignées
$smarty->clear_all_assign();</programlisting>
</example>
</sect1>
<sect1 id="api.clear.all.cache">
<title>clear_all_cache</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>clear_all_cache</function></funcdef>
<paramdef>int <parameter>expire time</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Utilisée pour effacer les fichiers de cache des templates. Vous pouvez passer un
paramètre optionnel afin d'indiquer l'âge minimun que doivent avoir
les fichiers de cache pour qu'ils soient effacés.
</para>
<example>
<title>clear_all_cache</title>
<programlisting>
// efface le cache
$smarty->clear_all_cache();</programlisting>
</example>
</sect1>
<sect1 id="api.clear.assign">
<title>clear_assign</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>clear_assign</function></funcdef>
<paramdef>string <parameter>var</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Efface la valeur d'une variable assignée. Il peut s'agir
d'une simple valeur ou d'un tableau de valeur.
</para>
<example>
<title>clear_assign</title>
<programlisting>
// efface une variable
$smarty->clear_assign("Name");
// efface plusieurs variables
$smarty->clear_assign(array("Name","Address","Zip"));</programlisting>
</example>
</sect1>
<sect1 id="api.clear.cache">
<title>clear_cache</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>clear_cache</function></funcdef>
<paramdef>string <parameter>template</parameter></paramdef>
<paramdef>string <parameter><optional>cache id</optional></parameter></paramdef>
<paramdef>string <parameter><optional>compile id</optional></parameter></paramdef>
<paramdef>int <parameter><optional>expire time</optional></parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Utilisée pour nettoyer le(s) fichier(s) de cache d'un template en particulier.
Si vous avez plusieurs fichiers de cache pour ce template vous
pouvez en spécifier un en particulier en passant son identifiant
en deuxième paramètre. Vous pouvez aussi passer un identifiant
de compilation en troisième paramètre. Vous pouvez grouper des
templates ensemble afin qu'ils puissent être supprimés en groupe.
Référez-vous à la section sur le
<link linkend="caching">cache</link>
pour plus d'informations. Vous pouvez passer un quatrième paramètre
pour indiquer un âge minimum en secondes que le fichier en cache doit
avoir avant d'être effacé.
</para>
<example>
<title>clear_cache</title>
<programlisting>
// efface le fichier de cache de ce template
$smarty->clear_cache("index.tpl");
// efface un fichier de cache grâce à son identifiant de cache
$smarty->clear_cache("index.tpl","CACHEID");</programlisting>
</example>
</sect1>
<sect1 id="api.clear.compiled.tpl">
<title>clear_compiled_tpl</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>clear_compiled_tpl</function></funcdef>
<paramdef>string <parameter>tpl_file</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Utilisée pour effacer la version compilée du template spécifié ou
de tous les templates si aucun n'est spécifié. Cette fonction
est destinée à un usage avancé et n'est pas habituellement utilisée.
</para>
<example>
<title>clear_compiled_tpl</title>
<programlisting>
// efface la version compilée du template spécifié
$smarty->clear_compiled_tpl("index.tpl");
// efface tout le contenu du répertoire des templates compilés
$smarty->clear_compiled_tpl();</programlisting>
</example>
</sect1>
<sect1 id="api.clear.config">
<title>clear_config</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>clear_config</function></funcdef>
<paramdef>string <parameter><optional>var</optional></parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Utilisée pour effacer toutes les variables de configuration s'étant
vues assigner une valeur. Si une variable est spécifiée, seule cette
variable est effacée.
</para>
<example>
<title>clear_config</title>
<programlisting>
// efface toutes les variables de configuration assignées
$smarty->clear_config();
// efface une seule variable
$smarty->clear_config('foobar');</programlisting>
</example>
</sect1>
<sect1 id="api.config.load">
<title>config_load</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>config_load</function></funcdef>
<paramdef>string <parameter>file</parameter></paramdef>
<paramdef>string <parameter><optional>section</optional></parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Utilisée pour charger des données d'un fichier de config et les
assigner à un template. Cette fonction fonctionne exactement comme
la fonction de template <link
linkend="language.function.config.load">config_load</link>.
</para>
<note>
<title>Note technique</title>
<para>
Comme pour Smarty 2.4.0, les variables de templates assignées
sont conservées entre chaque appel à fetch et display.
Les variables de configuration chargées avec config_load sont
globales. Les fichiers de config sont aussi compilés pour une
exécution plus rapide et respecte les réglages de <link
linkend="variable.force.compile">force_compile</link> et de <link
linkend="variable.compile.check">compile_check</link>.
</para>
</note>
<example>
<title>config_load</title>
<programlisting>
// charge les variables de configuration et les assigne
$smarty->config_load('my.conf');
// charge une section
$smarty->config_load('my.conf','foobar');</programlisting>
</example>
</sect1>
<sect1 id="api.display">
<title>display</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>display</function></funcdef>
<paramdef>string <parameter>template</parameter></paramdef>
<paramdef>string <parameter><optional>cache_id</optional></parameter></paramdef>
<paramdef>string <parameter><optional>compile_id</optional></parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Utilisée pour afficher un template. Il faut fournir un type et un
chemin de <link
linkend="template.resources">ressource template</link>
valides. Vous pouvez passer en second paramètre un identifiant
de fichier de cache. Reportez-vous à la section
<link linkend="caching">cache</link> pour plus de renseignements.
</para>
<para>
Le troisième paramètre optionnel est un identifiant de compilation.
Cela s'avère utile quand vous voulez compiler différentes versions
d'un même template, pour par exemple avoir des templates
compilés séparés pour différents langages. Une autre utilité de ce
paramètre est le cas où vous utilisez plus d'un $template_dir mais un seul
$compile_dir, car certains templates avec le même nom s'écraseraient
entre eux. Vous pouvez aussi régler la variable <link
linkend="variable.compile.id">$compile_id</link> une seule
fois au lieu de la passer à chaque appel.
</para>
<example>
<title>affichage</title>
<programlisting>
include("Smarty.class.php");
$smarty = new Smarty;
$smarty->caching = true;
// ne fait un appel à la base de données que si le fichier
// de cache n'existe pas
if(!$smarty->is_cached("index.tpl"))
{
// quelques données
$address = "245 N 50th";
$db_data = array(
"City" => "Lincoln",
"State" => "Nebraska",
"Zip" = > "68502"
);
$smarty->assign("Name","Fred");
$smarty->assign("Address",$address);
$smarty->assign($db_data);
}
// display the output
$smarty->display("index.tpl");</programlisting>
</example>
<para>
Utilisez la syntaxe des <link
linkend="template.resources">ressources templates</link>
pour afficher des fichiers en-dehors du répertoire
$template_dir
</para>
<example>
<title>exemples de fonction d'affichage de ressources templates</title>
<programlisting>
// chemin absolu
$smarty->display("/usr/local/include/templates/header.tpl");
// chemin absolu (pareil)
$smarty->display("file:/usr/local/include/templates/header.tpl");
// chemin absolu Windows (on DOIT utiliser le préfixe "file:")
$smarty->display("file:C:/www/pub/templates/header.tpl");
// inclue à partir de la ressource template "db"
$smarty->display("db:header.tpl");</programlisting>
</example>
</sect1>
<sect1 id="api.fetch">
<title>fetch</title>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>fetch</function></funcdef>
<paramdef>string <parameter>template</parameter></paramdef>
<paramdef>string <parameter><optional>cache_id</optional></parameter></paramdef>
<paramdef>string <parameter><optional>compile_id</optional></parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Utilisée pour renvoyer le résultat du template plutôt que de l'afficher.
Il faut passer un type et un chemin de <link
linkend="template.resources">ressource template</link>
valides. Vous pouvez passer un identifiant de cache en deuxième
paramètre. Reportez-vous à la section <link linkend="caching">cache
</link> pour plus de renseignements.
</para>
<para>
Un troisième paramètre optionnel est un identifiant de compilation.
Cela s'avère utile quand vous voulez compiler différentes versions
d'un même template, pour par exemple avoir des templates
compilés séparés pour différents langages. Une autre utilité de ce
paramètre est le cas où vous utilisez plus d'un $template_dir
mais un seul $compile_dir, car certains templates avec le même nom
s'écraseraient entre eux. Vous pouvez aussi régler la variable <link
linkend="variable.compile.id">$compile_id</link> une seule
fois plutôt que de la passer à chaque appel.
</para>
<example>
<title>fetch</title>
<programlisting>
include("Smarty.class.php");
$smarty = new Smarty;
$smarty->caching = true;
// ne fait un appel à la base de données que si le fichier
// de cache n'existe pas
if(!$smarty->is_cached("index.tpl"))
{
// quelques données
$address = "245 N 50th";
$db_data = array(
"City" => "Lincoln",
"State" => "Nebraska",
"Zip" = > "68502"
);
$smarty->assign("Name","Fred");
$smarty->assign("Address",$address);
$smarty->assign($db_data);
}
// récupère le résultat
$output = $smarty->fetch("index.tpl");
// fait quelque chose avec $output
echo $output;</programlisting>
</example>
</sect1>
<sect1 id="api.get.config.vars">
<title>get_config_vars</title>
<funcsynopsis>
<funcprototype>
<funcdef>array <function>get_config_vars</function></funcdef>
<paramdef>string <parameter><optional>varname</optional></parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Retourne la valeur de la variable de configuration passée en paramètre.
Si aucun paramètre n'est donné, un tableau de toutes les variables de
configuration chargées est renvoyé.
</para>
<example>
<title>get_config_vars</title>
<programlisting>
// récupère la variable de configuration chargée 'foo'
$foo = $smarty->get_config_vars('foo');
// récupère toutes les variables de configuration chargées
$config_vars = $smarty->get_config_vars();
// les affiche à l'écran
print_r($config_vars);</programlisting>
</example>
</sect1>
<sect1 id="api.get.registered.object">
<title>get_registered_object</title>
<funcsynopsis>
<funcprototype>
<funcdef>array <function>get_registered_object</function></funcdef>
<paramdef>string <parameter>object_name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Retourne la référence d'un objet enregistré. Utile quand vous
voulez accéder directement à un objet enregistré avec une
fonction utilisateur.
</para>
<example>
<title>get_registered_object</title>
<programlisting>
function smarty_block_foo($params, &amp;$smarty) {
if (isset[$params['object']]) {
// récupère la référence de l'objet enregistré
$obj_ref =&amp; $smarty->get_registered_object($params['object']);
// $obj_ref est maintenant une référence vers l'objet
}
}</programlisting>
</example>
</sect1>
<sect1 id="api.get.template.vars">
<title>get_template_vars</title>
<funcsynopsis>
<funcprototype>
<funcdef>array <function>get_template_vars</function></funcdef>
<paramdef>string <parameter><optional>varname</optional></parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Retourne la valeur assignée passée en paramètre. Si aucun paramètre
n'est donné, un tableau de toutes les variables assignées est
renvoyé.
</para>
<example>
<title>get_template_vars</title>
<programlisting>
// récupère la variable 'foo' assignée au template
// get assigned template var 'foo'
$foo = $smarty->get_template_vars('foo');
// récupère toutes les variables assignées à ce template
$tpl_vars = $smarty->get_template_vars();
// les affiche à l'écran
print_r($tpl_vars);</programlisting>
</example>
</sect1>
<sect1 id="api.is.cached">
<title>is_cached</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>is_cached</function></funcdef>
<paramdef>string <parameter>template</parameter></paramdef>
<paramdef>[string <parameter>cache_id</parameter>]</paramdef>
</funcprototype>
</funcsynopsis>
<para>
Retourne vrai s'il y a un fichier de cache valide pour ce template.
Cela fonctionne seulement si <link
linkend="variable.caching">caching</link> est à vrai.
</para>
<example>
<title>is_cached</title>
<programlisting>
$smarty->caching = true;
if(!$smarty->is_cached("index.tpl")) {
// faire des requêtes base de données et assigner
// des variables ici.
}
$smarty->display("index.tpl");</programlisting>
</example>
<para>
Vous pouvez aussi passer en second paramètre un identifiant
de cache au cas où vous voudriez plusieurs fichiers de cache
pour ce template.
</para>
<example>
<title>is_cached with multiple-cache template</title>
<programlisting>
$smarty->caching = true;
if(!$smarty->is_cached("index.tpl","FrontPage")) {
// faire des requêtes base de données et assigner
// des variables ici.
}
$smarty->display("index.tpl","FrontPage");</programlisting>
</example>
</sect1>
<sect1 id="api.load.filter">
<title>load_filter</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>load_filter</function></funcdef>
<paramdef>string <parameter>type</parameter></paramdef>
<paramdef>string <parameter>name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Cette fonction peut être utilisée pour charger un plugin
de filtrage. Le premier argument spécifie le type du filtre
et peut prendre l'une des valeurs suivantes : 'pre', 'post'
ou 'output'. Le second argument spécifie le nom du plugin
de filtrage, par exemple 'trim'.
</para>
<example>
<title>Chargement de plugins de filtrage</title>
<programlisting>
$smarty->load_filter('pre', 'trim'); // charge le filtre 'trim' de type 'pre'
$smarty->load_filter('pre', 'datefooter'); // charge un autre filtre de type 'pre' appelé 'datefooter'
$smarty->load_filter('output', 'compress'); // charge le filtre 'compress' de type 'output'</programlisting>
</example>
</sect1>
<sect1 id="api.register.block">
<title>register_block</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>register_block</function></funcdef>
<paramdef>string <parameter>name</parameter></paramdef>
<paramdef>string <parameter>impl</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Utilisée pour déclarrer dynamiquement des plugins de fonction
de blocs. Il faut passer en paramètre le nom de la fonction
de blocs, suivi du nom de la fonction PHP qui l'implémente.
</para>
<example>
<title>register_block</title>
<programlisting>
/* PHP */
$smarty->register_block("translate", "do_translation");
function do_translation ($params, $content, &$smarty) {
if ($content) {
$lang = $params['lang'];
// fait de la traduction avec la variable $content
echo $translation;
}
}
{* template *}
{translate lang="br"}
Hello, world!
{/translate}</programlisting>
</example>
</sect1>
<sect1 id="api.register.compiler.function">
<title>register_compiler_function</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>register_compiler_function</function></funcdef>
<paramdef>string <parameter>name</parameter></paramdef>
<paramdef>string <parameter>impl</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Utilisée pour déclarer dynamiquement un plugin de fonction
de compilation. Il faut passer en paramètres le nom de la fonction
de compilation, suivi par la fonction PHP qui
l'implémente.
</para>
</sect1>
<sect1 id="api.register.function">
<title>register_function</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>register_function</function></funcdef>
<paramdef>string <parameter>name</parameter></paramdef>
<paramdef>string <parameter>impl</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Utilisée pour déclarer dynamiquement des plugins de fonction
de templates. Il faut passer en paramètres le nom de la fonction
de templates, suivi par le nom de la fonction PHP qui l'implémente.
</para>
<example>
<title>register_function</title>
<programlisting>
$smarty->register_function("date_now", "print_current_date");
function print_current_date ($params) {
extract($params);
if(empty($format))
$format="%b %e, %Y";
echo strftime($format,time());
}
// vous pouvez maintenant utiliser ceci dans Smarty pour afficher
// la date actuelle : {date_now} ou {date_now format="%Y/%m/%d"}
// pour la formater</programlisting>
</example>
</sect1>
<sect1 id="api.register.modifier">
<title>register_modifier</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>register_modifier</function></funcdef>
<paramdef>string <parameter>name</parameter></paramdef>
<paramdef>string <parameter>impl</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Utilisée pour déclarer dynamiquement un plugin de modificateur.
Il faut passer en paramètre le nom du modificateur de variables,
suivi de la fonction PHP qui l'implémente.
</para>
<example>
<title>register_modifier</title>
<programlisting>
// associons la fonction PHP stripslashes à un modificateur Smarty.
$smarty->register_modifier("sslash","stripslashes");
// vous pouvez maintenant utiliser {$var|sslash} pour supprimer les slash des variables</programlisting>
</example>
</sect1>
<sect1 id="api.register.object">
<title>register_object</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>register_object</function></funcdef>
<paramdef>string <parameter>object_name</parameter></paramdef>
<paramdef>object <parameter>$object</parameter></paramdef>
<paramdef>array <parameter>allowed methods/properties</parameter></paramdef>
<paramdef>boolean <parameter>format</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Utilisée pour enregistrer un objet à utiliser dans un template.
Reportez-vous à la section
<link linkend="advanced.features.objects">objet</link> de
ce manuel pour des exemples.
</para>
</sect1>
<sect1 id="api.register.outputfilter">
<title>register_outputfilter</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>register_outputfilter</function></funcdef>
<paramdef>string <parameter>function_name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Utilisée pour déclarer dynamiquement des filtres de sortie, pour
agir sur la sortie d'un template avant qu'elle ne soit affichée.
Reportez-vous à la section <link linkend="advanced.features.outputfilters">
filtres de sortie</link> pour plus d'information sur le sujet.
</para>
</sect1>
<sect1 id="api.register.postfilter">
<title>register_postfilter</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>register_postfilter</function></funcdef>
<paramdef>string <parameter>function_name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Utilisée pour déclarer dynamiquement des filtres de post-compilation pour y faire
passer des templates une fois qu'ils ont été compilés. Reportez-vous
à la section
<link linkend="advanced.features.postfilters">filtres de post-compilation de templates</link>
pour avoir plus de renseignements sur la façon de paramétrer les fonctions
de post-compilation.
</para>
</sect1>
<sect1 id="api.register.prefilter">
<title>register_prefilter</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>register_prefilter</function></funcdef>
<paramdef>string <parameter>function_name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Utilisée pour déclarer dynamiquement des filtres de pré-compilation pour y faire
passer des templates avant qu'ils ne soient compilés. Reportez-vous
à la section
<link linkend="advanced.features.postfilters">filtres de pré-compilation de templates</link>
pour avoir plus de renseignements sur la façon de paramétrer les fonctions
de pré-compilation.
</para>
</sect1>
<sect1 id="api.register.resource">
<title>register_resource</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>register_resource</function></funcdef>
<paramdef>string <parameter>name</parameter></paramdef>
<paramdef>array <parameter>resource_funcs</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Utilisée pour déclarer dynamiquement une ressource plugin
dans Smarty. Il faut passer en paramètre le nom de la ressource
et le tableau des fonctions PHP qui l'implémentent. Reportez-vous
à la section <link linkend="template.resources">ressources templates</link>
pour avoir plus d'informations sur la façon de paramétrer une fonction
récupérant des templates.
</para>
<example>
<title>register_resource</title>
<programlisting>
$smarty->register_resource("db", array("db_get_template",
"db_get_timestamp",
"db_get_secure",
"db_get_trusted"));</programlisting>
</example>
</sect1>
<sect1 id="api.trigger.error">
<title>trigger_error</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>trigger_error</function></funcdef>
<paramdef>string <parameter>error_msg</parameter></paramdef>
<paramdef>[int <parameter>level</parameter>]</paramdef>
</funcprototype>
</funcsynopsis>
<para>
Cette fonction peut-être utilisée pour afficher un message d'erreur
en utilisant Smarty. Le paramètre <parameter>level</parameter>
peut prendre l'une des valeures utilisées par la fonction PHP
trigger_error, i.e. E_USER_NOTICE, E_USER_WARNING, etc. Par défaut
il s'agit de E_USER_WARNING.
</para>
</sect1>
<sect1 id="api.template.exists">
<title>template_exists</title>
<funcsynopsis>
<funcprototype>
<funcdef>bool <function>template_exists</function></funcdef>
<paramdef>string <parameter>template</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Cette fonction vérifie si le template spécifié existe. Elle accepte
soit un chemin vers le template, soit une ressource de type
chaîne de caractères précisant le nom du template.
</para>
</sect1>
<sect1 id="api.unregister.block">
<title>unregister_block</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>unregister_block</function></funcdef>
<paramdef>string <parameter>name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Utilisée pour désallouer dynamiquement un plugin de fonction
de blocs. Passez en paramètre le nom du bloc.
</para>
</sect1>
<sect1 id="api.unregister.compiler.function">
<title>unregister_compiler_function</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>unregister_compiler_function</function></funcdef>
<paramdef>string <parameter>name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Utilisée pour désallouer dynamiquement un fonction de compilation.
Passez en paramètre le nom de la fonction de compilation.
</para>
</sect1>
<sect1 id="api.unregister.function">
<title>unregister_function</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>unregister_function</function></funcdef>
<paramdef>string <parameter>name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Utilisée pour désallouer dynamiquement un plugin de fonction
de templates. Passez en paramètres le nom de la fonction de templates.
</para>
<example>
<title>unregister_function</title>
<programlisting>
// nous ne voulons pas que les designers de templates aient accès
// au système de fichiers.
$smarty->unregister_function("fetch");</programlisting>
</example>
</sect1>
<sect1 id="api.unregister.modifier">
<title>unregister_modifier</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>unregister_modifier</function></funcdef>
<paramdef>string <parameter>name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Utilisée pour désallouer dynamiquement un plugin modificateur de variable.
Passez en paramètre le nom du modificateur de templates.
</para>
<example>
<title>unregister_modifier</title>
<programlisting>
// nous ne voulons pas que les designers de templates
// suppriment les balises des élements
$smarty->unregister_modifier("strip_tags");</programlisting>
</example>
</sect1>
<sect1 id="api.unregister.object">
<title>unregister_object</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>unregister_object</function></funcdef>
<paramdef>string <parameter>object_name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Utilisée pour désallouer un objet.
</para>
</sect1>
<sect1 id="api.unregister.outputfilter">
<title>unregister_outputfilter</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>unregister_outputfilter</function></funcdef>
<paramdef>string <parameter>function_name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Utilisée pour désallouer dynamiquement un filtre de sortie.
</para>
</sect1>
<sect1 id="api.unregister.postfilter">
<title>unregister_postfilter</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>unregister_postfilter</function></funcdef>
<paramdef>string <parameter>function_name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Utilisée pour désallouer dynamiquement un filtre de post-compilation.
</para>
</sect1>
<sect1 id="api.unregister.prefilter">
<title>unregister_prefilter</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>unregister_prefilter</function></funcdef>
<paramdef>string <parameter>function_name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Utilisée pour désallouer dynamiquement un filtre de pré-compilation.
</para>
</sect1>
<sect1 id="api.unregister.resource">
<title>unregister_resource</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>unregister_resource</function></funcdef>
<paramdef>string <parameter>name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Utilisée pour désallouer dynamiquement un plugin ressource.
Passez en paramètre le nom de la ressource.
</para>
<example>
<title>unregister_resource</title>
<programlisting>
$smarty->unregister_resource("db");</programlisting>
</example>
</sect1>
</chapter>
<chapter id="caching">
<title>Cache</title>
<para>
Le cache est utilisée pour accélérer l'appel de <link
linkend="api.display">display()</link> ou de <link
linkend="api.fetch">fetch()</link> en sauvegardant leur résultat
dans un fichier. Si un fichier de cache est disponible lors d'un appel,
il sera affiché sans qu'il ne soit nécessaire de regénérer le résultat.
Le système de cache
peut accélérer les traitements de façon impressionnante, en particulier les
templates dont la compilation est très longue. Comme le résultat de
display() ou de fetch() est dans le cache, un fichier de cache peut
être composé de plusieurs fichiers de templates, plusieurs fichiers
de configuration, etc.
</para>
<para>
Comme les templates sont dynamiques, il est important de faire attention
à la façon dont les fichiers de cache sont générés, et pour combien de temps.
Si par exemple vous affichez la page d'accueil de votre site Web dont le
contenu ne change pas souvent, il peut être intéressant de mettre cette page
dans le cache pour une heure ou plus. A l'inverse, si vous affichez une page
de météo mises à jour toutes les minutes, mettre cette page en cache
n'a aucun sens.
</para>
<sect1 id="caching.setting.up">
<title>Paramétrer le cache</title>
<para>
La première chose à faire est d'activer le cache. Cela est fait en
mettant <link linkend="variable.caching">$caching</link> = true
(ou 1).
</para>
<example>
<title>activation du cache</title>
<programlisting>
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
$smarty->display('index.tpl');</programlisting>
</example>
<para>
Avec le cache activé, la fonction display('index.tpl') va afficher
le template mais sauvegardera par la même occasion une copie du résultat
dans un fichier (de cache) du répertoire
<link linkend="variable.cache.dir">$cache_dir</link>. Au prochain appel de
display('index.tpl'), le fichier de cache sera préféré à la réutilisation
du template.
</para>
<note>
<title>Note technique</title>
<para>
Les fichiers situés dans $cache_dir sont nommés de la même façon que les templates.
Bien qu'ils aient une extension ".php", ils ne sont pas vraiment exécutable.
N'éditez surtout pas ces fichiers !
</para>
</note>
<para>
Tout fichier de cache à une durée de vie limitée déterminée par <link
linkend="variable.cache.lifetime">$cache_lifetime</link>. La valeur par
défaut est 3600 secondes, i.e. 1 heure. Une fois que cette durée est
dépassée, le cache est regénéré. Il est possible de donner
une durée d'expiration propre à chaque fichier de cache en réglant
$caching = 2.
Se reporter à la documentation de <link
linkend="variable.cache.lifetime">$cache_lifetime</link> pour plus de
détails.
</para>
<example>
<title>réglage individuel de cache_lifetime</title>
<programlisting>
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = 2; // régler la durée de vie individuellement
// régle la durée de vie du cache à 15 minutes pour index.tpl
$smarty->cache_lifetime = 300;
$smarty->display('index.tpl');
// régle la durée de vie du cache à 1 heure pour home.tpl
$smarty->cache_lifetime = 3600;
$smarty->display('home.tpl');
// NOTE : le réglage suivant ne fonctionne pas quand $caching = 2. La durée de vie
// du fichier de cache de home.tpl a déjà été réglée à 1 heure et ne respectera
// plus la valeur de $cache_lifetime. Le cache de home.tpl expirera toujours
// dans 1 heure.
$smarty->cache_lifetime = 30; // 30 secondes
$smarty->display('home.tpl');</programlisting>
</example>
<para>
Si <link linkend="variable.compile.check">$compile_check</link> est actif,
chaque fichier de template et de configuration qui a un rapport
avec le fichier de cache sera vérifié pour détecter une éventuelle
modification. Si l'un de ces fichiers a été modifié depuis que le fichier de cache a été
généré, le cache est immédiatement regénéré. Ce processus est coûteux, donc,
pour des raisons de performances, mettez ce paramètre à false pour une application
en production.
</para>
<example>
<title>activation de $compile_check</title>
<programlisting>
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
$smarty->compile_check = true;
$smarty->display('index.tpl');</programlisting>
</example>
<para>
Si <link linkend="variable.force.compile">$force_compile</link> est actif,
les fichiers de cache sont toujours regénérés. Ceci revient finalement à
désactiver le cache. $force_compile est utilisé à des fins de débogage,
un moyen plus efficace de désactiver le cache est de régler
<link linkend="variable.caching">$caching</link> = false (ou 0).
</para>
<para>
La fonction <link linkend="api.is.cached">is_cached()</link> permet
de tester si un template a ou non un fichier de cache valide.
Si vous disposez d'un template en cache qui requiert une requête
à une base de données, vous pouvez utiliser cette méthode plutôt
que $compile_check.
</para>
<example>
<title>utilisation de is_cached()</title>
<programlisting>
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
if(!$smarty->is_cached('index.tpl')) {
// pas de cache disponible, on assigne
$contents = get_database_contents();
$smarty->assign($contents);
}
$smarty->display('index.tpl');</programlisting>
</example>
<para>
Vous pouvez rendre dynamiques seulement certaines parties d'une
page avec la fonction de templates <link
linkend="language.function.insert">insert</link>.
Imaginons que toute une page doit être mise en cache à part
une bannière en bas à droite. En utilisant une fonction insert pour la
bannière, vous pouvez garder cet élément dynamique dans le contenu qui
est en cache. Reportez-vous à la documentation
<link linkend="language.function.insert">insert</link> pour plus de détails
et des exemples.
</para>
<para>
Vous pouvez effacer tous les fichiers du cache avec la fonction <link
linkend="api.clear.all.cache">clear_all_cache(),</link> ou de façon
individuelle (ou par groupe) avec la fonction <link
linkend="api.clear.cache">clear_cache()</link>.
</para>
<example>
<title>nettoyage du cache</title>
<programlisting>
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
// efface tous les fichiers du cache
$smarty->clear_all_cache();
// efface le fichier de cache du template 'index.tpl'
$smarty->clear_cache('index.tpl');
$smarty->display('index.tpl');</programlisting>
</example>
</sect1>
<sect1 id="caching.multiple.caches">
<title>Caches multiples pour une seule page</title>
<para>
Vous pouvez avoir plusieurs fichiers de caches pour un même appel
aux fonctions display() ou fetch(). Imaginons qu'un appel à display('index.tpl')
puisse avoir plusieurs résultats, en fonction de certaines conditions, et que
vous vouliez des fichiers de cache séparés pour chacun d'eux. Vous
pouvez faire cela en passant un identifiant de cache (cache_id) en
deuxième paramètre à l'appel de fonction.
</para>
<example>
<title>Passage d'un cache_id à display()</title>
<programlisting>
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
$my_cache_id = $_GET['article_id'];
$smarty->display('index.tpl',$my_cache_id);</programlisting>
</example>
<para>
Nous passons ci-dessus la variable $my_cache_id à display() comme
identifiant de cache. Pour chaque valeur distincte de $my_cache_id,
un fichier de cache distinct va être créé. Dans cet exemple,
"article_id" a été passé dans l'URL et est utilisé en tant qu'identifiant
de cache.
</para>
<note>
<title>Note technique</title>
<para>
Soyez prudent en passant des valeurs depuis un client (navigateur Web)
vers Smarty (ou vers n'importe quelle application PHP). Bien que l'exemple
ci-dessus consistant à utiliser article_id depuis l'URL puisse paraître
commode, le résultat peut s'avérer mauvais. L'identifiant
de cache est utilisé pour créer un répertoire sur le système de fichiers,
donc si l'utilisateur décide de donner une très grande valeur à article_id
ou d'écrire un script qui envoie des article_id de façon aléatoire,
cela pourra causer des problèmes coté serveur. Assurez-vous de bien
tester toute donnée passée en paramètre avant de l'utiliser. Dans cet
exemple, peut-être savez-vous que article_id a une longueur de 10
caractères, est exclusivement composé de caractères alph-numériques et
doit avoir une valeur contenue dans la base de données. Vérifiez-le bien !
</para>
</note>
<para>
Assurez-vous de bien passer le même identifiant aux fonctions
<link linkend="api.is.cached">is_cached()</link> et
<link linkend="api.clear.cache">clear_cache()</link>.
</para>
<example>
<title>passer un cache_id à is_cached()</title>
<programlisting>
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
$my_cache_id = $_GET['article_id'];
if(!$smarty->is_cached('index.tpl',$my_cache_id)) {
// pas de fichier de cache dispo, on assigne donc les variables
$contents = get_database_contents();
$smarty->assign($contents);
}
$smarty->display('index.tpl',$my_cache_id);</programlisting>
</example>
<para>
Vous pouvez effacer tous les fichiers de cache pour un identifiant
de cache particulier en passant null en tant que premier paramètre
à clear_cache().
</para>
<example>
<title>effacement de tous les fichiers de cache pour un identifiant de cache particulier</title>
<programlisting>
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
// efface tous les fichiers de cache avec "sports" comme identifiant
$smarty->clear_cache(null,"sports");
$smarty->display('index.tpl',"sports");</programlisting>
</example>
<para>
De cette manière vous pouvez "grouper" vos fichiers de cache en leur
donnant le même identifiant.
</para>
</sect1>
<sect1 id="caching.groups">
<title>groupes de fichiers de cache</title>
<para>
Vous pouvez faire des groupements plus élaborés en paramétrant les
groupes d'identifiant de cache. Il suffit de séparer chaque sous-groupes
avec une barre verticale "|" dans la valeur de l'identifiant de cache.
Vous pouvez faire autant de sous-groupes que vous le désirez.
</para>
<example>
<title>groupes d'identifiants de cache</title>
<programlisting>
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
// efface tous les fichiers de cache avec "sports|basketball" comme premiers
// groupes d'identifiants de cache
$smarty->clear_cache(null,"sports|basketball");
// efface tous les fichiers de cache "sports" comme premier groupe d'identifiants.
// Inclue donc "sports|basketball" ou "sports|nimportequoi|nimportequoi|..."
$smarty->clear_cache(null,"sports");
$smarty->display('index.tpl',"sports|basketball");</programlisting>
</example>
<note>
<title>Note technique</title>
<para>
Le système de cache n'utilise PAS le chemin vers le template en quoi
que ce soit pour l'identifiant de cache. Si par exemple vous
faites display('themes/blue/index.tpl'), vous ne pouvez pas effacer tous
les fichiers de cache dans le répertoire "theme/blue". Si vous voulez
faire cela, vous devez les grouper avec un même identifiant de cache,
display('themes/blue/index.tpl','themes|blue'). Vous pouvez ensuite effacer les
fichiers de cache pour blue et theme avec clear_cache(null,'theme|blue').
</para>
</note>
</sect1>
</chapter>
<chapter id="advanced.features">
<title>Fonctionnalités avancées</title>
<sect1 id="advanced.features.objects">
<title>Objets</title>
<para>
Smarty donne l'accès aux objets PHP à travers les templates. Il y
a 2 moyens d'y avoir accès. Le premier consiste à allouer les objets
au template puis de les utiliser avec une syntaxe similaire à celles
des fonctions personnalisées. Le deuxième moyen consiste à allouer
des objets aux templates et de les utiliser comme n'importe quelle
variable. La première méthode a une syntaxe beaucoup plus sympathique.
Elle est aussi plus sécurisée, puisqu'un objet alloué ne peut avoir accès
qu'à certaines méthodes et propriétés. Néanmoins, un objet alloué
ne peut pas avoir de lien sur lui-même ou être mis dans un tableau
d'objet, etc. Vous devez choisir la méthode qui correspond à vos
besoins, mais tâchez d'utiliser la première méthode autant que possible
afin de réduire la syntaxe des templates au minimum.
</para>
<para>
Si l'option de sécurité est activée, aucune méthode ou fonctions privées
n'est accessible (commençant par "_"). S'il existe une méthode et une
propriété du même nom, c'est la méthode qui sera utilisée.
</para>
<para>
Vous pouvez restreindre l'accès aux méthodes et aux propriétés en
les listant dans un tableau en tant que troisième paramètre
d'allocation.
</para>
<para>
Par défaut, les paramètres passés aux objets depuis le templates le sont de la
même façon que les fonctions utilisateurs les récupèrent.
Le premier paramètre correspond à un tableau associatif, le second à l'objet
Smarty. Si vous souhaitez que les paramètres soient passées un à un, comme
dans un appel traditionnel, définissez registration, quatrième paramètre optionnel,
à false.
</para>
<example>
<title>utilisation d'un objet alloué ou assigné</title>
<programlisting>
&lt;?php
// la classe
class My_Object() {
function meth1($params, &$smarty_obj) {
return "this is my meth1";
}
}
$myobj = new My_Object;
// enregistre l'objet
$smarty->register_object("foobar",$myobj);
// on restreint l'accès à certaines méthodes et propriétés en les listant
$smarty->register_object("foobar",$myobj,array('meth1','meth2','prop1'));
// pour utiliser le format habituel de paramètre objet, passez le booléen = false
$smarty->register_object("foobar",$myobj,null,false);
// on peut aussi assigner des objets. Assignez par référence quand c'est possible
$smarty->assign_by_ref("myobj", $myobj);
$smarty->display("index.tpl");
?&gt;
TEMPLATE:
{* accès à notre objet enregistré *}
{foobar->meth1 p1="foo" p2=$bar}
{* on peut aussi assigner la sortie *}
{foobar->meth1 p1="foo" p2=$bar assign="output"}
the output was {$output)
{* access our assigned object *}
{$myobj->meth1("foo",$bar)}</programlisting>
</example>
</sect1>
<sect1 id="advanced.features.prefilters">
<title>Filtres de pré-compilation</title>
<para>
Les filtres de pré-compilation sont des fonctions PHP que vos templates
exécutent avant qu'ils ne soient compilés. Cela peut être utile
pour pré-traiter vos templates afin d'enlever les commentaires
inutiles, garder un oeil sur ce que les gens mettent dans leurs templates, etc.
Les filtre de pré-compilations peuvent être soit
<link linkend="api.register.prefilter">déclarés</link> soit chargés
à partir des répertoires de plugins en utilisant la fonction
<link linkend="api.load.filter">load_filter()</link> ou en réglant
la variable
<link linkend="variable.autoload.filters">$autoload_filters</link>.
Smarty passera à la fonction le code source en tant que premier argument,
et attendra en retour le code modifié.
</para>
<example>
<title>Utilisation un filtre de pré-compilation de template</title>
<programlisting>
&lt;?php
// mettre ceci dans votre application
function remove_dw_comments($tpl_source, &$smarty)
{
return preg_replace("/&lt;!--#.*--&gt;/U","",$tpl_source);
}
// enregistrer le filtre de pré-compilation
$smarty->register_prefilter("remove_dw_comments");
$smarty->display("index.tpl");
?&gt;
{* template Smarty index.tpl *}
&lt;!--# cette ligne va être supprimée par le filtre de pré-compilation --&gt;</programlisting>
</example>
</sect1>
<sect1 id="advanced.features.postfilters">
<title>Filtres de post-compilation</title>
<para>
Les filtres de post-compilation sont des fonctions PHP que vos templates
exécutent après avoir été compilés. Les filtres de post-compilation peuvent
être soit <link linkend="api.register.postfilter">déclarés</link> soit chargés
depuis les répertoires des plugins en utilisant la fonction
<link linkend="api.load.filter">load_filter()</link> ou en réglant
la variable <link linkend="variable.autoload.filters">$autoload_filters</link>.
Smarty passera le template compilé en tant que premier paramètre et attendra
de la fonction qu'elle retourne le résultat de l'exécution.
</para>
<example>
<title>utilisation d'un filtre de post-compilation de templates</title>
<programlisting>
&lt;?php
// mettez cela dans votre application
function add_header_comment($tpl_source, &$smarty)
{
return "&lt;?php echo \"&lt;!-- Created by Smarty! --&gt;\n\" ?&gt;\n".$tpl_source;
}
// enregistre le filtre de post-compilation
$smarty->register_postfilter("add_header_comment");
$smarty->display("index.tpl");
?&gt;
{* template Smarty compilé index.tpl *}
&lt;!-- Created by Smarty! --&gt;
{* reste du contenu du template... *}</programlisting>
</example>
</sect1>
<sect1 id="advanced.features.outputfilters">
<title>Filtres de sortie</title>
<para>
Quand le template est appelé via les fonctions display() ou fetch(),
sa sortie est envoyée à travers un ou plusieurs filtres de sorties.
Ils diffèrent des filtres de post-compilation dans le sens ou ils agissent
sur la sortie des templates, une fois exécutés, et non sur les sources
des templates.
</para>
<para>
Les filtres de sortie peuvent être soit
<link linkend="api.register.outputfilter">déclarés</link> soit
chargés depuis les répertoires des plugins en utilisant la fonction
<link linkend="api.load.filter">load_filter()</link>
ou en réglant la variable
<link linkend="variable.autoload.filters">$autoload_filters</link>.
Smarty passera la sortie du template en premier argument et attendra
de la fonction qu'elle retourne le résultat de l'exécution.
</para>
<example>
<title>utilisation d'un filtre de sortie</title>
<programlisting>
&lt;?php
// mettez ceci dans votre application
function protect_email($tpl_output, &$smarty)
{
$tpl_output =
preg_replace('!(\S+)@([a-zA-Z0-9\.\-]+\.([a-zA-Z]{2,3}|[0-9]{1,3}))!',
'$1%40$2', $tpl_output);
return $tpl_output;
}
// enregistre le filtre de sortie
$smarty->register_outputfilter("protect_email");
$smarty->display("index.tpl");
// dorénavant toute occurence d'un adresse email dans le résultat du template
// aura un protection simple contre les robots spammers
?&gt;</programlisting>
</example>
</sect1>
<sect1 id="section.template.cache.handler.func">
<title>Fonction de gestion du cache</title>
<para>
Une alternative au mécanisme de cache par défaut (basé sur des fichiers
de cache) consiste à spécifier une fonction de gestion de cache utilisateur
qui sera utilisée pour lire, écrire et effacer les fichiers de cache.
</para>
<para>
Il suffit de créer dans votre application une fonction que Smarty
utilisera pour la gestion du cache et d'assigner le nom de cette
fonction à la variable de classe
<link linkend="variable.cache.handler.func">$cache_handler_func</link>.
Smarty utilisera alors cette fonction pour gérer les données du cache.
Le premier argument est l'action, qui sera 'read', 'write' ou 'clear'.
Le second paramètre est l'objet Smarty. Le troisième est le contenu
du cache. Pour écrire, Smarty passe le contenu du cache dans ces paramètres.
Pour lire, Smarty s'attend à ce que votre fonction accepte ce paramètre
par référence et que vous le remplissiez avec les données du cache. Pour effacer,
il suffit de passer une variable fictive car cette dernière n'est pas utilisée.
Le quatrième paramètre est le nom du fichier de template (utile pour
lire/écrire), le cinquième paramètre est l'identifiant de cache (optionnel)
et le sixième est l'identifiant de compilation.
</para>
<example>
<title>exemple d'utilisation de MySQL pour la source du cache</title>
<programlisting>
&lt;?php
/*
exemple d'usage :
include('Smarty.class.php');
include('mysql_cache_handler.php');
$smarty = new Smarty;
$smarty-&gt;cache_handler_func = 'mysql_cache_handler';
$smarty-&gt;display('index.tpl');
la base mysql est attendu dans ce format :
create database SMARTY_CACHE;
create table CACHE_PAGES(
CacheID char(32) PRIMARY KEY,
CacheContents MEDIUMTEXT NOT NULL
);
*/
function mysql_cache_handler($action, &$smarty_obj, &$cache_content, $tpl_file=null, $cache_id=null, $compile_id=null)
{
// l'hôte de la bd, l'utilisateur, et le mot de passe
$db_host = 'localhost';
$db_user = 'myuser';
$db_pass = 'mypass';
$db_name = 'SMARTY_CACHE';
$use_gzip = false;
// crée un identifiant de cache unique
$CacheID = md5($tpl_file.$cache_id.$compile_id);
if(! $link = mysql_pconnect($db_host, $db_user, $db_pass)) {
$smarty_obj-&gt;_trigger_error_msg("cache_handler: could not connect to database");
return false;
}
mysql_select_db($db_name);
switch ($action) {
case 'read':
// récupère le cache dans la base de données
$results = mysql_query("select CacheContents from CACHE_PAGES where CacheID='$CacheID'");
if(!$results) {
$smarty_obj-&gt;_trigger_error_msg("cache_handler: query failed.");
}
$row = mysql_fetch_array($results,MYSQL_ASSOC);
if($use_gzip && function_exists("gzuncompress")) {
$cache_contents = gzuncompress($row["CacheContents"]);
} else {
$cache_contents = $row["CacheContents"];
}
$return = $results;
break;
case 'write':
// sauvegarde le cache dans la base de données
if($use_gzip && function_exists("gzcompress")) {
// compresse le contenu pour gagner de la place
$contents = gzcompress($cache_content);
} else {
$contents = $cache_content;
}
$results = mysql_query("replace into CACHE_PAGES values(
'$CacheID',
'".addslashes($contents)."')
");
if(!$results) {
$smarty_obj-&gt;_trigger_error_msg("cache_handler: query failed.");
}
$return = $results;
break;
case 'clear':
// efface les données du cache
if(empty($cache_id) && empty($compile_id) && empty($tpl_file)) {
// les efface toutes
$results = mysql_query("delete from CACHE_PAGES");
} else {
$results = mysql_query("delete from CACHE_PAGES where CacheID='$CacheID'");
}
if(!$results) {
$smarty_obj-&gt;_trigger_error_msg("cache_handler: query failed.");
}
$return = $results;
break;
default:
// erreur, action inconnue
$smarty_obj-&gt;_trigger_error_msg("cache_handler: unknown action \"$action\"");
$return = false;
break;
}
mysql_close($link);
return $return;
}
?&gt;</programlisting>
</example>
</sect1>
<sect1 id="template.resources">
<title>Ressources</title>
<para>
Les templates peuvent provenir d'une grande variété de ressources. Quand vous
affichez ou récupérez un template, ou quand vous incluez un template
dans un autre template, vous fournissez un type de ressource, suivi
par le chemin approprié et le nom du template.
</para>
<sect2 id="templates.from.template.dir">
<title>Templates depuis $template_dir</title>
<para>
Les templates du répertoire $template_dir n'ont pas
besoin d'une ressource template, bien que vous puissiez utiliser
la ressource "file" pour être cohérent. Vous n'avez qu'à fournir
le chemin vers le template que vous voulez utiliser, relatif
au répertoire racine $template_dir.
</para>
<example>
<title>Utilisation de templates depuis $template_dir</title>
<programlisting>
// le script PHP
$smarty->display("index.tpl");
$smarty->display("admin/menu.tpl");
$smarty->display("file:admin/menu.tpl"); // le même que celui ci-dessus
{* le template Smarty *}
{include file="index.tpl"}
{include file="file:index.tpl"} {* le même que celui ci-dessus *}</programlisting>
</example>
</sect2>
<sect2 id="templates.from.any.dir">
<title>Templates à partir de n'importe quel répertoire</title>
<para>
Les templates en-dehors du répertoire $template_dir nécessitent
le type de ressource template, suivi du chemin absolu et du nom du
template.
</para>
<example>
<title>utilisation d'un template depuis n'importe quel répertoire</title>
<programlisting>
// le script PHP
$smarty->display("file:/export/templates/index.tpl");
$smarty->display("file:/path/to/my/templates/menu.tpl");
{* le template Smarty *}
{include file="file:/usr/local/share/templates/navigation.tpl"}</programlisting>
</example>
<sect3>
<title>Chemin de fichiers Windows</title>
<para>
Si vous utilisez Windows, les chemins de fichiers sont la plupart
du temps sur un disque identifié par une lettre (c:) au début du chemin.
Assurez-vous de bien mettre "file:" dans le chemin pour éviter des
conflits d'espace de nommage et obtenir les résultats escomptés.
</para>
<example>
<title>utilisation de templates avec des chemins de fichiers Windows</title>
<programlisting>
// le script PHP
$smarty->display("file:C:/export/templates/index.tpl");
$smarty->display("file:F:/path/to/my/templates/menu.tpl");
{* le template Smarty *}
{include file="file:D:/usr/local/share/templates/navigation.tpl"}</programlisting>
</example>
</sect3>
</sect2>
<sect2 id="templates.from.elsewhere">
<title>Templates depuis d'autres sources</title>
<para>
Vous pouvez récupérer les templates à partir n'importe quelle
source à laquelle vous avez accès avec PHP : base de données,
sockets, LDAP et ainsi de suite. Il suffit d'écrire les fonctions
de ressource plugins et de les enregistrer auprès de Smarty.
</para>
<para>
Reportez-vous à la section <link linkend="plugins.resources">ressource plugins</link>
pour plus d'informations sur les fonctions que vous êtes censé fournir.
</para>
<note>
<para>
Notez que vous ne pouvez pas écraser la ressource <literal>file</literal> native,
toutefois, vous pouvez fournir une ressource qui récupère un template depuis
le système de fichier par un autre moyen en l'enregistrant sous un autre
nom de ressource.
</para>
</note>
<example>
<title>utilisation de ressources utilisateurs</title>
<programlisting>
// le script PHP
// mettez ces fonctions quelque part dans votre application
function db_get_template ($tpl_name, &amp;$tpl_source, &amp;$smarty_obj)
{
// requête BD pour récupérer le template
// et remplir $tpl_source
$sql = new SQL;
$sql->query("select tpl_source
from my_table
where tpl_name='$tpl_name'");
if ($sql->num_rows) {
$tpl_source = $sql->record['tpl_source'];
return true;
} else {
return false;
}
}
function db_get_timestamp($tpl_name, &amp;$tpl_timestamp, &amp;$smarty_obj)
{
// requête BD pour remplir $tpl_timestamp
$sql = new SQL;
$sql->query("select tpl_timestamp
from my_table
where tpl_name='$tpl_name'");
if ($sql->num_rows) {
$tpl_timestamp = $sql->record['tpl_timestamp'];
return true;
} else {
return false;
}
}
function db_get_secure($tpl_name, &$smarty_obj)
{
// on suppose que tous les templates sont sûrs
return true;
}
function db_get_trusted($tpl_name, &$smarty_obj)
{
// pas utilisée pour les templates dans notre cas
}
// enregistre le nom de ressource "db"
$smarty->register_resource("db", array("db_get_template",
"db_get_timestamp",
"db_get_secure",
"db_get_trusted"));
// utilise la ressource depuis le script PHP
$smarty->display("db:index.tpl");
{* utilise la ressource depuis le template Smarty *}
{include file="db:/extras/navigation.tpl"}</programlisting>
</example>
</sect2>
<sect2 id="default.template.handler.function">
<title>Fonction de gestion de template par défaut</title>
<para>
Vous pouvez spécifier une fonction qui sera utilisée pour
récupérer le contenu d'un template dans le cas où le template
ne peut pas être récupéré depuis sa ressource. Une utilisation possible est
la création de templates à la volée.
</para>
<example>
<title>utilisation de la fonction de gestion de template par défaut</title>
<programlisting>
&lt;?php
// mettez cette fonction quelque part dans votre application
function make_template ($resource_type, $resource_name, &amp;$template_source, &amp;$template_timestamp, &amp;$smarty_obj)
{
if( $resource_type == 'file' ) {
if ( ! is_readable ( $resource_name )) {
// crée le fichier de template et renvoie le contenu
$template_source = "This is a new template.";
$template_timestamp = time();
$smarty_obj->_write_file($resource_name,$template_source);
return true;
}
} else {
// pas un fichier
return false;
}
}
// régle la fonction par défaut
$smarty->default_template_handler_func = 'make_template';
?&gt;</programlisting>
</example>
</sect2>
</sect1>
</chapter>
<chapter id="plugins">
<title>Etendre Smarty avec des plugins</title>
<para>
La version 2.0 a introduit l'architecture de plugin qui est
utilisée pour pratiquement toute les fonctionnalités
personnalisables de Smarty. Ceci comprend :
<itemizedlist spacing=compact>
<listitem><simpara>les fonctions</simpara></listitem>
<listitem><simpara>les modificateurs</simpara></listitem>
<listitem><simpara>les fonctions de blocs</simpara></listitem>
<listitem><simpara>les fonctions de compilation</simpara></listitem>
<listitem><simpara>les filtres de pré-compilation</simpara></listitem>
<listitem><simpara>les filtres de post-compilation</simpara></listitem>
<listitem><simpara>les filtres de sorties</simpara></listitem>
<listitem><simpara>les ressources</simpara></listitem>
<listitem><simpara>les insertions</simpara></listitem>
</itemizedlist>
A part pour les ressources, la compatibilité avec les anciennes
façons d'enregistrer les fonctions de gestion avec l'API register_
est conservée. Si vous n'avez pas utilisé cette API et que vous avez
à la place directement modifié les variables de classes
<literal>$custom_funcs</literal>, <literal>$custom_mods</literal> et
d'autres, vous devez alors modifier vos scripts pour utiliser
l'API ou convertir vos fonctionnalités personnalisées en plugins.
</para>
<sect1>
<title>Comment fonctionnent les plugins</title>
<para>
Les plugins sont toujours chargés à la demande. Seuls les modificateurs
de variables, les ressources, etc invoqués dans les scripts de templates
seront chargés. De plus, chaque plugin n'est chargé qu'une fois, et ce
même si vous avez plusieurs instances de Smarty qui tournent dans
la même requête.
</para>
<para>
Les filtres de post/pré-compilation et les filtres de sortie sont des cas
un peu spéciaux.
Comme ils ne sont pas mentionnés dans les templates, ils doivent être déclarés
ou chargés explicitement via les fonctions de l'API avant que le template
ne soit exécuté. L'ordre dans lequel les filtres multiples d'un même type
sont exécutés dépend de l'ordre dans lequel ils sont enregistrés ou chargés.
</para>
<para>
Il n'existe qu'un seul répertoire de plugin (pour des raisons de performances).
Pour installer un plugin, copiez-le simplement dans le répertoire et Smarty
l'utilisera automatiquement.
</para>
</sect1>
<sect1 id="plugins.naming.conventions">
<title>Conventions de nommage</title>
<para>
Les fichiers et les fonctions de plugins doivent suivre une convention
de nommage très spécifique pour être localisés par Smarty.
</para>
<para>
Les fichiers de plugins doivent être nommés de la façon suivante :
<blockquote>
<para>
<filename>
<replaceable>type</replaceable>.<replaceable>nom</replaceable>.php
</filename>
</para>
</blockquote>
</para>
<para>
Où <literal>type</literal> est l'une des valeurs suivantes :
<itemizedlist spacing=compact>
<listitem><simpara>function</simpara></listitem>
<listitem><simpara>modifier</simpara></listitem>
<listitem><simpara>block</simpara></listitem>
<listitem><simpara>compiler</simpara></listitem>
<listitem><simpara>prefilter</simpara></listitem>
<listitem><simpara>postfilter</simpara></listitem>
<listitem><simpara>outputfilter</simpara></listitem>
<listitem><simpara>resource</simpara></listitem>
<listitem><simpara>insert</simpara></listitem>
</itemizedlist>
</para>
<para>
Et <literal>nom</literal> doit être un identifiant valide (lettres, nombres
et underscore seulement).
</para>
<para>
Quelques exemples : <literal>function.html_select_date.php</literal>,
<literal>resource.db.php</literal>,
<literal>modifier.spacify.php</literal>.
</para>
<para>
Les fonctions de plugins dans les fichiers de plugins doivent être
nommées de la façon suivante :
<blockquote>
<para>
<function>smarty_<replaceable>type</replaceable>_<replaceable>nom</replaceable></function>
</para>
</blockquote>
</para>
<para>
Les significations de <literal>type</literal> et de <literal>nom</literal> sont les mêmes
que précédemment.
</para>
<para>
Smarty donnera des messages d'erreur approprié si le fichier de plugin
n'est pas trouvé, ou si le fichier ou la fonction de plugin ne sont
pas nommés correctement.
</para>
</sect1>
<sect1 id="plugins.writing">
<title>Ecrire des plugins</title>
<para>
Les plugins peuvent être soit chargés automatiquement par Smarty
depuis le système de fichier, soit être déclarés
pendant l'exécution via une fonction register_* de l'API. Ils peuvent
aussi être désalloués en utilisant une fonction unregister_* de
l'API.
</para>
<para>
Pour les plugins qui ne sont pas enregistrés pendant l'exécution, le nom
des fonctions n'ont pas à suivre la convention de nommage.
</para>
<para>
Si certaines fonctionnalités d'un plugin dépendent d'un autre plugin
(comme c'est le cas de certains plugins accompagnant Smarty), alors la manière appropriée
de charger le plugin est la suivante :
</para>
<programlisting>
require_once SMARTY_DIR . 'plugins/function.html_options.php';</programlisting>
<para>
Une règle générale est que chaque objet Smarty est toujours passé au plugin
en tant que dernier paramètre (à part pour les modificateurs).
</para>
</sect1>
<sect1 id="plugins.functions"><title>Les fonctions de templates</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>smarty_function_<replaceable>name</replaceable></function></funcdef>
<paramdef>array <parameter>$params</parameter></paramdef>
<paramdef>object <parameter>&$smarty</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Tous les attributs passés aux fonctions de template à partir du template
sont contenus dans le tableau associatif <parameter>$params</parameter>.
Vous pouvez accéder à ces valeurs soit directement, par exemple
<varname>$params['start']</varname>, soit en utilisant
<varname>extract($params)</varname> pour les importer dans la table
des symboles.
</para>
<para>
Le retour de la fonction sera substituée à la balise de fonction
du template (fonction <function>fetch</function> par exemple). Sinon,
la fonction peut simplement accomplir une autre tâche sans sortie
(la fonction <function>assign</function> par exemple)
</para>
<para>
Si la fonction a besoin d'assigner des variables aux templates ou d'utiliser
d'autres fonctionnalités fournies par Smarty, elle peut recevoir un
objet <parameter>$smarty</parameter> pour cela.
</para>
<para>
Référez-vous aussi à :
<link linkend="api.register.function">register_function()</link>,
<link linkend="api.unregister.function">unregister_function()</link>.
</para>
<para>
<example>
<title>fonction de plugin avec sortie</title>
<programlisting>
&lt;?php
/*
* Smarty plugin
* -------------------------------------------------------------
* Fichier : function.eightball.php
* Type : fonction
* Nom : eightball
* Rôle : renvoie une phrase magique au hasard
* -------------------------------------------------------------
*/
function smarty_function_eightball($params, &amp;$smarty)
{
$answers = array('Yes',
'No',
'No way',
'Outlook not so good',
'Ask again soon',
'Maybe in your reality');
$result = array_rand($answers);
return $answers[$result];
}
?&gt;</programlisting>
</example>
</para>
<para>
peut être utilisée dans le template de la façon suivante :
</para>
<programlisting>
Question: Will we ever have time travel?
Answer: {eightball}.</programlisting>
<para>
<example>
<title>fonction de plugin sans sortie</title>
<programlisting>
&lt;?php
/*
* Smarty plugin
* -------------------------------------------------------------
* Fichier : function.assign.php
* Type : fonction
* Nom : assign
* Purpose : assigne une valeur à une variable de template
* -------------------------------------------------------------
*/
function smarty_function_assign($params, &amp;$smarty)
{
extract($params);
if (empty($var)) {
$smarty->trigger_error("assign: missing 'var' parameter");
return;
}
if (!in_array('value', array_keys($params))) {
$smarty->trigger_error("assign: missing 'value' parameter");
return;
}
$smarty->assign($var, $value);
}
?&gt;</programlisting>
</example>
</para>
</sect1>
<sect1 id="plugins.modifiers"><title>Modificateurs</title>
<para>
Les modificateurs sont des petites fonctions appliquées à une variable
de template avant qu'elle ne soit affichée ou utilisée dans un autre contexte.
Les modificateurs peuvent être chaînés entre eux.
</para>
<funcsynopsis>
<funcprototype>
<funcdef>mixed <function>smarty_modifier_<replaceable>name</replaceable></function></funcdef>
<paramdef>mixed <parameter>$value</parameter></paramdef>
<paramdef>[mixed <parameter>$param1</parameter>, ...]</paramdef>
</funcprototype>
</funcsynopsis>
<para>
Le premier paramètre passé au modificateur est la valeur
sur laquelle le modificateur est supposé opérer. Les autres paramètres
peuvent être optionnels, dépendant de quel genre d'opération doit être
effectué.
</para>
<para>
Le modificateur doit retourner le résultat de son exécution.
</para>
<para>
Regardez aussi
<link linkend="api.register.modifier">register_modifier()</link>,
<link linkend="api.unregister.modifier">unregister_modifier()</link>.
</para>
<example>
<title>plugin modificateur simple</title>
<para>
Ce plugin est un alias d'une fonction PHP. Il n'a aucun paramètre
supplémentaires.
</para>
<programlisting>
&lt;?php
/*
* Smarty plugin
* -------------------------------------------------------------
* Fichier : modifier.capitalize.php
* Type : modificateur
* Name : capitalize
* Rôle : met une majuscule aux mots d'une phrase
* -------------------------------------------------------------
*/
function smarty_modifier_capitalize($string)
{
return ucwords($string);
}
?&gt;</programlisting>
</example>
<para></para>
<example>
<title>un plugin modificateur un peu plus complexe</title>
<programlisting>
&lt;?php
/*
* Smarty plugin
* -------------------------------------------------------------
* Fichier : modifier.truncate.php
* Type : modificateur
* Name : truncate
* Rôle : Tronque une chaîne à une certaine longueur si
* nécessaire, la coupe optionnellement au milieu
* d'un mot et ajoute la chaîne $etc
* -------------------------------------------------------------
*/
function smarty_modifier_truncate($string, $length = 80, $etc = '...',
$break_words = false)
{
if ($length == 0)
return '';
if (strlen($string) > $length) {
$length -= strlen($etc);
$fragment = substr($string, 0, $length+1);
if ($break_words)
$fragment = substr($fragment, 0, -1);
else
$fragment = preg_replace('/\s+(\S+)?$/', '', $fragment);
return $fragment.$etc;
} else
return $string;
}
?&gt;</programlisting>
</example>
</sect1>
<sect1 id="plugins.block.functions"><title>Fonctions de blocs</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>smarty_block_<replaceable>name</replaceable></function></funcdef>
<paramdef>array <parameter>$params</parameter></paramdef>
<paramdef>mixed <parameter>$content</parameter></paramdef>
<paramdef>object <parameter>&$smarty</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Les fonctions de blocs sont des fonctions de la forme {func} .. {/func}.
En d'autres mots, elles englobent des blocs de template et opèrent sur les
contenus de ces blocs. Les fonctions de blocs ont la priorité sur les
fonctions utilisateurs de même nom, ce qui signifie que vous ne
pouvez avoir une fonction utilisateur {func} et une fonction de bloc
{func} .. {/func}.
</para>
<para>
L'implémentation de votre fonction est appelée deux fois par Smarty :
une fois pour la balise ouvrante et une autre fois pour la balise
fermante.
</para>
<para>
Seule la balise ouvrante d'une fonction de bloc peut avoir des attributs.
Tous les attributs passés par le template aux fonctions de templates sont
contenues dans le tableau associatif <parameter>$params</parameter>.
Vous pouvez accéder à ces valeurs soit directement, par exemple
<varname>$params['start']</varname>, soit en utilisant
<varname>extract($params)</varname> pour les importer dans la table
des symboles. Votre fonction a aussi accès aux attributs de la balise
ouvrante quand c'est la balise fermante qui est exécutée.
</para>
<para>
La valeur de la variable <parameter>$content</parameter> est différente
selon si votre fonction est appelée pour la balise ouvrante ou la
balise fermante. Si c'est pour la balise ouvrante, elle sera à
<literal>null</literal> et si c'est la balise fermante elle sera
égale au contenu du bloc de template. Notez que le bloc de template
aura déjà été exécuté par Smarty, vous recevrez donc la sortie du
template et non sa source.
</para>
<para>
Si vous imbriqué des fonctions de bloc, il est possible de connaître
la fonction de bloc parente grâce à la variable <varname>$smarty->_tag_stack</varname>.
Faites un var_dump() dessus et la structure devrait apparaître.
</para>
<para>
Regardez aussi :
<link linkend="api.register.block">register_block()</link>,
<link linkend="api.unregister.block">unregister_block()</link>.
</para>
<example>
<title>fonction de bloc</title>
<programlisting>
&lt;?php
/*
* Smarty plugin
* -------------------------------------------------------------
* Fichier : block.translate.php
* Type : bloc
* Nom : translate
* Rôle : traduire un bloc de texte
* -------------------------------------------------------------
*/
function smarty_block_translate($params, $content, &amp;$smarty)
{
if ($content) {
$lang = $params['lang'];
// fait une traduction de $content
echo $translation;
}
}</programlisting>
</example>
</sect1>
<sect1 id="plugins.compiler.functions"><title>Fonctions de compilation</title>
<para>
Les fonctions de compilation sont appelées durant la compilation du template.
Elles sont utiles pour injecter du code PHP ou du contenu "statique variant
avec le temps" (bandeau de pub par ex.). Si une fonction de compilation et
une fonction personnalisée ont le même
nom, la fonction de compilation a priorité.
</para>
<funcsynopsis>
<funcprototype>
<funcdef>mixed <function>smarty_compiler_<replaceable>name</replaceable></function></funcdef>
<paramdef>string <parameter>$tag_arg</parameter></paramdef>
<paramdef>object <parameter>&$smarty</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Les fonctions de compilation ont deux paramètres : une chaîne contenant
la balise - en gros, tout, depuis le nom de la fonction jusqu'au délimiteur de fin - et
l'objet Smarty. Elles sont censées retourner le code PHP qui doit être
injecté dans le template compilé.
</para>
<para>
Regardez aussi
<link linkend="api.register.compiler.function">register_compiler_function()</link>,
<link linkend="api.unregister.compiler.function">unregister_compiler_function()</link>.
</para>
<example>
<title>fonction de compilation simple</title>
<programlisting>
&lt;?php
/*
* Smarty plugin
* -------------------------------------------------------------
* Fichier : compiler.tplheader.php
* Type : compilation
* Nom : tplheader
* Rôle : Renvoie l'en-tête contenant le nom du fichier
* source et le temps de compilation.
* -------------------------------------------------------------
*/
function smarty_compiler_tplheader($tag_arg, &$smarty)
{
return "\necho '" . $smarty-&gt;_current_file . " compiled at " . date('Y-m-d H:M'). "';";
}
?&gt;</programlisting>
<para>
Cette fonction peut-être appelé depuis le template comme suivant :
</para>
<programlisting>
{* cette fonction n'est executée que lors de la compilation *}
{tplheader}</programlisting>
<para>
Le code PHP résultant dans les templates compilés ressemblerait à ça :
</para>
<programlisting>
&lt;php
echo 'index.tpl compiled at 2002-02-20 20:02';
?&gt;</programlisting>
</example>
</sect1>
<sect1 id="plugins.prefilters.postfilters">
<title>filtres de pré-compilation/filtres de post-compilation</title>
<para>
Les filtres de pré-compilation et les filtres de post-compilation ont des concepts très
proches. Ils différent dans leur exécution, plus précisément dans le
moment où ils sont exécutés.
</para>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>smarty_prefilter_<replaceable>name</replaceable></function></funcdef>
<paramdef>string <parameter>$source</parameter></paramdef>
<paramdef>object <parameter>&$smarty</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Les filtres de pré-compilation sont utilisés pour transformer la source d'un template
juste avant la compilation. Le premier paramètre passé à la fonction
de filtre de pré-compilation est la source du template, éventuellement modifiée par
d'autres filtre de pré-compilations. Le plugin est supposé retourner la source modifiée.
Notez que cette source n'est sauvegardée nulle part, elle est seulement
utilisé pour la compilation.
</para>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>smarty_postfilter_<replaceable>name</replaceable></function></funcdef>
<paramdef>string <parameter>$compiled</parameter></paramdef>
<paramdef>object <parameter>&$smarty</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Les filtres de post-compilation sont utilisés pour modifier la sortie du template
(le code PHP) juste après que la compilation a été faite mais juste
avant que le template ne soit sauvegardé sur le système de fichiers.
Le premier paramètre passé à la fonction de filtre de post-compilation est le code
du template compilé, éventuellement déjà modifié par d'autres filtre de post-compilations.
Le plugin est censé retourner la version modifié du code.
</para>
<example>
<title>plugin de filtre de post-compilation</title>
<programlisting>
&lt;?php
/*
* Smarty plugin
* -------------------------------------------------------------
* Fichier : prefilter.pre01.php
* Type : filtre de pré-compilation
* Nom : pre01
* Rôle : Passe les balises HTML en minuscules.
* -------------------------------------------------------------
*/
function smarty_prefilter_pre01($source, &$smarty)
{
return preg_replace('!&lt;(\w+)[^&gt;]+&gt;!e', 'strtolower("$1")', $source);
}
?&gt;</programlisting>
</example>
<para></para>
<example>
<title>plugin de filtre de post-compilation</title>
<programlisting>
&lt;?php
/*
* Smarty plugin
* -------------------------------------------------------------
* Fichier : postfilter.post01.php
* Type: filtre de post-compilation
* Nom : post01
* Rôle : Renvoie du code qui liste toutes les variables
* du template.
* -------------------------------------------------------------
*/
function smarty_postfilter_post01($compiled, &$smarty)
{
$compiled = "&lt;pre&gt;\n&lt;?php print_r(\$this-&gt;get_template_vars()); ?&gt;\n&lt;/pre&gt;" . $compiled;
return $compiled;
}
?&gt;</programlisting>
</example>
</sect1>
<sect1 id="plugins.outputfilters"><title>Filtres de sortie</title>
<para>
Les plugins de filtres de sortie opèrent sur la sortie du template,
après que le template a été chargé et exécuté, mais avant que
la sortie ne soit affichée.
</para>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>smarty_outputfilter_<replaceable>name</replaceable></function></funcdef>
<paramdef>string <parameter>$template_output</parameter></paramdef>
<paramdef>object <parameter>&$smarty</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Le premier paramètre passé à la fonction du filtre de sortie est la
sortie du template qui doit être modifiée et le second paramètre
est l'instance de Smarty appelant le plugin. Le plugin est supposé
faire un traitement et en retourner le résultat.
</para>
<example>
<title>plugin de filtre de sortie</title>
<programlisting>
/*
* Smarty plugin
* -------------------------------------------------------------
* Fichier : outputfilter.protect_email.php
* Type : filtre de sortie
* Nom : protect_email
* Rôle: Convertie les @ en %40 pour protéger des
* robots spammers.
* -------------------------------------------------------------
*/
function smarty_outputfilter_protect_email($output, &$smarty)
{
return preg_replace('!(\S+)@([a-zA-Z0-9\.\-]+\.([a-zA-Z]{2,3}|[0-9]{1,3}))!',
'$1%40$2', $output);
}
</programlisting>
</example>
</sect1>
<sect1 id="plugins.resources"><title>Ressources</title>
<para>
Les plugins ressources sont un moyen générique de fournir des sources
de templates ou des composants de scripts PHP à Smarty. Quelques exemples
de ressources : bases de données, LDAP, mémoire partagée, sockets, et ainsi
de suite.
</para>
<para>
Il y au total 4 fonctions qui ont besoin d'être enregistrées pour
chaque type de ressource. Chaque fonction reçoit le nom de la ressource demandée
comme premier paramètre et l'objet Smarty comme dernier paramètre.
Les autres paramètres dépendent de la fonction.
</para>
<funcsynopsis>
<funcprototype>
<funcdef>bool <function>smarty_resource_<replaceable>name</replaceable>_source</function></funcdef>
<paramdef>string <parameter>$rsrc_name</parameter></paramdef>
<paramdef>string <parameter>&$source</parameter></paramdef>
<paramdef>object <parameter>&$smarty</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>bool <function>smarty_resource_<replaceable>name</replaceable>_timestamp</function></funcdef>
<paramdef>string <parameter>$rsrc_name</parameter></paramdef>
<paramdef>int <parameter>&$timestamp</parameter></paramdef>
<paramdef>object <parameter>&$smarty</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>bool <function>smarty_resource_<replaceable>name</replaceable>_secure</function></funcdef>
<paramdef>string <parameter>$rsrc_name</parameter></paramdef>
<paramdef>object <parameter>&$smarty</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>bool <function>smarty_resource_<replaceable>name</replaceable>_trusted</function></funcdef>
<paramdef>string <parameter>$rsrc_name</parameter></paramdef>
<paramdef>object <parameter>&$smarty</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
La première fonction est supposée récupérer la ressource. Son second
paramètre est une variable passée par référence où le résultat doit être
stocké. La fonction est supposée retourner <literal>true</literal> si
elle réussi à récupérer la ressource et <literal>false</literal> sinon.
</para>
<para>
La seconde fonction est supposée récupérer la date de dernière modification
de la ressource demandée (comme un timestamp UNIX). Le second paramètre
est une variable passée par référence dans laquelle la date doit
être stockée. La fonction est supposée renvoyer <literal>true</literal> si elle
a réussi à récupérer la date et <literal>false</literal> sinon.
</para>
<para>
La troisième fonction est supposée retourner <literal>true</literal>
ou <literal>false</literal> selon si la ressource demandée est sûre
ou non. La fonction est utilisée seulement pour les ressources templates
mais doit tout de même être définie.
</para>
<para>
La quatrième fonction est supposée retourner <literal>true</literal>
ou <literal>false</literal> selon si on peut faire confiance ou
non à la ressource demandée. Cette fonction est utilisée seulement
pour les composants de scripts PHP demandés par les balises
<command>include_php</command> ou <command>insert</command>
ayant un attribut <structfield>src</structfield>. Quoiqu'il en soit,
elle doit être définie pour les ressources templates.
</para>
<para>
Regardez aussi
<link linkend="api.register.resource">register_resource()</link>,
<link linkend="api.unregister.resource">unregister_resource()</link>.
</para>
<example>
<title>resource plugin</title>
<programlisting>
&lt;?php
/*
* Smarty plugin
* -------------------------------------------------------------
* Fichier : resource.db.php
* Type : ressource
* Nom : db
* Rôle : Récupère des templates depuis une base de données
* -------------------------------------------------------------
*/
function smarty_resource_db_source($tpl_name, &amp;$tpl_source, &amp;$smarty)
{
// fait des requêtes BD pour récupérer votre template
// et remplir $tpl_source
$sql = new SQL;
$sql->query("select tpl_source
from my_table
where tpl_name='$tpl_name'");
if ($sql->num_rows) {
$tpl_source = $sql->record['tpl_source'];
return true;
} else {
return false;
}
}
function smarty_resource_db_timestamp($tpl_name, &amp;$tpl_timestamp, &amp;$smarty)
{
// fait des requêtes BD pour remplir $tpl_timestamp
$sql = new SQL;
$sql->query("select tpl_timestamp
from my_table
where tpl_name='$tpl_name'");
if ($sql->num_rows) {
$tpl_timestamp = $sql->record['tpl_timestamp'];
return true;
} else {
return false;
}
}
function smarty_resource_db_secure($tpl_name, &amp;$smarty)
{
// suppose que tous les templates sont sûrs
return true;
}
function smarty_resource_db_trusted($tpl_name, &amp;$smarty)
{
// inutilisée pour les templates
}
?&gt;</programlisting>
</example>
</sect1>
<sect1 id="plugins.inserts"><title>Insertions</title>
<para>
Les plugins d'insertion sont utilisés pour implémenter les fonctions
qui sont appelées par les balises
<link linkend="language.function.insert"><command>insert</command></link>
dans les templates.
</para>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>smarty_insert_<replaceable>name</replaceable></function></funcdef>
<paramdef>array <parameter>$params</parameter></paramdef>
<paramdef>object <parameter>&$smarty</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Le premier paramètre passé à la fonction est une tableau associatif
d'attributs. Vous pouvez accéder à ces valeurs soit directement, par exemple
<varname>$params['start']</varname>, soit en utilisant
<varname>extract($params)</varname> pour les importer dans la table
des symboles.
</para>
<para>
La fonction d'insertion est supposée retourner le résultat qui sera
substitué à la balise <command>insert</command> dans le template.
</para>
<example>
<title>plugin d'insertion</title>
<programlisting>
&lt;?php
/*
* Smarty plugin
* -------------------------------------------------------------
* Fichier : insert.time.php
* Type : temps
* Nom : time
* Rôle : Insert la date/heure courante conformément
* au format
* -------------------------------------------------------------
*/
function smarty_insert_time($params, &amp;$smarty)
{
if (empty($params['format'])) {
$smarty->trigger_error("insert time: missing 'format' parameter");
return;
}
$datetime = strftime($params['format']);
return $datetime;
}
?&gt;</programlisting>
</example>
</sect1>
</chapter>
</part>
Reference in New Issue View Git Blame Copy Permalink