mirror of
https://github.com/smarty-php/smarty.git
synced 2025-10-08 02:01:00 +02:00
528 lines
18 KiB
XML
528 lines
18 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- $Revision$ -->
|
|
<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 a travers les templates. Il y
|
|
a 2 moyens d'y avoir accès. Le premier consiste a allouer les objets
|
|
au template puis de les utiliser avec une syntaxe similaire a celles
|
|
des fonctions personnalisées. Le deuxième moyen consiste a 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'a 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 a vos
|
|
besoins, mais tGchez 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 (commentant 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 faton que les fonctions utilisateurs les récupèrent.
|
|
Le premier paramètre correspond a un tableau associatif, le second a l'objet
|
|
Smarty. Si vous souhaitez que les paramètres soient passées un a un, comme
|
|
dans un appel traditionnel, définissez registration, quatrième paramètre optionnel,
|
|
a false.
|
|
</para>
|
|
<example>
|
|
<title>utilisation d'un objet alloué ou assigné</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'accès a 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");
|
|
?>
|
|
|
|
TEMPLATE:
|
|
|
|
{* accès a 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
|
|
a 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 a 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>
|
|
<?php
|
|
// mettre ceci dans votre application
|
|
function remove_dw_comments($tpl_source, &$smarty)
|
|
{
|
|
return preg_replace("/<!--#.*-->/U","",$tpl_source);
|
|
}
|
|
|
|
// enregistrer le filtre de pré-compilation
|
|
$smarty->register_prefilter("remove_dw_comments");
|
|
$smarty->display("index.tpl");
|
|
?>
|
|
|
|
{* template Smarty index.tpl *}
|
|
<!--# cette ligne va être supprimée par le filtre de pré-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
|
|
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>
|
|
<?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 compilé 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 appelé via les fonctions display() ou fetch(),
|
|
sa sortie est envoyée a 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>
|
|
<?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
|
|
?></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 a 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 a 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 a 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>
|
|
<?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;
|
|
|
|
// 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->_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->_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->_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->_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 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'a 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 a 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 id="templates.windows.filepath">
|
|
<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 a partir n'importe quelle
|
|
source a 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 a la section <link linkend="plugins.resources">ressource plugins</link>
|
|
pour plus d'informations sur les fonctions que vous Otes 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, &$tpl_source, &$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, &$tpl_timestamp, &$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 svrs
|
|
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 a la volée.
|
|
</para>
|
|
<example>
|
|
<title>utilisation de la fonction de gestion de template par défaut</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 )) {
|
|
// 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';
|
|
?></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
|
|
-->
|