smarty/docs/de/programmers/plugins.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
 <chapter id="plugins">
  <title>Smarty durch Plugins erweitern</title>
  <para>
   In Version 2.0 wurde die Plugin-Architektur eingef&uuml;hrt, welche f&uuml;r fast alle anpassbaren Funktionalit&auml;ten
   verwendet wird. Unter anderem:
   <itemizedlist spacing="compact">
    <listitem><simpara>Funktionen</simpara></listitem>
    <listitem><simpara>Modifikatoren</simpara></listitem>
    <listitem><simpara>Block-Funktionen</simpara></listitem>
    <listitem><simpara>Compiler-Funktionen</simpara></listitem>
    <listitem><simpara>'pre'-Filter</simpara></listitem>
    <listitem><simpara>'post'-Filter</simpara></listitem>
    <listitem><simpara>Ausgabefilter</simpara></listitem>
    <listitem><simpara>Ressourcen</simpara></listitem>
    <listitem><simpara>Inserts</simpara></listitem>
   </itemizedlist>
   F&uuml;r die Abw&auml;rtskompatibilit&auml;t wurden das register_* API zur Funktions-Registrierung
   beibehalten. Haben Sie fr&uuml;her nicht die API-Funktionen benutzt, sondern die Klassen-Variablen
   <literal>$custom_funcs</literal>, <literal>$custom_mods</literal> und andere direkt 
    ge&auml;ndert, m&uuml;ssen Sie Ihre Skripte so anpassen, dass diese das API verwenden.
    Oder sie implementieren die Funktionalit&auml;ten alternativ mit Plugins.
    
  </para>
  
  <sect1 id="plugins.howto">
   <title>Wie Plugins funktionieren</title>
   <para>
    Plugins werden immer erst bei Bedarf geladen. Nur die im Template
    verwendeten Funktionen, Ressourcen, Variablen-Modifikatoren, etc. werden geladen.
    Des weiteren wird jedes Plugin nur einmal geladen, selbst wenn mehrere Smarty-Instanzen
    im selben Request erzeugt werden.
   </para>
   <para>
    'pre'/'post'-Filter machen die Ausnahme. Da sie in den Templates nicht direkt
    erw&auml;hnt werden, m&uuml;ssen sie zu Beginn der Ausf&uuml;hrung explizit via API geladen oder
    registriert werden. Die Reihenfolge der Anwendung mehrerer Filter desselben Typs
    entspricht der Reihenfolge in der sie geladen/registriert wurden.
   </para>
   <para>
    Die <link linkend="variable.plugins.dir">plugins directory</link> Variable kann eine Zeichenkette,
    oder ein Array mit Verzeichnisnamen sein. Um einen Plugin zu installieren k&ouml;nnen Sie ihn einfach
    in einem der Verzeichnisse ablegen.
   </para>
  </sect1>
  
  <sect1 id="plugins.naming.conventions">
   <title>Namenskonvention</title>
   <para>
    Plugin-Dateien m&uuml;ssen einer klaren Namenskonvention gehorchen,
    um von Smarty erkannt zu werden.
   </para>
   <para>
    
    Die Plugin-Dateien m&uuml;ssen wie folgt benannt werden:
    <blockquote>
     <para>
      <filename>
       <replaceable>type</replaceable>.<replaceable>name</replaceable>.php
      </filename>
     </para>
    </blockquote>
   </para>
   <para>
    
    Wobei <literal>Typ</literal> einen der folgenden Werte haben kann:
    <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>
    und <literal>Name</literal> ein erlaubter Identifikator (bestehend
    aus Buchstaben, Zahlen und Unterstrichen) ist.
   </para>
   <para>
     Ein paar Beispiele: <literal>function.html_select_date.php</literal>,
     <literal>resource.db.php</literal>,
      <literal>modifier.spacify.php</literal>.
   </para>
   <para>
    
    Die Plugin-Funktion innerhalb das Plugin-Datei muss wie folgt benannt werden:
    <blockquote>
     <para>
      <function>smarty_<replaceable>type</replaceable>_<replaceable>name</replaceable></function>
     </para>
    </blockquote>
   </para>
   <para>
    <literal>type</literal> und <literal>name</literal> haben die selbe Bedeutung wie bei den Plugin-Dateien.
   </para>
   <para>
    Smarty gibt Fehlermeldungen aus, falls ein aufgerufenes Plugin nicht existiert,
    oder eine Datei mit falscher Namensgebung im Verzeichnis gefunden wurde.
   </para>
  </sect1>
  <sect1 id="plugins.writing">
   <title>Plugins schreiben</title>
   <para>
    Plugins k&ouml;nnen von Smarty automatisch geladen oder 
    zur Laufzeit dynamisch mit den register_* API-Funktionen
    registriert werden. Um registrierte Plugins wieder zu entfernen,
    k&ouml;nnen die unregister_* API-Funktionen verwendet werden.
   </para>
   <para>
    Bei Plugins, die zur Laufzeit geladen werden, m&uuml;ssen keine Namenskonventionen
    beachtet werden.
   </para>
   <para>
    Wenn ein Plugin auf die Funktionalit&auml;t eines anderen Plugins angewiesen
    ist (wie dies bei manchen Smarty Standard-Plugins der Fall ist), sollte
    folgender Weg gew&auml;hlt werden, um das ben&ouml;tigte Plugin zu laden:
   </para>
   <programlisting>
    require_once $smarty->_get_plugin_filepath('function', 'html_options');</programlisting>
    <para>
     Das Smarty Objekt wird jedem Plugin immer als letzter Parameter
     &uuml;bergeben (ausser bei Variablen-Modifikatoren und bei Bl&uuml;cken wird
     <parameter>&amp;$repeat</parameter> nach dem Smarty Objekt &uuml;bergeben um R&uuml;ckw&auml;rtskompatibel zu bleiben).
    </para>
  </sect1>
  
  <sect1 id="plugins.functions"><title>Template-Funktionen</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>
    Alle einer Funktion &uuml;bergebenen Parameter werden in der Variable
    <parameter>$params</parameter> als assoziatives Array abgelegt. Sie k&ouml;nnen
     auf diese Werte entweder direkt mit <varname>$params['start']</varname> zugreifen
     oder sie mit <varname>extract($params)</varname> in die Symbol-Tabelle importieren.
