Etendre Smarty avec des plugins
La version 2.0 a introduit l'architecture de plugin qui est
utilisTe pour pratiquement toute les fonctionnalitTs
personnalisables de Smarty. Ceci comprend :
les fonctionsles modificateursles fonctions de blocsles fonctions de compilationles filtres de prT-compilationles filtres de post-compilationles filtres de sortiesles ressourcesles insertions
A part pour les ressources, la compatibilitT avec les anciennes
fatons d'enregistrer les fonctions de gestion avec l'API register_
est conservTe. Si vous n'avez pas utilisT cette API et que vous avez
a la place directement modifiT les variables de classes
$custom_funcs, $custom_mods et
d'autres, vous devez alors modifier vos scripts pour utiliser
l'API ou convertir vos fonctionnalitTs personnalisTes en plugins.
Comment fonctionnent les plugins
Les plugins sont toujours chargTs a la demande. Seuls les modificateurs
de variables, les ressources, etc invoquTs dans les scripts de templates
seront chargTs. De plus, chaque plugin n'est chargT qu'une fois, et ce
mOme si vous avez plusieurs instances de Smarty qui tournent dans
la mOme requOte.
Les filtres de post/prT-compilation et les filtres de sortie sont des cas
un peu spTciaux.
Comme ils ne sont pas mentionnTs dans les templates, ils doivent Otre dTclarTs
ou chargTs explicitement via les fonctions de l'API avant que le template
ne soit exTcutT. L'ordre dans lequel les filtres multiples d'un mOme type
sont exTcutTs dTpend de l'ordre dans lequel ils sont enregistrTs ou chargTs.
Il n'existe qu'un seul rTpertoire de plugin (pour des raisons de performances).
Pour installer un plugin, copiez-le simplement dans le rTpertoire et Smarty
l'utilisera automatiquement.
Conventions de nommage
Les fichiers et les fonctions de plugins doivent suivre une convention
de nommage trFs spTcifique pour Otre localisTs par Smarty.
Les fichiers de plugins doivent Otre nommTs de la faton suivante :
type.nom.php
Oś type est l'une des valeurs suivantes :
functionmodifierblockcompilerprefilterpostfilteroutputfilterresourceinsert
Et nom doit Otre un identifiant valide (lettres, nombres
et underscore seulement).
Quelques exemples : function.html_select_date.php,
resource.db.php,
modifier.spacify.php.
Les fonctions de plugins dans les fichiers de plugins doivent Otre
nommTes de la faton suivante :
smarty_type_nom
Les significations de type et de nom sont les mOmes
que prTcTdemment.
Smarty donnera des messages d'erreur appropriT si le fichier de plugin
n'est pas trouvT, ou si le fichier ou la fonction de plugin ne sont
pas nommTs correctement.
Ecrire des plugins
Les plugins peuvent Otre soit chargTs automatiquement par Smarty
depuis le systFme de fichier, soit Otre dTclarTs
pendant l'exTcution via une fonction register_* de l'API. Ils peuvent
aussi Otre dTsallouTs en utilisant une fonction unregister_* de
l'API.
Pour les plugins qui ne sont pas enregistrTs pendant l'exTcution, le nom
des fonctions n'ont pas a suivre la convention de nommage.
Si certaines fonctionnalitTs d'un plugin dTpendent d'un autre plugin
(comme c'est le cas de certains plugins accompagnant Smarty), alors la maniFre appropriTe
de charger le plugin est la suivante :
require_once SMARTY_DIR . 'plugins/function.html_options.php';
Une rFgle gTnTrale est que chaque objet Smarty est toujours passT au plugin
en tant que dernier paramFtre (a part pour les modificateurs).
Les fonctions de templatesvoid smarty_function_namearray $paramsobject &$smarty
Tous les attributs passTs aux fonctions de template a partir du template
sont contenus dans le tableau associatif $params.
Vous pouvez accTder a ces valeurs soit directement, par exemple
$params['start'], soit en utilisant
extract($params) pour les importer dans la table
des symboles.
Le retour de la fonction sera substituTe a la balise de fonction
du template (fonction fetch par exemple). Sinon,
la fonction peut simplement accomplir une autre tGche sans sortie
(la fonction assign par exemple)
Si la fonction a besoin d'assigner des variables aux templates ou d'utiliser
d'autres fonctionnalitTs fournies par Smarty, elle peut recevoir un
objet $smarty pour cela.
RTfTrez-vous aussi a :
register_function(),
unregister_function().
fonction de plugin avec sortie
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* Fichier : function.eightball.php
* Type : fonction
* Nom : eightball
* R(le : renvoie une phrase magique au hasard
* -------------------------------------------------------------
*/
function smarty_function_eightball($params, &$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];
}
?>
peut Otre utilisTe dans le template de la faton suivante :
Question: Will we ever have time travel?
Answer: {eightball}.fonction de plugin sans sortie
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* Fichier : function.assign.php
* Type : fonction
* Nom : assign
* Purpose : assigne une valeur a une variable de template
* -------------------------------------------------------------
*/
function smarty_function_assign($params, &$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);
}
?>Modificateurs
Les modificateurs sont des petites fonctions appliquTes a une variable
de template avant qu'elle ne soit affichTe ou utilisTe dans un autre contexte.
Les modificateurs peuvent Otre chaenTs entre eux.
mixed smarty_modifier_namemixed $value[mixed $param1, ...]
Le premier paramFtre passT au modificateur est la valeur
sur laquelle le modificateur est supposT opTrer. Les autres paramFtres
peuvent Otre optionnels, dTpendant de quel genre d'opTration doit Otre
effectuT.
Le modificateur doit retourner le rTsultat de son exTcution.
Regardez aussi
register_modifier(),
unregister_modifier().
plugin modificateur simple
Ce plugin est un alias d'une fonction PHP. Il n'a aucun paramFtre
supplTmentaires.
<?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);
}
?>un plugin modificateur un peu plus complexe
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* Fichier : modifier.truncate.php
* Type : modificateur
* Name : truncate
* R(le : Tronque une chaene a une certaine longueur si
* nTcessaire, la coupe optionnellement au milieu
* d'un mot et ajoute la chaene $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;
}
?>Fonctions de blocsvoid smarty_block_namearray $paramsmixed $contentobject &$smarty
Les fonctions de blocs sont des fonctions de la forme {func} .. {/func}.
En d'autres mots, elles englobent des blocs de template et opFrent sur les
contenus de ces blocs. Les fonctions de blocs ont la prioritT sur les
fonctions utilisateurs de mOme nom, ce qui signifie que vous ne
pouvez avoir une fonction utilisateur {func} et une fonction de bloc
{func} .. {/func}.
L'implTmentation de votre fonction est appelTe deux fois par Smarty :
une fois pour la balise ouvrante et une autre fois pour la balise
fermante.
Seule la balise ouvrante d'une fonction de bloc peut avoir des attributs.
Tous les attributs passTs par le template aux fonctions de templates sont
contenues dans le tableau associatif $params.
Vous pouvez accTder a ces valeurs soit directement, par exemple
$params['start'], soit en utilisant
extract($params) pour les importer dans la table
des symboles. Votre fonction a aussi accFs aux attributs de la balise
ouvrante quand c'est la balise fermante qui est exTcutTe.
La valeur de la variable $content est diffTrente
selon si votre fonction est appelTe pour la balise ouvrante ou la
balise fermante. Si c'est pour la balise ouvrante, elle sera a
null et si c'est la balise fermante elle sera
Tgale au contenu du bloc de template. Notez que le bloc de template
aura dTja TtT exTcutT par Smarty, vous recevrez donc la sortie du
template et non sa source.
Si vous imbriquT des fonctions de bloc, il est possible de connaetre
la fonction de bloc parente grGce a la variable $smarty->_tag_stack.
Faites un var_dump() dessus et la structure devrait apparaetre.
Regardez aussi :
register_block(),
unregister_block().
fonction de bloc
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* Fichier : block.translate.php
* Type : bloc
* Nom : translate
* R(le : traduire un bloc de texte
* -------------------------------------------------------------
*/
function smarty_block_translate($params, $content, &$smarty)
{
if ($content) {
$lang = $params['lang'];
// fait une traduction de $content
echo $translation;
}
}Fonctions de compilation
Les fonctions de compilation sont appelTes 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 personnalisTe ont le mOme
nom, la fonction de compilation a prioritT.
mixed smarty_compiler_namestring $tag_argobject &$smarty
Les fonctions de compilation ont deux paramFtres : une chaene contenant
la balise - en gros, tout, depuis le nom de la fonction jusqu'au dTlimiteur de fin - et
l'objet Smarty. Elles sont censTes retourner le code PHP qui doit Otre
injectT dans le template compilT.
Regardez aussi
register_compiler_function(),
unregister_compiler_function().
fonction de compilation simple
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* Fichier : compiler.tplheader.php
* Type : compilation
* Nom : tplheader
* R(le : Renvoie l'en-tOte contenant le nom du fichier
* source et le temps de compilation.
* -------------------------------------------------------------
*/
function smarty_compiler_tplheader($tag_arg, &$smarty)
{
return "\necho '" . $smarty->_current_file . " compiled at " . date('Y-m-d H:M'). "';";
}
?>
Cette fonction peut-Otre appelT depuis le template comme suivant :
{* cette fonction n'est executTe que lors de la compilation *}
{tplheader}
Le code PHP rTsultant dans les templates compilTs ressemblerait a ta :
<php
echo 'index.tpl compiled at 2002-02-20 20:02';
?>filtres de prT-compilation/filtres de post-compilation
Les filtres de prT-compilation et les filtres de post-compilation ont des concepts trFs
proches. Ils diffTrent dans leur exTcution, plus prTcisTment dans le
moment oś ils sont exTcutTs.
string smarty_prefilter_namestring $sourceobject &$smarty
Les filtres de prT-compilation sont utilisTs pour transformer la source d'un template
juste avant la compilation. Le premier paramFtre passT a la fonction
de filtre de prT-compilation est la source du template, Tventuellement modifiTe par
d'autres filtre de prT-compilations. Le plugin est supposT retourner la source modifiTe.
Notez que cette source n'est sauvegardTe nulle part, elle est seulement
utilisT pour la compilation.
string smarty_postfilter_namestring $compiledobject &$smarty
Les filtres de post-compilation sont utilisTs pour modifier la sortie du template
(le code PHP) juste aprFs que la compilation a TtT faite mais juste
avant que le template ne soit sauvegardT sur le systFme de fichiers.
Le premier paramFtre passT a la fonction de filtre de post-compilation est le code
du template compilT, Tventuellement dTja modifiT par d'autres filtre de post-compilations.
Le plugin est censT retourner la version modifiT du code.
plugin de filtre de post-compilation
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* Fichier : prefilter.pre01.php
* Type : filtre de prT-compilation
* Nom : pre01
* R(le : Passe les balises HTML en minuscules.
* -------------------------------------------------------------
*/
function smarty_prefilter_pre01($source, &$smarty)
{
return preg_replace('!<(\w+)[^>]+>!e', 'strtolower("$1")', $source);
}
?>plugin de filtre de post-compilation
<?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 = "<pre>\n<?php print_r(\$this->get_template_vars()); ?>\n</pre>" . $compiled;
return $compiled;
}
?>Filtres de sortie
Les plugins de filtres de sortie opFrent sur la sortie du template,
aprFs que le template a TtT chargT et exTcutT, mais avant que
la sortie ne soit affichTe.
string smarty_outputfilter_namestring $template_outputobject &$smarty
Le premier paramFtre passT a la fonction du filtre de sortie est la
sortie du template qui doit Otre modifiTe et le second paramFtre
est l'instance de Smarty appelant le plugin. Le plugin est supposT
faire un traitement et en retourner le rTsultat.
plugin de filtre de sortie
/*
* Smarty plugin
* -------------------------------------------------------------
* Fichier : outputfilter.protect_email.php
* Type : filtre de sortie
* Nom : protect_email
* R(le: Convertie les @ en %40 pour protTger 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);
}
Ressources
Les plugins ressources sont un moyen gTnTrique de fournir des sources
de templates ou des composants de scripts PHP a Smarty. Quelques exemples
de ressources : bases de donnTes, LDAP, mTmoire partagTe, sockets, et ainsi
de suite.
Il y au total 4 fonctions qui ont besoin d'Otre enregistrTes pour
chaque type de ressource. Chaque fonction retoit le nom de la ressource demandTe
comme premier paramFtre et l'objet Smarty comme dernier paramFtre.
Les autres paramFtres dTpendent de la fonction.
bool smarty_resource_name_sourcestring $rsrc_namestring &$sourceobject &$smartybool smarty_resource_name_timestampstring $rsrc_nameint &$timestampobject &$smartybool smarty_resource_name_securestring $rsrc_nameobject &$smartybool smarty_resource_name_trustedstring $rsrc_nameobject &$smarty
La premiFre fonction est supposTe rTcupTrer la ressource. Son second
paramFtre est une variable passTe par rTfTrence oś le rTsultat doit Otre
stockT. La fonction est supposTe retourner true si
elle rTussi a rTcupTrer la ressource et false sinon.
La seconde fonction est supposTe rTcupTrer la date de derniFre modification
de la ressource demandTe (comme un timestamp UNIX). Le second paramFtre
est une variable passTe par rTfTrence dans laquelle la date doit
Otre stockTe. La fonction est supposTe renvoyer true si elle
a rTussi a rTcupTrer la date et false sinon.
La troisiFme fonction est supposTe retourner true
ou false selon si la ressource demandTe est svre
ou non. La fonction est utilisTe seulement pour les ressources templates
mais doit tout de mOme Otre dTfinie.
La quatriFme fonction est supposTe retourner true
ou false selon si on peut faire confiance ou
non a la ressource demandTe. Cette fonction est utilisTe seulement
pour les composants de scripts PHP demandTs par les balises
include_php ou insert
ayant un attribut src. Quoiqu'il en soit,
elle doit Otre dTfinie pour les ressources templates.
Regardez aussi
register_resource(),
unregister_resource().
resource plugin
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* Fichier : resource.db.php
* Type : ressource
* Nom : db
* R(le : RTcupFre des templates depuis une base de donnTes
* -------------------------------------------------------------
*/
function smarty_resource_db_source($tpl_name, &$tpl_source, &$smarty)
{
// fait des requOtes BD pour rTcupTrer 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, &$tpl_timestamp, &$smarty)
{
// fait des requOtes 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, &$smarty)
{
// suppose que tous les templates sont svrs
return true;
}
function smarty_resource_db_trusted($tpl_name, &$smarty)
{
// inutilisTe pour les templates
}
?>Insertions
Les plugins d'insertion sont utilisTs pour implTmenter les fonctions
qui sont appelTes par les balises
insert
dans les templates.
string smarty_insert_namearray $paramsobject &$smarty
Le premier paramFtre passT a la fonction est une tableau associatif
d'attributs. Vous pouvez accTder a ces valeurs soit directement, par exemple
$params['start'], soit en utilisant
extract($params) pour les importer dans la table
des symboles.
La fonction d'insertion est supposTe retourner le rTsultat qui sera
substituT a la balise insert dans le template.
plugin d'insertion
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* Fichier : insert.time.php
* Type : temps
* Nom : time
* R(le : Insert la date/heure courante conformTment
* au format
* -------------------------------------------------------------
*/
function smarty_insert_time($params, &$smarty)
{
if (empty($params['format'])) {
$smarty->trigger_error("insert time: missing 'format' parameter");
return;
}
$datetime = strftime($params['format']);
return $datetime;
}
?>