smarty/docs/fr/programmers/plugins.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
 <chapter id="plugins">
  <title>Etendre Smarty avec des plugins</title>
  <para>
  La version 2.0 a introduit l'architecture de plugin qui est
  utilis<69>e pour pratiquement toute les fonctionnalit<69>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<70>-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<69> avec les anciennes
  fatons d'enregistrer les fonctions de gestion avec l'API register_
  est conserv<72>e. Si vous n'avez pas utilis<69> cette API et que vous avez
  a la place directement modifi<66> 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<69>s personnalis<69>es en plugins.
  </para>
     
  <sect1>
   <title>Comment fonctionnent les plugins</title>
   <para>
   Les plugins sont toujours charg<72>s a la demande. Seuls les modificateurs
   de variables, les ressources, etc invoqu<71>s dans les scripts de templates
   seront charg<72>s. De plus, chaque plugin n'est charg<72> qu'une fois, et ce
   m<>me si vous avez plusieurs instances de Smarty qui tournent dans
   la m<>me requ<71>te.
   </para>
   <para>
   Les filtres de post/pr<70>-compilation et les filtres de sortie sont des cas
   un peu sp<73>ciaux.
   Comme ils ne sont pas mentionn<6E>s dans les templates, ils doivent <20>tre d<>clar<61>s
   ou charg<72>s explicitement via les fonctions de l'API avant que le template
   ne soit ex<65>cut<75>. L'ordre dans lequel les filtres multiples d'un m<>me type
   sont ex<65>cut<75>s d<>pend de l'ordre dans lequel ils sont enregistr<74>s ou charg<72>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<74>s sp<73>cifique pour <20>tre localis<69>s par Smarty.
    </para>
    <para>
    Les fichiers de plugins doivent <20>tre nomm<6D>s de la faton 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 <20>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 <20>tre
    nomm<6D>es de la faton 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<70>c<EFBFBD>demment.
    </para>
    <para>
    Smarty donnera des messages d'erreur appropri<72> si le fichier de plugin
    n'est pas trouv<75>, ou si le fichier ou la fonction de plugin ne sont
    pas nomm<6D>s correctement.
    </para>
    </sect1>

   <sect1 id="plugins.writing">
    <title>Ecrire des plugins</title>
    <para>
    Les plugins peuvent <20>tre soit charg<72>s automatiquement par Smarty
    depuis le syst<73>me de fichier, soit <20>tre d<>clar<61>s
    pendant l'ex<65>cution via une fonction register_* de l'API. Ils peuvent
    aussi <20>tre d<>sallou<6F>s en utilisant une fonction unregister_* de
    l'API.
    </para>
    <para>
    Pour les plugins qui ne sont pas enregistr<74>s pendant l'ex<65>cution, le nom
    des fonctions n'ont pas a suivre la convention de nommage.
    </para>
    <para>
    Si certaines fonctionnalit<69>s d'un plugin d<>pendent d'un autre plugin
    (comme c'est le cas de certains plugins accompagnant Smarty), alors la mani<6E>re appropri<72>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<EFBFBD>rale est que chaque objet Smarty est toujours pass<73> au plugin
    en tant que dernier param<61>tre (a 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>&amp;$smarty</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
    Tous les attributs pass<73>s aux fonctions de template a partir du template
    sont contenus dans le tableau associatif <parameter>$params</parameter>.
    Vous pouvez acc<63>der a 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<74>e a la balise de fonction
    du template (fonction <function>fetch</function> par exemple). Sinon,
    la fonction peut simplement accomplir une autre tGche 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<69>s fournies par Smarty, elle peut recevoir un
    objet <parameter>$smarty</parameter> pour cela.
    </para>
    <para>
     RTf<54>rez-vous aussi a :
     <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 <20>tre utilis<69>e dans le template de la faton 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 a 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<71>es a une variable
    de template avant qu'elle ne soit affich<63>e ou utilis<69>e dans un autre contexte.
    Les modificateurs peuvent <20>tre chaen<65>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<61>tre pass<73> au modificateur est la valeur
    sur laquelle le modificateur est suppos<6F> op<6F>rer. Les autres param<61>tres
    peuvent <20>tre optionnels, d<>pendant de quel genre d'op<6F>ration doit <20>tre
    effectu<74>.
    </para>
    <para>
    Le modificateur doit retourner le r<>sultat de son ex<65>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<61>tre
     suppl<70>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 chaene a une certaine longueur si
 *            n<>cessaire, 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;
}
?&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>&amp;$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<6F>rent sur les
    contenus de ces blocs. Les fonctions de blocs ont la priorit<69> 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<70>mentation de votre fonction est appel<65>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<73>s par le template aux fonctions de templates sont
    contenues dans le tableau associatif <parameter>$params</parameter>.
    Vous pouvez acc<63>der a 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<63>s aux attributs de la balise
    ouvrante quand c'est la balise fermante qui est ex<65>cut<75>e.     
    </para>
    <para>
    La valeur de la variable <parameter>$content</parameter> est diff<66>rente
    selon si votre fonction est appel<65>e pour la balise ouvrante ou la
    balise fermante. Si c'est pour la balise ouvrante, elle sera a
    <literal>null</literal> et si c'est la balise fermante elle sera
    Tgale au contenu du bloc de template. Notez que le bloc de template
    aura d<>ja Tt<54> ex<65>cut<75> par Smarty, vous recevrez donc la sortie du
    template et non sa source.    
    </para>
    <para>
    Si vous imbriqu<71> des fonctions de bloc, il est possible de connaetre
    la fonction de bloc parente grGce a la variable <varname>$smarty->_tag_stack</varname>.
    Faites un var_dump() dessus et la structure devrait apparaetre.
    </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<65>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<69>e ont le m<>me
    nom, la fonction de compilation a priorit<69>. 
    </para>
    <funcsynopsis>
     <funcprototype>
      <funcdef>mixed <function>smarty_compiler_<replaceable>name</replaceable></function></funcdef>
      <paramdef>string <parameter>$tag_arg</parameter></paramdef>
      <paramdef>object <parameter>&amp;$smarty</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
    Les fonctions de compilation ont deux param<61>tres : une chaene 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<6E>es retourner le code PHP qui doit <20>tre
    inject<63> dans le template compil<69>.
    </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, &amp;$smarty)
{
    return "\necho '" . $smarty-&gt;_current_file . " compiled at " . date('Y-m-d H:M'). "';";
}
?&gt;</programlisting>
     <para>
     Cette fonction peut-<2D>tre appel<65> depuis le template comme suivant :
     </para>     
     <programlisting>
{* cette fonction n'est execut<75>e que lors de la compilation *}
{tplheader}</programlisting>
     <para>
     Le code PHP r<>sultant dans les templates compil<69>s ressemblerait a ta :
     </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<70>-compilation/filtres de post-compilation</title>
    <para>
    Les filtres de pr<70>-compilation et les filtres de post-compilation ont des concepts tr<74>s
    proches. Ils diff<66>rent dans leur ex<65>cution, plus pr<70>cis<69>ment dans le
    moment o<> ils sont ex<65>cut<75>s.
    </para>
    <funcsynopsis>
     <funcprototype>
      <funcdef>string <function>smarty_prefilter_<replaceable>name</replaceable></function></funcdef>
      <paramdef>string <parameter>$source</parameter></paramdef>
      <paramdef>object <parameter>&amp;$smarty</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
    Les filtres de pr<70>-compilation sont utilis<69>s pour transformer la source d'un template
    juste avant la compilation. Le premier param<61>tre pass<73> a la fonction
    de filtre de pr<70>-compilation est la source du template, Tventuellement modifi<66>e par
    d'autres filtre de pr<70>-compilations. Le plugin est suppos<6F> retourner la source modifi<66>e.
    Notez que cette source n'est sauvegard<72>e nulle part, elle est seulement
    utilis<69> 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>&amp;$smarty</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
    Les filtres de post-compilation sont utilis<69>s pour modifier la sortie du template
    (le code PHP) juste apr<70>s que la compilation a Tt<54> faite mais juste
    avant que le template ne soit sauvegard<72> sur le syst<73>me de fichiers.
    Le premier param<61>tre pass<73> a la fonction de filtre de post-compilation est le code
    du template compil<69>, Tventuellement d<>ja modifi<66> par d'autres filtre de post-compilations.
    Le plugin est cens<6E> retourner la version modifi<66> 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<70>-compilation
 * Nom :      pre01
 * R(le :     Passe les balises HTML en minuscules.
 * -------------------------------------------------------------
 */
 function smarty_prefilter_pre01($source, &amp;$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, &amp;$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<6F>rent sur la sortie du template,
    apr<70>s que le template a Tt<54> charg<72> et ex<65>cut<75>, mais avant que
    la sortie ne soit affich<63>e.
    </para>    
    <funcsynopsis>
     <funcprototype>
      <funcdef>string <function>smarty_outputfilter_<replaceable>name</replaceable></function></funcdef>
      <paramdef>string <parameter>$template_output</parameter></paramdef>
      <paramdef>object <parameter>&amp;$smarty</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
    Le premier param<61>tre pass<73> a la fonction du filtre de sortie est la
    sortie du template qui doit <20>tre modifi<66>e et le second param<61>tre
    est l'instance de Smarty appelant le plugin. Le plugin est suppos<6F>
    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<6F>ger des 
 *           robots spammers.
 * -------------------------------------------------------------
 */
 function smarty_outputfilter_protect_email($output, &amp;$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<EFBFBD>rique de fournir des sources
    de templates ou des composants de scripts PHP a Smarty. Quelques exemples
    de ressources : bases de donn<6E>es, LDAP, m<>moire partag<61>e, sockets, et ainsi
    de suite.
    </para>
    <para>
    Il y au total 4 fonctions qui ont besoin d'<27>tre enregistr<74>es pour
    chaque type de ressource. Chaque fonction retoit le nom de la ressource demand<6E>e
    comme premier param<61>tre et l'objet Smarty comme dernier param<61>tre.
    Les autres param<61>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>&amp;$source</parameter></paramdef>
      <paramdef>object <parameter>&amp;$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>&amp;$timestamp</parameter></paramdef>
      <paramdef>object <parameter>&amp;$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>&amp;$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>&amp;$smarty</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>

    <para>
    La premi<6D>re fonction est suppos<6F>e r<>cup<75>rer la ressource. Son second
    param<61>tre est une variable pass<73>e par r<>f<EFBFBD>rence o<> le r<>sultat doit <20>tre
    stock<63>. La fonction est suppos<6F>e retourner <literal>true</literal> si
    elle r<>ussi a r<>cup<75>rer la ressource et <literal>false</literal> sinon.
    </para>

    <para>
    La seconde fonction est suppos<6F>e r<>cup<75>rer la date de derni<6E>re modification 
    de la ressource demand<6E>e (comme un timestamp UNIX). Le second param<61>tre
    est une variable pass<73>e par r<>f<EFBFBD>rence dans laquelle la date doit
    <20>tre stock<63>e. La fonction est suppos<6F>e renvoyer <literal>true</literal> si elle
    a r<>ussi a r<>cup<75>rer la date et <literal>false</literal> sinon.
    </para>

    <para>
    La troisi<73>me fonction est suppos<6F>e retourner <literal>true</literal>
    ou <literal>false</literal> selon si la ressource demand<6E>e est svre
    ou non. La fonction est utilis<69>e seulement pour les ressources templates
    mais doit tout de m<>me <20>tre d<>finie.
    </para>

    <para>
    La quatri<72>me fonction est suppos<6F>e retourner <literal>true</literal>
    ou <literal>false</literal> selon si on peut faire confiance ou
    non a la ressource demand<6E>e. Cette fonction est utilis<69>e seulement
    pour les composants de scripts PHP demand<6E>s par les balises
    <command>include_php</command> ou <command>insert</command>
    ayant un attribut <structfield>src</structfield>. Quoiqu'il en soit,
    elle doit <20>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 :     RTcup<75>re des templates depuis une base de donn<6E>es
 * -------------------------------------------------------------
 */
function smarty_resource_db_source($tpl_name, &amp;$tpl_source, &amp;$smarty)
{
    // fait des requ<71>tes BD pour r<>cup<75>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<71>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 svrs
    return true;
}

function smarty_resource_db_trusted($tpl_name, &amp;$smarty)
{
    // inutilis<69>e pour les templates
}
?&gt;</programlisting>
    </example>
   </sect1>

   <sect1 id="plugins.inserts"><title>Insertions</title>
    <para>
    Les plugins d'insertion sont utilis<69>s pour impl<70>menter les fonctions
    qui sont appel<65>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>&amp;$smarty</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
    Le premier param<61>tre pass<73> a la fonction est une tableau associatif
    d'attributs. Vous pouvez acc<63>der a 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<6F>e retourner le r<>sultat qui sera
    substitu<74> a 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<72>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>
<!-- 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
-->