</para>
<para>
 Die Ausgabe der Funktion wird verwendet, um das Funktions-Tag im Template
 (<function>fetch</function> Funktion, zum Beispiel) zu ersetzen.
 Alternativ kann sie auch etwas tun, ohne eine Ausgabe zur&uuml;ckzuliefern
 (<function>assign</function> Funktion, zum Beispiel).
</para>
<para>
 Falls die Funktion dem Template Variablen zuweisen oder
 auf eine andere Smarty-Funktionalit&auml;t zugreifen m&ouml;chte, kann dazu das
 &uuml;bergebene <parameter>$smarty</parameter> Objekt verwendet werden.
</para>
<para>
 
 Sehen Sie dazu:
 <link linkend="api.register.function">register_function()</link>,
  <link linkend="api.unregister.function">unregister_function()</link>.
</para>
<para>
 <example>
  <title>Funktionsplugin mit Ausgabe</title>
  <programlisting>
   &lt;?php
   /*
   * Smarty plugin
   * -------------------------------------------------------------
   * File:     function.eightball.php
   * Type:     function
   * Name:     eightball
   * Purpose:  outputs a random magic answer
   * -------------------------------------------------------------
   */
   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);
   echo $answers[$result];
   }
   ?&gt;</programlisting>
 </example>
</para>
<para>
 
 Es kann im Template wie folgt angewendet werden:
