mirror of
https://github.com/smarty-php/smarty.git
synced 2026-02-04 14:25:22 +01:00
527 lines
18 KiB
XML
527 lines
18 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
||
<!-- $Revision$ -->
|
||
<chapter id="advanced.features">
|
||
<title>FonctionnalitTs avancTes</title>
|
||
<sect1 id="advanced.features.objects">
|
||
<title>Objets</title>
|
||
<para>
|
||
Smarty donne l'accFs aux objets PHP a travers les templates. Il y
|
||
a 2 moyens d'y avoir accFs. Le premier consiste a allouer les objets
|
||
au template puis de les utiliser avec une syntaxe similaire a celles
|
||
des fonctions personnalisTes. Le deuxiFme moyen consiste a allouer
|
||
des objets aux templates et de les utiliser comme n'importe quelle
|
||
variable. La premiFre mTthode a une syntaxe beaucoup plus sympathique.
|
||
Elle est aussi plus sTcurisTe, puisqu'un objet allouT ne peut avoir accFs
|
||
qu'a certaines mTthodes et propriTtTs. NTanmoins, un objet allouT
|
||
ne peut pas avoir de lien sur lui-mOme ou Otre mis dans un tableau
|
||
d'objet, etc. Vous devez choisir la mTthode qui correspond a vos
|
||
besoins, mais tGchez d'utiliser la premiFre mTthode autant que possible
|
||
afin de rTduire la syntaxe des templates au minimum.
|
||
</para>
|
||
<para>
|
||
Si l'option de sTcuritT est activTe, aucune mTthode ou fonctions privTes
|
||
n'est accessible (commentant par "_"). S'il existe une mTthode et une
|
||
propriTtT du mOme nom, c'est la mTthode qui sera utilisTe.
|
||
</para>
|
||
<para>
|
||
Vous pouvez restreindre l'accFs aux mTthodes et aux propriTtTs en
|
||
les listant dans un tableau en tant que troisiFme paramFtre
|
||
d'allocation.
|
||
</para>
|
||
<para>
|
||
Par dTfaut, les paramFtres passTs aux objets depuis le templates le sont de la
|
||
mOme faton que les fonctions utilisateurs les rTcupFrent.
|
||
Le premier paramFtre correspond a un tableau associatif, le second a l'objet
|
||
Smarty. Si vous souhaitez que les paramFtres soient passTes un a un, comme
|
||
dans un appel traditionnel, dTfinissez registration, quatriFme paramFtre optionnel,
|
||
a false.
|
||
</para>
|
||
<example>
|
||
<title>utilisation d'un objet allouT ou assignT</title>
|
||
<programlisting>
|
||
<?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'accFs a certaines mTthodes et propriTtTs en les listant
|
||
$smarty->register_object("foobar",$myobj,array('meth1','meth2','prop1'));
|
||
// pour utiliser le format habituel de paramFtre objet, passez le boolTen = false
|
||
$smarty->register_object("foobar",$myobj,null,false);
|
||
|
||
// on peut aussi assigner des objets. Assignez par rTfTrence quand c'est possible
|
||
$smarty->assign_by_ref("myobj", $myobj);
|
||
|
||
$smarty->display("index.tpl");
|
||
?>
|
||
|
||
TEMPLATE:
|
||
|
||
{* accFs a notre objet enregistrT *}
|
||
{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 prT-compilation</title>
|
||
<para>
|
||
Les filtres de prT-compilation sont des fonctions PHP que vos templates
|
||
exTcutent avant qu'ils ne soient compilTs. Cela peut Otre utile
|
||
pour prT-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 prT-compilations peuvent Otre soit
|
||
<link linkend="api.register.prefilter">dTclarTs</link> soit chargTs
|
||
a partir des rTpertoires de plugins en utilisant la fonction
|
||
<link linkend="api.load.filter">load_filter()</link> ou en rTglant
|
||
la variable
|
||
<link linkend="variable.autoload.filters">$autoload_filters</link>.
|
||
Smarty passera a la fonction le code source en tant que premier argument,
|
||
et attendra en retour le code modifiT.
|
||
</para>
|
||
<example>
|
||
<title>Utilisation un filtre de prT-compilation de template</title>
|
||
<programlisting>
|
||
<?php
|
||
// mettre ceci dans votre application
|
||
function remove_dw_comments($tpl_source, &$smarty)
|
||
{
|
||
return preg_replace("/<!--#.*-->/U","",$tpl_source);
|
||
}
|
||
|
||
// enregistrer le filtre de prT-compilation
|
||
$smarty->register_prefilter("remove_dw_comments");
|
||
$smarty->display("index.tpl");
|
||
?>
|
||
|
||
{* template Smarty index.tpl *}
|
||
<!--# cette ligne va Otre supprimTe par le filtre de prT-compilation --></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
|
||
exTcutent aprFs avoir TtT compilTs. Les filtres de post-compilation peuvent
|
||
Otre soit <link linkend="api.register.postfilter">dTclarTs</link> soit chargTs
|
||
depuis les rTpertoires des plugins en utilisant la fonction
|
||
<link linkend="api.load.filter">load_filter()</link> ou en rTglant
|
||
la variable <link linkend="variable.autoload.filters">$autoload_filters</link>.
|
||
Smarty passera le template compilT en tant que premier paramFtre et attendra
|
||
de la fonction qu'elle retourne le rTsultat de l'exTcution.
|
||
</para>
|
||
<example>
|
||
<title>utilisation d'un filtre de post-compilation de templates</title>
|
||
<programlisting>
|
||
<?php
|
||
// mettez cela dans votre application
|
||
function add_header_comment($tpl_source, &$smarty)
|
||
{
|
||
return "<?php echo \"<!-- Created by Smarty! -->\n\" ?>\n".$tpl_source;
|
||
}
|
||
|
||
// enregistre le filtre de post-compilation
|
||
$smarty->register_postfilter("add_header_comment");
|
||
$smarty->display("index.tpl");
|
||
?>
|
||
|
||
{* template Smarty compilT index.tpl *}
|
||
<!-- Created by Smarty! -->
|
||
{* reste du contenu du template... *}</programlisting>
|
||
</example>
|
||
</sect1>
|
||
|
||
<sect1 id="advanced.features.outputfilters">
|
||
<title>Filtres de sortie</title>
|
||
<para>
|
||
Quand le template est appelT via les fonctions display() ou fetch(),
|
||
sa sortie est envoyTe a travers un ou plusieurs filtres de sorties.
|
||
Ils diffFrent des filtres de post-compilation dans le sens ou ils agissent
|
||
sur la sortie des templates, une fois exTcutTs, et non sur les sources
|
||
des templates.
|
||
</para>
|
||
<para>
|
||
Les filtres de sortie peuvent Otre soit
|
||
<link linkend="api.register.outputfilter">dTclarTs</link> soit
|
||
chargTs depuis les rTpertoires des plugins en utilisant la fonction
|
||
<link linkend="api.load.filter">load_filter()</link>
|
||
ou en rTglant 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 rTsultat de l'exTcution.
|
||
</para>
|
||
<example>
|
||
<title>utilisation d'un filtre de sortie</title>
|
||
<programlisting>
|
||
<?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");
|
||
|
||
// dorTnavant toute occurence d'un adresse email dans le rTsultat du template
|
||
// aura un protection simple contre les robots spammers
|
||
?></programlisting>
|
||
</example>
|
||
</sect1>
|
||
|
||
<sect1 id="section.template.cache.handler.func">
|
||
<title>Fonction de gestion du cache</title>
|
||
<para>
|
||
Une alternative au mTcanisme de cache par dTfaut (basT sur des fichiers
|
||
de cache) consiste a spTcifier une fonction de gestion de cache utilisateur
|
||
qui sera utilisTe pour lire, Tcrire et effacer les fichiers de cache.
|
||
</para>
|
||
<para>
|
||
Il suffit de crTer dans votre application une fonction que Smarty
|
||
utilisera pour la gestion du cache et d'assigner le nom de cette
|
||
fonction a la variable de classe
|
||
<link linkend="variable.cache.handler.func">$cache_handler_func</link>.
|
||
Smarty utilisera alors cette fonction pour gTrer les donnTes du cache.
|
||
Le premier argument est l'action, qui sera 'read', 'write' ou 'clear'.
|
||
Le second paramFtre est l'objet Smarty. Le troisiFme est le contenu
|
||
du cache. Pour Tcrire, Smarty passe le contenu du cache dans ces paramFtres.
|
||
Pour lire, Smarty s'attend a ce que votre fonction accepte ce paramFtre
|
||
par rTfTrence et que vous le remplissiez avec les donnTes du cache. Pour effacer,
|
||
il suffit de passer une variable fictive car cette derniFre n'est pas utilisTe.
|
||
Le quatriFme paramFtre est le nom du fichier de template (utile pour
|
||
lire/Tcrire), le cinquiFme paramFtre est l'identifiant de cache (optionnel)
|
||
et le sixiFme est l'identifiant de compilation.
|
||
</para>
|
||
<example>
|
||
<title>exemple d'utilisation de MySQL pour la source du cache</title>
|
||
<programlisting>
|
||
<?php
|
||
/*
|
||
|
||
exemple d'usage :
|
||
|
||
include('Smarty.class.php');
|
||
include('mysql_cache_handler.php');
|
||
|
||
$smarty = new Smarty;
|
||
$smarty->cache_handler_func = 'mysql_cache_handler';
|
||
|
||
$smarty->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;
|
||
|
||
// crTe 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->_trigger_error_msg("cache_handler: could not connect to database");
|
||
return false;
|
||
}
|
||
mysql_select_db($db_name);
|
||
|
||
switch ($action) {
|
||
case 'read':
|
||
// rTcupFre le cache dans la base de donnTes
|
||
$results = mysql_query("select CacheContents from CACHE_PAGES where CacheID='$CacheID'");
|
||
if(!$results) {
|
||
$smarty_obj->_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 donnTes
|
||
|
||
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->_trigger_error_msg("cache_handler: query failed.");
|
||
}
|
||
$return = $results;
|
||
break;
|
||
case 'clear':
|
||
// efface les donnTes 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->_trigger_error_msg("cache_handler: query failed.");
|
||
}
|
||
$return = $results;
|
||
break;
|
||
default:
|
||
// erreur, action inconnue
|
||
$smarty_obj->_trigger_error_msg("cache_handler: unknown action \"$action\"");
|
||
$return = false;
|
||
break;
|
||
}
|
||
mysql_close($link);
|
||
return $return;
|
||
|
||
}
|
||
|
||
?></programlisting>
|
||
</example>
|
||
</sect1>
|
||
|
||
<sect1 id="template.resources">
|
||
<title>Ressources</title>
|
||
<para>
|
||
Les templates peuvent provenir d'une grande variTtT de ressources. Quand vous
|
||
affichez ou rTcupTrez un template, ou quand vous incluez un template
|
||
dans un autre template, vous fournissez un type de ressource, suivi
|
||
par le chemin appropriT et le nom du template.
|
||
</para>
|
||
<sect2 id="templates.from.template.dir">
|
||
<title>Templates depuis $template_dir</title>
|
||
<para>
|
||
Les templates du rTpertoire $template_dir n'ont pas
|
||
besoin d'une ressource template, bien que vous puissiez utiliser
|
||
la ressource "file" pour Otre cohTrent. Vous n'avez qu'a fournir
|
||
le chemin vers le template que vous voulez utiliser, relatif
|
||
au rTpertoire 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 mOme que celui ci-dessus
|
||
|
||
{* le template Smarty *}
|
||
{include file="index.tpl"}
|
||
{include file="file:index.tpl"} {* le mOme que celui ci-dessus *}</programlisting>
|
||
</example>
|
||
</sect2>
|
||
<sect2 id="templates.from.any.dir">
|
||
<title>Templates a partir de n'importe quel rTpertoire</title>
|
||
<para>
|
||
Les templates en-dehors du rTpertoire $template_dir nTcessitent
|
||
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 rTpertoire</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 identifiT par une lettre (c:) au dTbut du chemin.
|
||
Assurez-vous de bien mettre "file:" dans le chemin pour Tviter des
|
||
conflits d'espace de nommage et obtenir les rTsultats escomptTs.
|
||
</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 rTcupTrer les templates a partir n'importe quelle
|
||
source a laquelle vous avez accFs avec PHP : base de donnTes,
|
||
sockets, LDAP et ainsi de suite. Il suffit d'Tcrire les fonctions
|
||
de ressource plugins et de les enregistrer auprFs de Smarty.
|
||
</para>
|
||
<para>
|
||
Reportez-vous a la section <link linkend="plugins.resources">ressource plugins</link>
|
||
pour plus d'informations sur les fonctions que vous Otes censT fournir.
|
||
</para>
|
||
<note>
|
||
<para>
|
||
Notez que vous ne pouvez pas Tcraser la ressource <literal>file</literal> native,
|
||
toutefois, vous pouvez fournir une ressource qui rTcupFre un template depuis
|
||
le systFme 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, &$tpl_source, &$smarty_obj)
|
||
{
|
||
// requOte BD pour rTcupTrer 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, &$tpl_timestamp, &$smarty_obj)
|
||
{
|
||
// requOte 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 svrs
|
||
return true;
|
||
}
|
||
|
||
function db_get_trusted($tpl_name, &$smarty_obj)
|
||
{
|
||
// pas utilisTe 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 dTfaut</title>
|
||
<para>
|
||
Vous pouvez spTcifier une fonction qui sera utilisTe pour
|
||
rTcupTrer le contenu d'un template dans le cas o<> le template
|
||
ne peut pas Otre rTcupTrT depuis sa ressource. Une utilisation possible est
|
||
la crTation de templates a la volTe.
|
||
</para>
|
||
<example>
|
||
<title>utilisation de la fonction de gestion de template par dTfaut</title>
|
||
<programlisting>
|
||
<?php
|
||
// mettez cette fonction quelque part dans votre application
|
||
|
||
function make_template ($resource_type, $resource_name, &$template_source, &$template_timestamp, &$smarty_obj)
|
||
{
|
||
if( $resource_type == 'file' ) {
|
||
if ( ! is_readable ( $resource_name )) {
|
||
// crTe 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;
|
||
}
|
||
}
|
||
|
||
// rTgle la fonction par dTfaut
|
||
$smarty->default_template_handler_func = 'make_template';
|
||
?></programlisting>
|
||
</example>
|
||
</sect2>
|
||
</sect1>
|
||
</chapter>
|
||
<!-- Keep this comment at the end of the file
|
||
Local variables:
|
||
mode: sgml
|
||
sgml-omittag:t
|
||
sgml-shorttag:t
|
||
sgml-minimize-attributes:nil
|
||
sgml-always-quote-attributes:t
|
||
sgml-indent-step:1
|
||
sgml-indent-data:t
|
||
indent-tabs-mode:nil
|
||
sgml-parent-document:nil
|
||
sgml-default-dtd-file:"../../../../manual.ced"
|
||
sgml-exposed-tags:nil
|
||
sgml-local-catalogs:nil
|
||
sgml-local-ecat-files:nil
|
||
End:
|
||
vim600: syn=xml fen fdm=syntax fdl=2 si
|
||
vim: et tw=78 syn=sgml
|
||
vi: ts=1 sw=1
|
||
--> |