</para>
<programlisting>
 Question: Will we ever have time travel?
 Answer: {eightball}.</programlisting>
 <para>
  <example>
   <title>Funktionsplugin ohne Ausgabe</title>
   <programlisting>
    &lt;?php
    /*
    * Smarty plugin
    * -------------------------------------------------------------
    * File:     function.assign.php
    * Type:     function
    * Name:     assign
    * Purpose:  assign a value to a template variable
    * -------------------------------------------------------------
    */
    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>Variablen-Modifikatoren</title>
   <para>
    Variablen-Modifikatoren sind kleine Funktionen, die auf eine Variable angewendet
    werden, bevor sie ausgegeben oder weiterverwendet wird. Variablen-Modifikatoren k&ouml;nnen
    aneinadergereiht werden.
   </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>
    Der erste an das Modifikator-Plugin &uuml;bergebene Parameter ist der
    Wert mit welchem er arbeiten soll. Die restlichen Parameter sind optional
    und h&auml;ngen von den durchzuf&uuml;hrenden Operationen ab.
   </para>
   <para>
    
    Der Modifikator muss das Resultat seiner Verarbeitung zur&uuml;ckgeben.
   </para>
   <para>
    Sehen Sie dazu:
    <link linkend="api.register.modifier">register_modifier()</link>,
     <link linkend="api.unregister.modifier">unregister_modifier()</link>.
   </para>
   <example>
    <title>Einfaches Modifikator-Plugin</title>
    <para>
     Dieses Plugin dient als Alias einer PHP-Funktion und erwartet keine
     zus&auml;tzlichen Parameter.
    </para>
    <programlisting>
     &lt;?php
     /*
     * Smarty plugin
     * -------------------------------------------------------------
     * File:     modifier.capitalize.php
     * Type:     modifier
     * Name:     capitalize
     * Purpose:  capitalize words in the string
     * -------------------------------------------------------------
     */
     function smarty_modifier_capitalize($string)
     {
     return ucwords($string);
     }
     ?&gt;</programlisting>
   </example>
   <para></para>
   <example>
    <title>Komplexes Modifikator-Plugin</title>
    <programlisting>
     &lt;?php
     /*
     * Smarty plugin
     * -------------------------------------------------------------
     * File:     modifier.truncate.php
     * Type:     modifier
     * Name:     truncate
     * Purpose:  Truncate a string to a certain length if necessary,
     *           optionally splitting in the middle of a word, and 
     *           appending the $etc string.
     * -------------------------------------------------------------
     */
     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>Block-Funktionen</title>
   <funcsynopsis>
    <funcprototype>
     <funcdef>void <function>smarty_function_<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>
    Block-Funktionen sind Funktionen, die in der Form {func} .. {/func} notiert
    werden. Mit anderen Worten umschliessen sie einen Template-Abschnitt und
    arbeiten danach auf dessen Inhalt. Eine Block-Funktion {func} .. {/func} 
    kann nicht mir einer gleichnamigen Template-Funktion {func}
    &uuml;berschrieben werden.
   </para>
   <para>
    Ihre Funktions-Implementation wird von Smarty zweimal
    aufgerufen: einmal f&uuml;r das &ouml;ffnende und einmal
    f&uuml;r das schliessende Tag. (konsultieren Sie den Abschnitt zu <literal>&amp;$repeat</literal>
    um zu erfahren wie Sie dies &auml;ndern k&ouml;nnen.)
   </para>
   <para>
    Nur das &Ouml;ffnungs-Tag kann Attribute enthalten. Alle so &uuml;bergebenen Attribute
    werden als assoziatives Array <parameter>$params</parameter> der Template-Funktion
    &uuml;bergeben. Sie k&ouml;nnen auf die Werte entweder direkt mit <varname>$params['start']</varname>
    zugreifen oder sie mit <varname>extract($params)</varname> in die Symbol-Tabelle
    importieren. Die Attribute aus dem &Ouml;ffnungs-Tag stehen auch beim Aufruf f&uuml;r das
    schliessende Tag zur Verf&uuml;gung.
   </para>
   <para>
    Der Inhalt der <parameter>$content</parameter> Variable h&auml;ngt davon
    ab, ob die Funktion f&uuml;r das &ouml;ffnende Tag oder f&uuml;r das schliessende
    Tag aufgerufen wird. F&uuml;r das &ouml;ffnende Tag ist der Wert <literal>null</literal>,
    f&uuml;r das schliessende Tag ist es der Inhalt des Template-Abschnitts.
    Achtung: Der Template-Abschnitt den Sie erhalten, wurde bereits von
    Smarty bearbeitet. Sie erhalten also die Template-Ausgabe, nicht den Template-Quelltext.
   </para>
   <para>
    Der Parameter <parameter>&amp;$repeat</parameter> wird als Referenz &uuml;bergeben und
    kontrolliert wie oft ein Block dargestellt werden soll. Standardwert von <parameter>$repeat</parameter>
    ist beim ersten Aufruf (f&uuml;r das &ouml;ffnende Tag) <literal>true</literal>, danach immer
    <literal>false</literal>.
    Jedes Mal wenn eine Funktion f&uuml;r <parameter>&amp;$repeat</parameter> TRUE zur&uuml;ck gibt,
    wird der Inhalt zwischen {func} .. {/func} erneut mit dem ver&auml;nderten
    Inhalt als <parameter>$content</parameter> Parameter aufgerufen.
   </para>
   <para>
    Wenn Sie verschachtelte Block-Funktionen haben, k&ouml;nnen Sie 
    die Eltern-Block-Funktion mit der <varname>$smarty->_tag_stack</varname> Variable 
    herausfinden. Lassen Sie sich ihren Inhalt mit 'var_dump()' ausgeben.
    Die Struktur sollte selbsterkl&auml;rend sein.
   </para>
   <para>
    
    Sehen Sie dazu:
    <link linkend="api.register.block">register_block()</link>,
    <link linkend="api.unregister.block">unregister_block()</link>.
   </para>
   <example>
    <title>Block-Funktionen</title>
    <programlisting>
     &lt;?php
     /*
     * Smarty plugin
     * -------------------------------------------------------------
     * File:     block.translate.php
     * Type:     block
     * Name:     translate
     * Purpose:  translate a block of text
     * -------------------------------------------------------------
     */
     function smarty_block_translate($params, $content, &amp;$smarty)
     {
     if (isset($content)) {
     $lang = $params['lang'];
     
     // den $content irgendwie intelligent &uuml;bersetzuen
     return $translation;
     }
     }</programlisting>
   </example>
  </sect1>
  
  <sect1 id="plugins.compiler.functions"><title>Compiler-Funktionen</title>
   <para>
    Compiler-Funktionen werden w&auml;hrend der Kompilierung des Template
    aufgerufen. Das ist n&uuml;tzlich, um PHP-Code oder zeitkritische statische
    Inhalte in ein Template einzuf&uuml;gen. Sind eine Compiler-Funktion und
    eine eigene Funktion unter dem selben Namen registriert, wird die
    Compiler-Funktion ausgef&uuml;hrt.
   </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>
    Die Compiler-Funktion erh&auml;lt zwei Parameter: die Tag-Argument Zeichenkette
    - also alles ab dem Funktionsnamen bis zum schliessenden Trennzeichen - und
    das Smarty Objekt. Gibt den PHP-Code zur&uuml;ck, der in das Template eingef&uuml;gt werden
    soll.
   </para>
   <para>
    
    Sehen Sie dazu:
    <link linkend="api.register.compiler.function">register_compiler_function()</link>,
     <link linkend="api.unregister.compiler.function">unregister_compiler_function()</link>.
   </para>
   <example>
    <title>Einfache Compiler-Funktionen</title>
    <programlisting>
     &lt;?php
     /*
     * Smarty plugin
     * -------------------------------------------------------------
     * File:     compiler.tplheader.php
     * Type:     compiler
     * Name:     tplheader
     * Purpose:  Output header containing the source file name and
     *           the time it was compiled.
     * -------------------------------------------------------------
     */
     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>
      
      Diese Funktion kann aus dem Template wie folgt aufgerufen werden:
     </para>
     <programlisting>
      
      {* diese Funktion wird nur zum Kompilier-Zeitpunkt ausgef&uuml;hrt *}
      {tplheader}</programlisting>
      <para>
       
       Der resultierende PHP-Code w&uuml;rde ungef&auml;hr so aussehen:
      </para>
      <programlisting>
       &lt;php
       echo 'index.tpl compiled at 2002-02-20 20:02';
       ?&gt;</programlisting>
   </example>
  </sect1>
  
  <sect1 id="plugins.prefilters.postfilters">
   <title>'pre'/'post'-Filter</title>
   <para>
    'pre'-Filter und 'post'-Filter folgen demselben Konzept. Der
    einzige Unterschied ist der Zeitpunkt der Ausf&uuml;hrung.
   </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>
    'pre'-Filter werden verwendet, um die Quellen eines Templates direkt
    vor der Kompilierung zu verarbeiten. Als erster Parameter wird die
    Template-Quelle, die m&ouml;glicherweise bereits durch eine weiteren 'pre'-Filter
    bearbeitet wurden, &uuml;bergeben. Das Plugin muss den resultierenden Wert
    zur&uuml;ckgeben. Achtung: Diese Werte werden nicht gespeichert und nur
    zum Kompilier-Zeitpunkt verwendet.
   </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>
    'post'-Filter werden auf die kompilierte Ausgabe direkt vor dem Speichern
    angewendet. Als erster Parameter wird der kompilierte Template-Code
    &uuml;bergeben, der m&ouml;glicherweise zuvor von anderen 'post'-Filtern
    bearbeitet wurde. Das Plugin muss den ver&auml;nderten Template-Code zur&uuml;ckgeben.
   </para>
   <example>
    <title>'pre'-Filter Plugin</title>
    <programlisting>
     &lt;?php
     /*
     * Smarty plugin
     * -------------------------------------------------------------
     * File:     prefilter.pre01.php
     * Type:     prefilter
     * Name:     pre01
     * Purpose:  Convert html tags to be lowercase.
     * -------------------------------------------------------------
     */
     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>'post'-Filter Plugin</title>
    <programlisting>
     &lt;?php
     /*
     * Smarty plugin
     * -------------------------------------------------------------
     * File:     postfilter.post01.php
     * Type:     postfilter
     * Name:     post01
     * Purpose:  Output code that lists all current template vars.
     * -------------------------------------------------------------
     */
     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>Ausgabefilter</title>
   <para>
    Ausgabefilter werden auf das Template direkt vor der Ausgabe angewendet,
    nachdem es geladen und ausgef&uuml;hrt wurde.
   </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>
    Als erster Parameter wird die Template-Ausgabe &uuml;bergeben, welche
    verarbeitet werden soll und als zweiter Parameter das Smarty-Objekt.
    Das Plugin muss danach die verarbeitete Template-Ausgabe zur&uuml;ckgeben.
   </para>
   <example>
    <title>Ausgabefilter Plugin</title>
    <programlisting>
     /*
     * Smarty plugin
     * -------------------------------------------------------------
     * File:     outputfilter.protect_email.php
     * Type:     outputfilter
     * Name:     protect_email
     * Purpose:  Converts @ sign in email addresses to %40 as 
     *           a simple protection against spambots
     * -------------------------------------------------------------
     */
     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>Ressourcen</title>
   <para>
    Ressourcen-Plugins stellen einen generischen Weg dar, um Smarty mit
    Template-Quellen oder PHP-Skripten zu versorgen. Einige Beispiele von Ressourcen:
    Datenbanken, LDAP, shared Memory, Sockets, usw.
   </para>
   
   <para>
    F&uuml;r jeden Ressource-Typ m&uuml;ssen 4 Funktionen registriert werden. Jede dieser
    Funktionen erh&auml;lt die verlangte Ressource als ersten Parameter und das Smarty Objekt
    als letzten. Die restlichen Parameter h&auml;ngen von der Funktion ab.
   </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>
    Die erste Funktion wird verwendet, um die Ressource zu laden. Der
    zweite Parameter ist eine Variable, die via Referenz &uuml;bergeben
    wird und in der das Resultat gespeichert werden soll. Die Funktion
    gibt <literal>true</literal> zur&uuml;ck, wenn der Ladevorgang erfolgreich war - 
    andernfalls <literal>false</literal>.
   </para>
   
   <para>
    Die zweite Funktion fragt das letzte &Auml;nderungsdatum der angeforderten
    Ressource (als Unix-Timestamp) ab. Der zweite Parameter ist die Variable,
    welche via Referenz &uuml;bergeben wird und in der das Resultat gespeichert werden soll.
    Gibt <literal>true</literal> zur&uuml;ck, wenn das &Auml;nderungsdatum ermittelt
    werden konnte und <literal>false</literal> wenn nicht.
   </para>
   
   <para>
    Die dritte Funktion gibt <literal>true</literal> oder <literal>false</literal>
    zur&uuml;ck, je nachdem ob die angeforderte Ressource als sicher bezeichnet wird
    oder nicht. Diese Funktion wird nur f&uuml;r Template-Ressourcen verwendet,
    sollte aber in jedem Fall definiert werden.
   </para>
   
   <para>
    Die vierte Funktion gibt <literal>true</literal> oder <literal>false</literal>
    zur&uuml;ck, je nachdem ob die angeforderte Ressource als vertrauensw&uuml;rdig angesehen wird
    oder nicht. Diese Funktion wird nur verwendet, wenn PHP-Skripte via <command>include_php</command>
    oder <command>insert</command> eingebunden werden sollen und ein 'src' Attribut &uuml;bergeben wurde.
    Die Funktion sollte aber in jedem Fall definiert werden.
   </para>
   <para>
    Sehen Sie dazu:
    <link linkend="api.register.resource">register_resource()</link>,
     <link linkend="api.unregister.resource">unregister_resource()</link>.
   </para>
   <example>
    <title>Ressourcen Plugin</title>
    <programlisting>
     &lt;?php
     /*
     * Smarty plugin
     * ------------------------------------------------------------- 
     * File:     resource.db.php
     * Type:     resource
     * Name:     db
     * Purpose:  Fetches templates from a database
     * -------------------------------------------------------------
     */
     function smarty_resource_db_source($tpl_name, &amp;$tpl_source, &amp;$smarty)
     {
     // Datenbankabfragen machen, um '$tpl_source' das template zuzuweisen
     $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)
     {
     
     // Datenbankabfragen durchf&uuml;hren um '$tpl_timestamp' zuzuweisen
     $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)
     {
     
     // angenommen alle Templates seien sicher...
     return true;
     }
     
     function smarty_resource_db_trusted($tpl_name, &amp;$smarty)
     {
     
     // wird f&uuml;r Templates nicht verwendet
     }
     ?&gt;</programlisting>
   </example>
  </sect1>
  
  <sect1 id="plugins.inserts"><title>Inserts</title>
   <para>
    Insert-Plugins werden verwendet, um Funktionen zu implementieren, die
    via <link linkend="language.function.insert"><command>insert</command></link> aufgerufen werden.
   </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>
    Als erster Parameter wird der Funktion ein assoziatives Array aller Attribute
    &uuml;bergeben, die im Insert-Tag notiert wurden. Sie k&ouml;nnen
    auf diese Werte entweder direkt mit <varname>$params['start']</varname> zugreifen
    oder sie mit <varname>extract($params)</varname> importieren.
   </para>
   <para>
    Als R&uuml;ckgabewert muss das Resultat der Ausf&uuml;hrung geliefert werden,
    das danach den Platz des <command>insert</command>-Tags im Template einnimmt.
   </para>
   <example>
    <title>Insert-Plugin</title>
    <programlisting>
     &lt;?php
     /*
     * Smarty plugin
     * ------------------------------------------------------------- 
     * File:     insert.time.php
     * Type:     time
     * Name:     time
     * Purpose:  Inserts current date/time according to 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
-->