smarty-php/smarty
1
0
Fork 0
mirror of https://github.com/smarty-php/smarty.git synced 2025-11-04 06:11:37 +01:00
Code Issues Packages Projects Releases Wiki Activity
Files
688530acea979818bff66afc0e54bbbe743f4827
smarty/docs/de/programmers.sgml
mohrt 5eff9c73e5 commit german 2.5.0 docs
2003-04-17 14:50:49 +00:00

2834 lines
106 KiB
Plaintext
Raw Blame History

<!-- Smarty German Documentation Port -->
<!-- $Id$ -->
<!-- $Author$ -->
<!-- $Revision$ -->
<part id="smarty.for.programmers">
<title>Smarty f&uuml;r Programmierer</title>
<chapter id="smarty.constants">
<title>Konstanten</title>
<para></para>
<sect1 id="constant.smarty.dir">
<title>SMARTY_DIR</title>
<para>
Definiert den absoluten Systempfad zu den Smarty Klassendateien. Falls
der Wert nicht definiert ist, versucht Smarty ihn automatisch zu ermitteln.
Der Pfad muss mit einem '/'-Zeichen enden.
</para>
<example>
<title>SMARTY_DIR</title>
<programlisting>
// Pfad zum Smarty Verzeichnis setzen
define("SMARTY_DIR","/usr/local/lib/php/Smarty/");
require_once(SMARTY_DIR."Smarty.class.php");</programlisting>
</example>
</sect1>
</chapter>
<chapter id="api.variables">
<title>Variablen</title>
<sect1 id="variable.template.dir">
<title>$template_dir</title>
<para>
Definiert das Standard-Template Verzeichnis. Wenn
sie beim Einbinden von Templates keinen Ressourcen-Typ &uuml;bergeben,
werden sie in diesem Pfad gesucht. Normalerweise lautet er './templates'.
Das heisst, Smarty erwartet das Template-Verzeichnis im selben Verzeichnis
wie das ausgef&uuml;hrte PHP-Skript.
</para>
<note>
<title>Technische Bemerkung</title>
<para>
Dieses Verzeichnis sollte ausserhalb der DocumentRoot
des Webservers liegen.
</para>
</note>
</sect1>
<sect1 id="variable.compile.dir">
<title>$compile_dir</title>
<para>
Definiert das Verzeichnis, in das die kompilierten Templates geschrieben
werden. Normalerweise lautet es './templates_c'.
Das heisst, Smarty erwartet das Kompilier-Verzeichnis im selben Verzeichnis
wie das ausgef&uuml;hrte PHP-Skript.
</para>
<note>
<title>Technische Bemerkung</title>
<para>
Diese Einstellung kann als relativer oder als absoluter Pfad
angegeben werden. 'include_path' wird nicht verwendet.
</para>
</note>
<note>
<title>Technische Bemerkung</title>
<para>
Dieses Verzeichnis sollte ausserhalb der DocumentRoot
des Webservers liegen.
</para>
</note>
</sect1>
<sect1 id="variable.config.dir">
<title>$config_dir</title>
<para>
Dieses Verzeichnis definiert den Ort, an dem die von den
Templates verwendeten Konfigurationsdateien abgelegt sind. Normalerweise
ist dies './configs'. Das bedeutet, Smarty erwartet das
Konfigurations-Verzeichnis im selben Verzeichnis wie das ausgef&uuml;hrte
PHP-Skript.
</para>
<note>
<title>Technische Bemerkung</title>
<para>
Dieses Verzeichnis sollte ausserhalb der DocumentRoot
des Webservers liegen.
</para>
</note>
</sect1>
<sect1 id="variable.plugins.dir">
<title>$plugins_dir</title>
<para>
Definiert das Verzeichnis in welchem Smarty die zu ladenden Plugins sucht.
Normalerweise ist dies 'plugins' im SMARTY_DIR Pfad. Wenn Sie einen relativen
Pfad angeben, wird Smarty zuerst versuchen das Plugin von SMARTY_DIR aus zu erreichen,
danach relativ zum aktuellen Verzeichnis (mit 'cwd' - current working directory)
und zum Schluss in jedem Eintrag des PHP-'include_path'.
</para>
<note>
<title>Technische Bemerkung</title>
<para>
F&uuml;r optimale Performance ist es sinnvoll, 'plugins_dir'
absolut oder relativ zu SMARTY_DIR bzw. dem aktuellen Verzeichnis zu definieren.
Von der Definition des Verzeichnisses im PHP-'include_path' wird abgeraten.
</para>
</note>
</sect1>
<sect1 id="variable.debugging">
<title>$debugging</title>
<para>
Aktiviert die <link linkend="chapter.debugging.console">Debugging Konsole</link>.
Die Konsole besteht aus einem Javascript-Fenster, welches Informationen zum
momentan geladenen Template und den zugewiesenen Variablen enth&auml;lt.
</para>
</sect1>
<sect1 id="variable.debug.tpl">
<title>$debug_tpl</title>
<para>
Definiert den Namen des f&uuml;r die Debugging Konsole verwendeten Template. Normalerweise
lautet er 'debug.tpl' und befindet sich im <link linkend="constant.smarty.dir">SMARTY_DIR</link> Verzeichnis.
</para>
</sect1>
<sect1 id="variable.debugging.ctrl">
<title>$debugging_ctrl</title>
<para>
Definiert Alternativen zur Aktivierung der Debugging Konsole.
NONE verbietet alternative Methoden. URL aktiviert ds Debugging,
wenn das Schl&uuml;sselwort 'SMARTY_DEBUG' im QUERY_STRING gefunden wird.
Wenn '$debugging' auf 'true' gesetzt ist, wird dieser Wert ignoriert.
</para>
</sect1>
<sect1 id="variable.global.assign">
<title>$global_assign</title>
<para>
Definiert eine Liste von Variablen die jedem Template automatisch
zugewiesen werden. Dies ist n&uuml;tzlich falls man globale beziehungsweise Server-Variablen,
zuweisen will, ohne dies von Hand zu tun. Jedes Element in '$global_assign' sollte
entweder den Namen der zuzuweisenden Variablen enthalten, oder Schl&uuml;ssel/Wert-Paare,
bei welchen der Schl&uuml;ssel den Namen des globalen Arrays definiert und der
Wert den Array mit den zuzuweisenden Werten. '$SCRIPT_NAME' wird immer zugewiesen und
aus '$HTTP_SERVER_VARS' bezogen.
</para>
<note>
<title>Technische Bemerkung</title>
<para>
Server-Variablen k&ouml;nnen &uuml;ber die '$smarty'-Variable
erreicht werden, zum Beispiel: {$smarty.server.SCRIPT_NAME}.
Konsultieren sie den Abschnitt zu <link linkend="language.variables.smarty">$smarty</link>
f&uuml;r weiterf&uuml;hrende Informationen.
</para>
</note>
</sect1>
<sect1 id="variable.undefined">
<title>$undefined</title>
<para>
Definiert den Wert von '$undefined' f&uuml;r Smarty. Normalerweise ist
dieser Wert 'null'. Momentan wird er nur verwendet, um nicht definierten
Elementen aus '$global_assign' einen Standardwert zuzuweisen.
</para>
</sect1>
<sect1 id="variable.autoload.filters">
<title>$autoload_filters</title>
<para>
Filter die Sie zu jedem Template laden m&ouml;chten, k&ouml;nnen Sie mit Hilfe
dieser Variable festlegen. Smarty wird sie danach automatisch laden. Die Variable
enth&auml;lt ein assoziatives Array, in dem der Schl&uuml;ssel den Filter-Typ
und der Wert den Filter-Namen definiert. Zum Beispiel:
<informalexample>
<programlisting>
$smarty-&gt;autoload_filters = array('pre' =&gt; array('trim', 'stamp'),
'output' => array('convert'));
</programlisting>
</informalexample>
</para>
</sect1>
<sect1 id="variable.compile.check">
<title>$compile_check</title>
<para>
Bei jedem Aufruf der PHP-Applikation &uuml;berpr&uuml;ft Smarty,
ob sich das zugrundeliegende Template seit dem letzten Aufruf
ge&auml;ndert hat. Falls es eine &Auml;nderung feststellt,
wird das Template neu kompiliert. Seit Smarty 1.4.0 wird
das Template - falls es nicht existiert - kompiliert, unabh&auml;ngig
davon welcher Wert '$compile_check' hat. Normalerweise ist der
Wert dieser Variable 'true'. Wenn eine Applikation produktiv
eingesetzt wird (die Templates &auml;ndern sich nicht mehr), kann
der 'compile_check'-Schritt entfallen. Setzen Sie dann
'$compile_check' auf 'false', um die Performance zu steigern.
Achtung: Wenn Sie '$compile_check' auf 'false' setzen und anschliessend
ein Template &auml;ndern, wird diese &Auml;nderung *nicht* angezeigt.
Wenn caching und 'compile_check' eingeschaltet sind, werden die
gecachten Skripts neu kompiliert, sobald eine &Auml;nderung an
einem der eingebundenen Templates festgestellt wird.
Siehe auch <link linkend="variable.force.compile">$force_compile</link>
und <link linkend="api.clear.compiled.tpl">clear_compiled_tpl</link>.
</para>
</sect1>
<sect1 id="variable.force.compile">
<title>$force_compile</title>
<para>
Veranlasst Smarty dazu die Templates bei jedem Aufruf neu
zu kompilieren. Diese Einstellung &uuml;berschreibt '$compile_check'.
Normalerweise ist dies ausgeschaltet, kann jedoch f&uuml;r die Fehlersuche
n&uuml;tzlich sein. In einem Produktiven-Umfeld sollte auf
die Verwendung verzichtet werden. Wenn caching eingeschaltet ist,
werden die gecachten Dateien bei jedem Aufruf neu kompiliert.
</para>
</sect1>
<sect1 id="variable.caching">
<title>$caching</title>
<para>
Definiert ob Smarty die Template-Ausgabe cachen soll. Normalerweise ist dies
ausgeschaltet (disabled, Wert: 0). Falls Ihre Templates redundante Inhalte erzeugen,
ist es empfehlenswert caching einzuschalten. Die Performance wird signifikant verbessert.
Sie k&ouml;nnen auch mehrere Caches f&uuml;r ein Template haben. Die Werte 1 und 2 aktivieren
caching. Bei 1 verwendet Smarty die Variable '$cache_lifetime', um zu berechnen
ob ein Template neu kompiliert werden soll. Der Wert 2 weist Smarty an, den Wert von
'cache_lifetime' zur Zeit der Erzeugung des Cache zu verwenden. Damit k&ouml;nnen Sie 'cache_lifetime'
setzen, bevor Sie das Template einbinden und haben so eine feine Kontrolle dar&uuml;ber,
wann ein bestimmter Cache abl&auml;uft. Konsultieren Sie dazu auch: <link linkend="api.is.cached">is_cached</link>.
</para>
<para>
Wenn '$compile_check' aktiviert ist, wird der Cache regeneriert sobald ein Template
oder eine Konfigurations-Variable ge&auml;ndert wurde. Wenn '$force_compile' aktiviert ist,
werden die gecachten Inhalte bei jedem Aufruf neu generiert.
</para>
</sect1>
<sect1 id="variable.cache.dir">
<title>$cache_dir</title>
<para>
Definiert den Namen des Verzeichnisses in dem die Template-Caches
angelegt werden. Normalerweise ist dies './cache', was Smarty veranlasst
das Cache-Verzeichnis im aktuellen Verzeichnis zu suchen. Sie k&ouml;nnen
auch einen eigenen Cache-Handler zur Kontrolle der Cache-Dateien
definieren, der diese Einstellung ignoriert.
</para>
<note>
<title>Technische Bemerkung</title>
<para>
Die Angabe muss entweder relativ oder absolut angegeben werden. 'include_path'
wird nicht verwendet.
</para>
</note>
<note>
<title>Technische Bemerkung</title>
<para>
Es wird empfohlen ein Verzeichnis ausserhalb der DocumentRoot zu verwenden.
</para>
</note>
</sect1>
<sect1 id="variable.cache.lifetime">
<title>$cache_lifetime</title>
<para>
Definiert die Zeitspanne (in Sekunden) die ein Cache g&uuml;ltig
bleibt. Ist die Zeit abgelaufen, wird der Cache neu generiert. '$caching'
muss eingeschaltet (true) sein, damit '$cache_lifetime' Sinn macht. Der
Wert -1 bewirkt, dass der Cache nie abl&auml;uft. Der Wert 0 bewirkt, dass
der Inhalt immer neu generiert wird (nur sinnvoll f&uuml;r Tests, eine
effizientere Methode w&auml;re <link linkend="variable.caching">$caching</link>
auf 'false' zu setzen).
</para>
<para>
Wenn <link linkend="variable.force.compile">$force_compile</link>
gesetzt ist, wird der Cache immer neu generiert (was einem Ausschalten
von caching gleichkommt). Mit der <link linkend="api.clear.all.cache">clear_all_cache()</link>
Funktion k&ouml;nnen Sie alle Cache-Dateien auf einmal entfernen. Mit der
<link linkend="api.clear.cache">clear_cache()</link> Funktion k&ouml;nnen Sie
einzelne Cache-Dateien (oder Gruppen) entfernen.
</para>
<note>
<title>Technische Bemerkung</title>
<para>
Falls Sie bestimmten Templates eine eigene Cache-Lifetime geben wollen,
k&ouml;nnen Sie dies tun indem Sie <link linkend="variable.caching">$caching</link>
auf 2 stellen und '$cache_lifetime' einen einmaligen Wert zuweisen, bevor Sie
'display()' oder 'fetch()' aufrufen.
</para>
</note>
</sect1>
<sect1 id="variable.cache.handler.func">
<title>$cache_handler_func</title>
<para>
Sie k&ouml;nnen auch eine eigene Cache-Handler Funktion definieren.
Siehe Abschnitt zur <link linkend="section.template.cache.handler.func">custom cache handler</link> Funktion.
</para>
</sect1>
<sect1 id="variable.cache.modified.check">
<title>$cache_modified_check</title>
<para>
Wenn auf 1 gesetzt, verwendet Smarty den If-Modified-Since
Header des Clients. Falls sich der Timestamp der Cache-Datei
seit dem letzten Besuch nicht ge&auml;ndert hat, wird der
Header '304 Not Modified' anstatt des Inhalts ausgegeben. Dies
funktioniert nur mit gecachten Inhalten die keine <command>insert</command>
Tags enthalten.
</para>
</sect1>
<sect1 id="variable.default.template.handler.func">
<title>$default_template_handler_func</title>
<para>
Diese Funktion wird aufgerufen, wenn ein Template nicht aus der
vorgegebenen Quelle geladen werden kann.
</para>
</sect1>
<sect1 id="variable.php.handling">
<title>$php_handling</title>
<para>
Definiert wie Smarty mit PHP-Code innerhalb von Templates umgehen soll.
Es gibt 4 verschiedene Einstellungen. Normalerweise wird
SMARTY_PHP_PASSTHRU verwendet. Achtung: '$php_handling' wirkt sich NICHT
auf PHP-Code aus, der zwischen <link linkend="language.function.php">{php}{/php}</link>
Tags steht.
</para>
<itemizedlist>
<listitem><para>SMARTY_PHP_PASSTHRU - Smarty gibt die Tags aus.</para></listitem>
<listitem><para>SMARTY_PHP_QUOTE - Smarty maskiert die Tags als HTML-Entities.</para></listitem>
<listitem><para>SMARTY_PHP_REMOVE - Smarty entfernt die Tags.</para></listitem>
<listitem><para>SMARTY_PHP_ALLOW - Smarty f&uuml;hrt den Code als PHP-Code aus.</para></listitem>
</itemizedlist>
<para>
ACHTUNG: Es wird davon abgeraten, PHP-Code in Templates einzubetten.
Bitte verwenden Sie stattdessen <link linkend="language.custom.functions">custom functions</link>
oder <link linkend="language.modifiers">Variablen-Modifikatoren</link>.
</para>
</sect1>
<sect1 id="variable.security">
<title>$security</title>
<para>
'$security' ein-/ausschalten. Normalerweise 'false' (ausgeschaltet).
Die Sicherheitseinstellung ist wertvoll, wenn nicht vertrauensw&uuml;rdigen
Parteien Zugriff auf die Templates gegeben wird (zum Beispiel via FTP).
Mit aktivierter '$security' kann verhindert werden, dass diese das System
via Template-Engine kompromittieren. Die '$security' einzuschalten halt folgende
Auswirkungen auf die Template-Language (ausser sie werden mit '$security_settings'
&uuml;berschrieben):
</para>
<itemizedlist>
<listitem><para>Wenn '$php_handling' auf SMARTY_PHP_ALLOW geschaltet ist, wird der Wert auf SMARTY_PHP_PASSTHRU ge&auml;ndert.</para></listitem>
<listitem><para>Ausser den in '$security_settings' definierten, sind keine Funktionen in IF-Statements aufrufbar.</para></listitem>
<listitem><para>Templates k&ouml;nnen nur aus den im '$secure_dir'-Array definierten Verzeichnissen geladen werden.</para></listitem>
<listitem><para>'fetch()' kann nur verwendet werden um Dateien aus '$secure_dir' zu laden.</para></listitem>
<listitem><para>{php}{/php}-Tags sind nicht erlaubt.</para></listitem>
<listitem><para>Ausser den in '$security_settings' definierten, sind keine PHP-Funktionen direkt als Variablen-Modifikatoren aufrufbar.</para></listitem>
</itemizedlist>
</sect1>
<sect1 id="variable.secure.dir">
<title>$secure_dir</title>
<para>
Definiert die als 'sicher' geltenden Verzeichnisse als Array.
{include} und {fetch} verwenden diese Verzeichnisse, wenn '$security'
eingeschaltet ist.
</para>
</sect1>
<sect1 id="variable.security.settings">
<title>$security_settings</title>
<para>
Wird verwendet um spezifische Sicherheits-Einstellungen zu
&auml;ndern, wenn '$security' eingeschaltet ist.
</para>
<itemizedlist>
<listitem><para>PHP_HANDLING - true/false. Wenn auf 'true' gesetzt wird '$php_handling' ignoriert.</para></listitem>
<listitem><para>IF_FUNCS - Ist ein Array aller erlaubter Funktionen in IF-Statements.</para></listitem>
<listitem><para>INCLUDE_ANY - true/false. Wenn 'true', kann jedes Template geladen werden, auch ausserhalb der '$secure_dir'-Liste.</para></listitem>
<listitem><para>PHP_TAGS - true/false. Wenn 'true', sind keine {php}{/php}-Tags erlaubt.</para></listitem>
<listitem><para>MODIFIER_FUNCS - Ist ein Array aller Funktionen die als Variablen-Modifikatoren verwendet werden d&uuml;rfen.</para></listitem>
</itemizedlist>
</sect1>
<sect1 id="variable.trusted.dir">
<title>$trusted_dir</title>
<para>
'$trusted_dir' wird nur verwendet wenn die Sicherheit eingeschaltet ist. Der Wert
ist ein Array aller Verzeichnisse, die als vertrauensw&uuml;rdig gelten.
In diesen Verzeichnissen k&ouml;nnen PHP-Skripte, die man direkt aus einem Template
mit <link linkend="language.function.include.php">{include_php}</link> aufruft,
abgelegt werden.
</para>
</sect1>
<sect1 id="variable.left.delimiter">
<title>$left_delimiter</title>
<para>
Das zu verwendende linke Trennzeichen der Template-Sprache.
Normalerweise '{'.
</para>
</sect1>
<sect1 id="variable.right.delimiter">
<title>$right_delimiter</title>
<para>
Das zu verwendende rechte Trennzeichen der Template-Sprache.
Normalerweise '}'.
</para>
</sect1>
<sect1 id="variable.compiler.class">
<title>$compiler_class</title>
<para>
Definiert den Namen der Compiler-Klasse, die Smarty zum kompilieren
der Templates verwenden soll. Normalerweise 'Smarty_Compiler'. Nur
f&uuml;r fortgeschrittene Anwender.
</para>
</sect1>
<sect1 id="variable.request.vars.order">
<title>$request_vars_order</title>
<para>
Die Reihenfolge in welcher die Request-Variblen zugewiesen werden.
Verh&auml;lt sich wie 'variables_order' in der php.ini.
</para>
</sect1>
<sect1 id="variable.compile.id">
<title>$compile_id</title>
<para>
Persistenter 'compile-identifier'. Anstatt jedem Funktionsaufruf die selbe 'compile_id'
zu &uuml;bergeben, kann eine individuelle 'compile_id' gesetzt werden. Das ist z. B.
sinnvoll, um in Kombination mit einem 'prefilter' verschiedene Sprach-Versionen eines Template
kompilieren.
</para>
</sect1>
<sect1 id="variable.use.sub.dirs">
<title>$use_sub_dirs</title>
<para>
Wenn Sie Smarty in einer Umgebung einsetzen, die das Erstellen von Unterverzeichnissen
nicht erlaubt, k&ouml;nnen Sie diesen Wert auf 'false' setzen. Unterverzeichnisse
sind jedoch effizienter und sollten deshalb m&ouml;glichst verwendet werden.
</para>
</sect1>
<sect1 id="variable.default.modifiers">
<title>$default_modifiers</title>
<para>
Definiert ein Array von Variablen-Modifikatoren, die auf jeder Variable anzuwenden sind.
Wenn Sie zum Beispiel alle Variablen standardm&auml;ssig HTML-Maskieren wollen,
k&ouml;nnen Sie array('escape:"htmlall"'); verwenden. Um eine Variable von dieser
Behandlung auszuschliessen, k&ouml;nnen Sie ihr den Modifikator 'nodefaults' &uuml;bergeben.
Zum Beispiel: {$var|nodefaults}.
</para>
</sect1>
</chapter>
<chapter id="api.functions">
<title>Methoden</title>
<sect1 id="api.append">
<title>append (anh&auml;ngen)</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>append</function></funcdef>
<paramdef>mixed <parameter>var</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>void <function>append</function></funcdef>
<paramdef>string <parameter>varname</parameter></paramdef>
<paramdef>mixed <parameter>var</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>void <function>append</function></funcdef>
<paramdef>string <parameter>varname</parameter></paramdef>
<paramdef>mixed <parameter>var</parameter></paramdef>
<paramdef>boolean <parameter>merge</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Wird verwendet, um an Template-Variablen weitere Daten anzuh&auml;ngen. Sie
k&ouml;nnen entweder ein Namen/Wert-Paar oder assoziative Arrays,
die mehrere Namen/Wert-Paare enthalten, &uuml;bergeben. Wenn Sie als dritten Parameter
'true' &uuml;bergeben werden die beiden Arrays zusammengef&uuml;gt.
</para>
<note>
<title>Technical Note</title>
<para>
Der Parameter 'merge' &uuml;berschreibt bestehende Schl&uuml;ssel, falls
im zweiten Array die selben Schl&uuml;ssel wie im ersten vorkommen.
Diese Funktion ist ungelich 'array_merge()' aus PHP.
</para>
</note>
<example>
<title>append (anh&auml;ngen)</title>
<programlisting>
// Namen/Wert-Paare &uuml;bergeben
$smarty->append("Name","Fred");
$smarty->append("Address",$address);
// assoziatives Array &uuml;bergeben
$smarty->append(array("city" => "Lincoln","state" => "Nebraska"));</programlisting>
</example>
</sect1>
<sect1 id="api.append.by.ref">
<title>append_by_ref (via Referenz anh&auml;ngen)</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>append_by_ref</function></funcdef>
<paramdef>string <parameter>varname</parameter></paramdef>
<paramdef>mixed <parameter>var</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>void <function>append_by_ref</function></funcdef>
<paramdef>string <parameter>varname</parameter></paramdef>
<paramdef>mixed <parameter>var</parameter></paramdef>
<paramdef>boolean <parameter>merge</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Wird verwendet, um an Template-Variablen Werte via Referenz (pass by reference) anstatt via Kopie
anzuh&auml;ngen. Wenn Sie eine Variable via Referenz anh&auml;ngen und sie nachtr&auml;glich
ge&auml;ndert wird, wird auch der angeh&auml;ngte Wert ge&auml;ndert. Bei Objekten kann so
das kopieren derselben vermieden werden. Konsultieren Sie das PHP-Manual betreffend Variablenreferenzierung
f&uuml;r weitere Erkl&auml;rungen. Wenn Sie als dritten Parameter 'true' &uuml;bergeben wird das anzuh&auml;ngende Array
mit dem bestehenden zusammengef&uml;gt.
</para>
<note>
<title>Technische Bemerkung</title>
<para>
Der Parameter 'merge' &uuml;berschreibt bestehende Schl&uuml;ssel, falls
im zweiten Array die selben Schl&uuml;ssel wie im ersten vorkommen.
Diese Funktion ist ungelich 'array_merge()' aus PHP.
</para>
</note>
<example>
<title>append_by_ref (via Referenz anh&auml;ngen)</title>
<programlisting>
// Namen/Wert-Paare &uuml;bergeben
$smarty->append_by_ref("Name",$myname);
$smarty->append_by_ref("Address",$address);</programlisting>
</example>
</sect1>
<sect1 id="api.assign">
<title>assign (zuweisen)</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>assign</function></funcdef>
<paramdef>mixed <parameter>var</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>void <function>assign</function></funcdef>
<paramdef>string <parameter>varname</parameter></paramdef>
<paramdef>mixed <parameter>var</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Wird verwendet, um einem Template Werte zuzuweisen. Sie k&ouml;nnen
entweder Namen/Wert-Paare oder ein assoziatives Array
mit Namen/Wert-Paaren &uuml;bergeben.
</para>
<example>
<title>assign</title>
<programlisting>
// Namen/Wert-Paare &uuml;bergeben
$smarty->assign("Name","Fred");
$smarty->assign("Address",$address);
// assoziatives Array mit Namen/Wert-Paaren &uuml;bergeben
$smarty->assign(array("city" => "Lincoln","state" => "Nebraska"));</programlisting>
</example>
</sect1>
<sect1 id="api.assign.by.ref">
<title>assign_by_ref (via Referenz zuweisen)</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>assign_by_ref</function></funcdef>
<paramdef>string <parameter>varname</parameter></paramdef>
<paramdef>mixed <parameter>var</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Weist einen Wert via Referenz zu, anstatt eine Kopie zu machen.
Konsultieren Sie das PHP-Manual zum Thema 'variable referencing' f&uuml;r weitere Erkl&auml;rungen.
</para>
<note>
<title>Technical Note</title>
<para>
Wird verwendet, um an Template-Variablen Werte via Referenz (pass by reference) anstatt via Kopie
anzuh&auml;ngen. Wenn Sie eine Variable via Referenz anh&auml;ngen und sie nachtr&auml;glich
ge&auml;ndert wird, wird auch der angeh&auml;ngte Wert ge&auml;ndert. Bei Objekten kann so
das kopieren derselben vermieden werden. Konsultieren Sie das PHP-Manual betreffend Variablenreferenzierung
f&uuml;r weitere Erkl&auml;rungen.
</para>
</note>
<example>
<title>assign_by_ref (via Referenz zuweisen)</title>
<programlisting>
// Namen/Wert-Paare &uuml;bergeben
$smarty->assign_by_ref("Name",$myname);
$smarty->assign_by_ref("Address",$address);</programlisting>
</example>
</sect1>
<sect1 id="api.clear.all.assign">
<title>clear_all_assign (alle Zuweisungen l&ouml;schen)</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>clear_all_assign</function></funcdef>
<paramdef><parameter></parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
L&ouml;scht die Werte aller zugewiesenen Variablen.
</para>
<example>
<title>clear_all_assign (alle Zuweisungen l&ouml;schen)</title>
<programlisting>
// l&ouml;sche alle zugewiesenen Variablen
$smarty->clear_all_assign();</programlisting>
</example>
</sect1>
<sect1 id="api.clear.all.cache">
<title>clear_all_cache (Cache vollst&auml;ndig leeren)</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>clear_all_cache</function></funcdef>
<paramdef>int <parameter>expire time</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Leert den gesamten Template-Cache. Als optionaler Parameter kann ein
Mindestalter in Sekunden angegeben werden, das die einzelne Datei haben
muss, bevor sie gel&ouml;scht wird.
</para>
<example>
<title>clear_all_cache (Cache vollst&auml;ndig leeren)</title>
<programlisting>
// leere den gesamten cache
$smarty->clear_all_cache();</programlisting>
</example>
</sect1>
<sect1 id="api.clear.assign">
<title>clear_assign (l&ouml;sche Zuweisung)</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>clear_assign</function></funcdef>
<paramdef>string <parameter>var</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
L&ouml;scht den Wert einer oder mehrerer (&uuml;bergabe als Array) zugewiesener Variablen.
</para>
<example>
<title>clear_assign (l&ouml;sche Zuweisung)</title>
<programlisting>
// l&ouml;sche eine einzelne Variable
$smarty->clear_assign("Name");
// l&ouml;sche mehrere Variablen
$smarty->clear_assign(array("Name","Address","Zip"));</programlisting>
</example>
</sect1>
<sect1 id="api.clear.cache">
<title>clear_cache (leere Cache)</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>clear_cache</function></funcdef>
<paramdef>string <parameter>template</parameter></paramdef>
<paramdef>string <parameter><optional>cache id</optional></parameter></paramdef>
<paramdef>string <parameter><optional>compile id</optional></parameter></paramdef>
<paramdef>int <parameter><optional>expire time</optional></parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
L&ouml;scht den Cache eines bestimmten Templates. Falls Sie mehrere
Caches f&uuml;r ein Template verwenden, k&ouml;nnen Sie als zweiten Parameter
die 'cache_id' des zu leerenden Caches &uuml;bergeben. Als dritten Parameter
k&ouml;nnen sie die 'compile_id' angeben. Sie k&ouml;nnen Templates auch
gruppieren und dann als Gruppe aus dem Cache l&ouml;schen. Sehen sie dazu den Abschnitt &uuml;ber
<link linkend="caching">caching</link>. Als vierten Parameter k&ouml;nnen Sie
ein Mindestalter in Sekunden angeben, das ein Cache aufweisen muss,
bevor er gel&ouml;scht wird.
</para>
<example>
<title>clear_cache (Cache leeren)</title>
<programlisting>
// Cache eines Templates leeren
$smarty->clear_cache("index.tpl");
// leere den Cache einer bestimmten 'cache-id' eines mehrfach-gecachten Templates
$smarty->clear_cache("index.tpl","CACHEID");</programlisting>
</example>
</sect1>
<sect1 id="api.clear.compiled.tpl">
<title>clear_compiled_tpl (kompiliertes Template l&ouml;schen)</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>clear_compiled_tpl</function></funcdef>
<paramdef>string <parameter>tpl_file</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
L&ouml;scht die kompilierte Version des angegebenen Templates. Falls
kein Template-Name &uuml;bergeben wird, werden alle kompilierten
Templates gel&ouml;scht. Diese Funktion ist f&uuml;r fortgeschrittene Benutzer.
</para>
<example>
<title>clear_compiled_tpl (kompiliertes Template l&ouml;schen)</title>
<programlisting>
// ein bestimmtes kompiliertes Template l&ouml;schen
$smarty->clear_compiled_tpl("index.tpl");
// das gesamte Kompilier-Verzeichnis l&ouml;schen
$smarty->clear_compiled_tpl();</programlisting>
</example>
</sect1>
<sect1 id="api.display">
<title>display (ausgeben)</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>display</function></funcdef>
<paramdef>string <parameter>template</parameter></paramdef>
<paramdef>string <parameter><optional>cache_id</optional></parameter></paramdef>
<paramdef>string <parameter><optional>compile_id</optional></parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Gibt ein Template aus. Sie m&uuml;ssen einen g&uuml;ltigen
<link linkend="template.resources">Template Ressourcen</link>-Typ
inklusive Pfad angeben. Als optionalen zweiten Parameter k&ouml;nnen
Sie eine 'cache_id' &uuml;bergeben. Konsultieren
Sie den Abschnitt &uuml;ber <link linkend="caching">caching</link> f&uuml;r weitere Informationen.
</para>
<para>
Als optionalen dritten Parameter k&ouml;nnen Sie eine 'compile_id' &uuml;bergeben.
Dies ist wertvoll, falls Sie verschiedene Versionen eines Templates
kompilieren wollen - zum Beispiel in verschiedenen Sprachen. 'compile_id'
wird auch verwendet, wenn Sie mehr als ein '$template_dir' aber nur ein
'$compile_dir' haben. Setzen Sie dazu f&uuml;r jedes Verzeichnis eine
eigene 'compile_id', andernfalls werden Templates mit dem gleichen Namen
&uuml;berschrieben. Sie k&ouml;nnen die Variable <link linkend="variable.compile.id">$compile_id</link>
auch einmalig setzen, anstatt sie bei jedem Aufruf von 'display()' zu &uuml;bergeben.
</para>
<example>
<title>display (ausgeben)</title>
<programlisting>
include("Smarty.class.php");
$smarty = new Smarty;
$smarty->caching = true;
// Datenbank-Aufrufe nur durchf&uuml;hren, wenn kein Cache existiert
if(!$smarty->is_cached("index.tpl"))
{
// Beispieldaten
$address = "245 N 50th";
$db_data = array(
"City" => "Lincoln",
"State" => "Nebraska",
"Zip" = > "68502"
);
$smarty->assign("Name","Fred");
$smarty->assign("Address",$address);
$smarty->assign($db_data);
}
// Ausgabe
$smarty->display("index.tpl");</programlisting>
</example>
<para>
Verwenden Sie die Syntax von <link linkend="template.resources">template resources</link>
um Dateien ausserhalb von '$template_dir' zu verwenden.
</para>
<example>
<title>Beispiele von Template-Ressourcen f&uuml;r 'display()'</title>
<programlisting>
// absoluter Dateipfad
$smarty->display("/usr/local/include/templates/header.tpl");
// absoluter Dateipfad (alternativ)
$smarty->display("file:/usr/local/include/templates/header.tpl");
// absoluter Dateipfad unter Windows (MUSS mit 'file:'-Prefix versehen werden)
$smarty->display("file:C:/www/pub/templates/header.tpl");
// aus der Template-Ressource 'db' einbinden
$smarty->display("db:header.tpl");</programlisting>
</example>
</sect1>
<sect1 id="api.fetch">
<title>fetch</title>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>fetch</function></funcdef>
<paramdef>string <parameter>template</parameter></paramdef>
<paramdef>string <parameter><optional>cache_id</optional></parameter></paramdef>
<paramdef>string <parameter><optional>compile_id</optional></parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Gibt die Ausgabe des Template zur&uuml;ck, anstatt es direkt anzuzeigen. &Uuml;bergeben Sie
einen g&uuml;ltigen <link linkend="template.resources">Template Ressource</link>-Typ
und -Pfad. Als optionaler zweiter Parameter kann eine 'cache_id' &uuml;bergeben werden.
Bitte konsultieren Sie den Abschnitt &uuml;ber <link linkend="caching">caching </link>
f&uuml;r weitere Informationen.
</para>
<para>
Als optionalen dritten Parameter k&ouml;nnen Sie eine 'compile_id' &uuml;bergeben.
Dies ist wertvoll, falls Sie verschiedene Versionen eines Templates
kompilieren wollen - zum Beispiel in verschiedenen Sprachen. 'compile_id'
wird auch verwendet, wenn Sie mehr als ein '$template_dir' aber nur ein
'$compile_dir' haben. Setzen Sie dann f&uuml;r jedes Verzeichnis eine
eigene 'compile_id', andernfalls werden Templates mit dem gleichen Namen
&uuml;berschrieben. Sie k&ouml;nnen die Variable <link linkend="variable.compile.id">$compile_id</link>
auch einmalig setzen, anstatt sie bei jedem Aufruf von 'fetch()' zu &uuml;bergeben.
</para>
<example>
<title>fetch</title>
<programlisting>
include("Smarty.class.php");
$smarty = new Smarty;
$smarty->caching = true;
// Datenbank-Aufrufe nur durchf&uuml;hren, wenn kein Cache existiert
if(!$smarty->is_cached("index.tpl"))
{
// Beispieldaten
$address = "245 N 50th";
$db_data = array(
"City" => "Lincoln",
"State" => "Nebraska",
"Zip" = > "68502"
);
$smarty->assign("Name","Fred");
$smarty->assign("Address",$address);
$smarty->assign($db_data);
}
// Ausgabe abfangen
$output = $smarty->fetch("index.tpl");
// Etwas mit $output anstellen
echo $output;</programlisting>
</example>
</sect1>
<sect1 id="api.get.config.vars">
<title>get_config_vars</title>
<funcsynopsis>
<funcprototype>
<funcdef>array <function>get_config_vars</function></funcdef>
<paramdef>string <parameter><optional>varname</optional></parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Gibt die definierte Variable aus einer Konfigurationsdatei zur&uuml;ck,
wenn kein Parameter &uuml;bergeben wird, wird ein Array aller Variablen
zur&uuml;ckgegeben.
</para>
<example>
<title>get_config_vars</title>
<programlisting>
// Vriable 'foo' aus Konfigurationsdatei lesen
$foo = $smarty->get_config_vars('foo');
// alle Variablen aus der Konfigurationsdatei lesen
$config_vars = $smarty->get_config_vars();
// ausgeben
print_r($config_vars);</programlisting>
</example>
</sect1>
<sect1 id="api.get.registered.object">
<title>get_registered_object</title>
<funcsynopsis>
<funcprototype>
<funcdef>array <function>get_registered_object</function></funcdef>
<paramdef>string <parameter>object_name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
This returns a reference to a registered object. This is useful
from within a custom function when you need direct access to a
registered object.
</para>
<example>
<title>get_registered_object</title>
<programlisting>
function smarty_block_foo($params, &amp;$smarty) {
if (isset[$params['object']]) {
// get reference to registered object
$obj_ref =&amp; $smarty->&amp;get_registered_object($params['object']);
// use $obj_ref is now a reference to the object
}
}</programlisting>
</example>
</sect1>
<sect1 id="api.get.template.vars">
<title>get_template_vars (Template-Variablen extrahieren)</title>
<funcsynopsis>
<funcprototype>
<funcdef>array <function>get_template_vars</function></funcdef>
<paramdef>string <parameter><optional>varname</optional></parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Gibt den Wert der &uuml;bergebenen Template-Variable zur&uuml;ck. Wenn kein Parameter
&uuml;bergeben wird, besteht die R&uuml;ckgabe aus einem Array aller zugewiesener Variablen.
</para>
<example>
<title>get_template_vars (Template-Variablen extrahieren)</title>
<programlisting>
// Template-Variable 'foo' extrahieren
$foo = $smarty->get_template_vars('foo');
// alle zugewiesenen Template-Variablen extrahieren
$tpl_vars = $smarty->get_template_vars();
// Anschauen
print_r($tpl_vars);</programlisting>
</example>
</sect1>
<sect1 id="api.is.cached">
<title>is_cached (gecachte Version existiert)</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>is_cached</function></funcdef>
<paramdef>string <parameter>template</parameter></paramdef>
<paramdef>[string <parameter>cache_id</parameter>]</paramdef>
</funcprototype>
</funcsynopsis>
<para>
Gibt 'true' zur&uuml;ck, wenn ein g&uuml;ltiger Cache f&uuml;r das angegebene Template existiert.
Dies funktioniert nur, wenn <link linkend="variable.caching">caching</link> eingeschaltet ist.
</para>
<example>
<title>is_cached</title>
<programlisting>
$smarty->caching = true;
if(!$smarty->is_cached("index.tpl")) {
// Datenbank-Abfragen, Variablen zuweisen...
}
$smarty->display("index.tpl");</programlisting>
</example>
<para>
Als optionalen zweiten Parameter k&ouml;nnen Sie die 'cache_id' &uuml;bergeben,
falls Sie mehrere Caches f&uuml;r ein Template verwenden.
</para>
<example>
<title>'is_cached' bei mehreren Template-Caches</title>
<programlisting>
$smarty->caching = true;
if(!$smarty->is_cached("index.tpl", "FrontPage")) {
// Datenbank Abfragen, Variablen zuweisen...
}
$smarty->display("index.tpl","FrontPage");</programlisting>
</example>
</sect1>
<sect1 id="api.load.filter">
<title>load_filter (Filter laden)</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>load_filter</function></funcdef>
<paramdef>string <parameter>type</parameter></paramdef>
<paramdef>string <parameter>name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Mit dieser Funktion k&ouml;nnen Filter-Plugins geladen werden.
Der erste Parameter definiert den Filter-Typ und kann einen der
folgenden Werte haben: 'pre', 'post', oder 'output'. Als zweiter
Parameter wird der Name des Filter-Plugins angegeben, zum Beispiel 'trim'.
</para>
<example>
<title>Filter-Plugins laden</title>
<programlisting>
$smarty->load_filter('pre', 'trim'); // lade den 'pre'-Filter (Vor-Filter) namens 'trim'
$smarty->load_filter('pre', 'datefooter'); // lade einen zweiten Vor-Filter namens 'datefooter'
$smarty->load_filter('output', 'compress'); // lade den 'output'-Filter (Ausgabe-Filter) namens 'compress'</programlisting>
</example>
</sect1>
<sect1 id="api.register.block">
<title>register_block (Block-Funktion registrieren)</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>register_block</function></funcdef>
<paramdef>string <parameter>name</parameter></paramdef>
<paramdef>string <parameter>impl</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Wird verwendet, um Block-Funktion-Plugins dynamisch zu registrieren.
&Uuml;bergeben Sie dazu den Namen der Block-Funktion und den Namen der
PHP-Funktion, die die entsprechende Funktionalit&auml;t bereitstellt.
</para>
<example>
<title>register_block (Block-Funktion registrieren)</title>
<programlisting>
/* PHP */
$smarty->register_block("translate", "do_translation");
function do_translation ($params, $content, &$smarty) {
if ($content) {
$lang = $params['lang'];
// &uuml;bersetze den Inhalt von '$content'
echo $translation;
}
}
{* template *}
{translate lang="br"}
Hello, world!
{/translate}</programlisting>
</example>
</sect1>
<sect1 id="api.register.compiler.function">
<title>register_compiler_function (Compiler-Funktion registrieren)</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>register_compiler_function</function></funcdef>
<paramdef>string <parameter>name</parameter></paramdef>
<paramdef>string <parameter>impl</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Wird verwendet, um Compiler-Funktion-Plugins dynamisch zu
registrieren. &Uuml;bergeben Sie dazu den Namen der Compiler-Funktion und den Namen der
PHP-Funktion, die die entsprechende Funktionalit&auml;t bereitstellt.
</para>
</sect1>
<sect1 id="api.register.function">
<title>register_function (Funktion registrieren)</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>register_function</function></funcdef>
<paramdef>string <parameter>name</parameter></paramdef>
<paramdef>string <parameter>impl</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Wird verwendet, um Template-Funktion-Plugins dynamisch zu
registrieren. &Uuml;bergeben Sie dazu den Namen der Template-Funktion
und den Namen der PHP-Funktion, die die entsprechende Funktionalit&auml;t bereitstellt.
</para>
<example>
<title>register_function (Funktion registrieren)</title>
<programlisting>
$smarty->register_function("date_now", "print_current_date");
function print_current_date ($params) {
extract($params);
if(empty($format))
$format="%b %e, %Y";
echo strftime($format,time());
}
// Von nun an k&ouml;nnen Sie {date_now} verwenden, um das aktuelle Datum auszugeben.
// Oder {date_now format="%Y/%m/%d"}, wenn Sie es formatieren wollen.</programlisting>
</example>
</sect1>
<sect1 id="api.register.modifier">
<title>register_modifier (Modifikator-Plugin registrieren)</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>register_modifier</function></funcdef>
<paramdef>string <parameter>name</parameter></paramdef>
<paramdef>string <parameter>impl</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Wird verwendet, um Modifikator-Plugins dynamisch zu
registrieren. &Uuml;bergeben Sie dazu den Namen der Modifikator-Funktion
und den Namen der PHP-Funktion, die die entsprechende Funktionalit&auml;t
bereitstellt.
</para>
<example>
<title>register_modifier (Modifikator-Plugin registrieren)</title>
<programlisting>
// PHP's 'stripslashes()'-Funktion als Smarty Modifikator registrieren
$smarty->register_modifier("sslash", "stripslashes");
// Von nun an k&ouml;nnen Sie {$var|sslash} verwenden,
// um "\"-Zeichen (Backslash) aus Zeichenketten zu entfernen. ('\\' wird zu '\',...)</programlisting>
</example>
</sect1>
<sect1 id="api.register.outputfilter">
<title>register_outputfilter (Ausgabefilter registrieren)</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>register_outputfilter</function></funcdef>
<paramdef>string <parameter>function_name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Wird verwendet, um Ausgabefilter dynamisch zu registrieren.
Ausgabefilter ver&auml;ndern die Ausgabe,
bevor sie angezeigt wird. Konsultieren Sie dazu den
Abschnitt <link linkend="advanced.features.outputfilters">template output filters</link>
</para>
</sect1>
<sect1 id="api.register.postfilter">
<title>register_postfilter ('post'-Filter registrieren)</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>register_postfilter</function></funcdef>
<paramdef>string <parameter>function_name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Wird verwendet, um 'post'-Filter dynamisch zu registrieren. 'post'-Filter werden
auf das kompilierte Template angewendet. Konsultieren Sie dazu den
Abschnitt <link linkend="advanced.features.postfilters">template postfilters</link>.
</para>
</sect1>
<sect1 id="api.register.prefilter">
<title>register_prefilter ('pre'-Filter registrieren)</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>register_prefilter</function></funcdef>
<paramdef>string <parameter>function_name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Wird verwendet, um 'pre'-Filter dynamisch zu registrieren. 'pre'-Filter werden
vor der Kompilierung auf das Template angewendet. Konsultieren Sie dazu den
Abschnitt <link linkend="advanced.features.prefilters">template prefilters</link>.
</para>
</sect1>
<sect1 id="api.register.resource">
<title>register_resource (Ressource registrieren)</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>register_resource</function></funcdef>
<paramdef>string <parameter>name</parameter></paramdef>
<paramdef>array <parameter>resource_funcs</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Wird verwendet, um ein Ressource-Plugin dynamisch zu
registrieren. &Uuml;bergeben Sie dazu den Ressourcen-Namen und
das Array mit den Namen der PHP-Funktionen, die die Funktionalit&auml;t implementieren.
Konsultieren Sie den Abschnitt <link linkend="template.resources">template resources</link>
f&uuml;r weitere Informationen zum Thema.
</para>
<example>
<title>register_resource (Ressource registrieren)</title>
<programlisting>
$smarty->register_resource("db", array("db_get_template",
"db_get_timestamp",
"db_get_secure",
"db_get_trusted"));</programlisting>
</example>
</sect1>
<sect1 id="api.trigger.error">
<title>trigger_error (Fehler ausl&ouml;sen)</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>trigger_error</function></funcdef>
<paramdef>string <parameter>error_msg</parameter></paramdef>
<paramdef>[int <parameter>level</parameter>]</paramdef>
</funcprototype>
</funcsynopsis>
<para>
Wird verwendet, um eine Fehlermeldung via Smarty auszugeben.
Der <parameter>level</parameter>-Parameter kann alle
Werte der 'trigger_error()'-PHP-Funktion haben,
zum Beispiel E_USER_NOTICE, E_USER_WARNING, usw.
Voreingestellt ist E_USER_WARNING.
</para>
</sect1>
<sect1 id="api.template.exists">
<title>template_exists (Template existiert)</title>
<funcsynopsis>
<funcprototype>
<funcdef>bool <function>template_exists</function></funcdef>
<paramdef>string <parameter>template</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Diese Funktion pr&uuml;ft, ob das angegebene Template existiert. Als Parameter
k&ouml;nnen entweder ein Pfad im Dateisystem oder eine Ressource &uuml;bergeben werden.
</para>
</sect1>
<sect1 id="api.unregister.block">
<title>unregister_block (Block-Funktion deaktivieren)</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>unregister_block</function></funcdef>
<paramdef>string <parameter>name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Wird verwendet, um registrierte Block-Funktionen auszuschalten.
&Uuml;bergeben Sie dazu den Namen der Block-Funktion.
</para>
</sect1>
<sect1 id="api.unregister.compiler.function">
<title>unregister_compiler_function (Compiler-Funktion deaktivieren)</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>unregister_compiler_function</function></funcdef>
<paramdef>string <parameter>name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Wird verwendet, um registrierte Compiler-Funktionen auszuschalten.
&Uuml;bergeben Sie dazu den Funktionsnamen der Compiler-Funktion.
</para>
</sect1>
<sect1 id="api.unregister.function">
<title>unregister_function (Template-Funktion deaktivieren)</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>unregister_function</function></funcdef>
<paramdef>string <parameter>name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Wird verwendet, um registrierte Template-Funktionen auszuschalten.
&Uuml;bergeben Sie dazu den Namen der Template-Funktion.
</para>
<example>
<title>unregister_function</title>
<programlisting>
// Template-Designer sollen keinen Zugriff auf das Dateisystem haben
$smarty->unregister_function("fetch");</programlisting>
</example>
</sect1>
<sect1 id="api.unregister.modifier">
<title>unregister_modifier (Modifikator deaktivieren)</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>unregister_modifier</function></funcdef>
<paramdef>string <parameter>name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Wird verwendet, um registrierte Variablen-Modifikatoren auszuschalten.
&Uuml;bergeben Sie dazu den Modifikator-Namen.
</para>
<example>
<title>unregister_modifier</title>
<programlisting>
// Verhindern, dass Template-Designer 'strip_tags' anwenden
$smarty->unregister_modifier("strip_tags");</programlisting>
</example>
</sect1>
<sect1 id="api.unregister.outputfilter">
<title>unregister_outputfilter (Ausgabefilter deaktivieren)</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>unregister_outputfilter</function></funcdef>
<paramdef>string <parameter>function_name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Wird verwendet, um registrierte Ausgabefilter auszuschalten.
</para>
</sect1>
<sect1 id="api.unregister.postfilter">
<title>unregister_postfilter ('post'-Filter deaktivieren)</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>unregister_postfilter</function></funcdef>
<paramdef>string <parameter>function_name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Wird verwendet, um registrierte 'post'-Filter auszuschalten.
</para>
</sect1>
<sect1 id="api.unregister.prefilter">
<title>unregister_prefilter ('pre'-Filter deaktiviern)</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>unregister_prefilter</function></funcdef>
<paramdef>string <parameter>function_name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Wird verwendet, um registrierte 'pre'-Filter auszuschalten.
</para>
</sect1>
<sect1 id="api.unregister.resource">
<title>unregister_resource (Ressource deaktivieren)</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>unregister_resource</function></funcdef>
<paramdef>string <parameter>name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Wird verwendet, um registrierte Ressourcen auszuschalten.
&Uuml;bergeben Sie dazu den Namen der Ressource.
</para>
<example>
<title>unregister_resource (Ressource deaktivieren)</title>
<programlisting>
$smarty->unregister_resource("db");</programlisting>
</example>
</sect1>
</chapter>
<chapter id="caching">
<title>Caching</title>
<para>
Caching wird verwendet, um <link linkend="api.display">display()</link> oder
<link linkend="api.fetch">fetch()</link> Aufrufe durch zwischenspeichern (cachen)
der Ausgabe in einer Datei zu beschleunigen. Falls eine gecachte Version
des Aufrufs existiert, wird diese ausgegeben, anstatt die Ausgabe neu zu generieren.
Caching kann die Performance vor allem dann deutlich verbessern, wenn Templates
l&auml;ngere Rechenzeit beanspruchen. Weil die Ausgabe von display() und fetch() gecached
wird, kann ein Cache verschiedene Templates, Konfigurationsdateien usw. enthalten.
</para>
<para>
Da Templates dynamisch sind ist es wichtig darauf zu achten, welche Inhalte
f&uuml;r f&uuml;r wie lange gecached werden sollen. Wenn sich zum Beispiel die erste Seite Ihrer Website
nur sporadisch &auml;ndert, macht es Sinn die Seite f&uuml;r eine
Stunde oder l&auml;nger zu cachen. Wenn Sie aber eine Seite mit sich min&uuml;tlich
erneuernden Wetterinformationen haben, macht es m&ouml;glicherweise keinen Sinn,
die Seite &uuml;berhaupt zu cachen.
</para>
<sect1 id="caching.setting.up">
<title>Caching einrichten</title>
<para>
Als erstes muss das Caching eingeschaltet werden. Dies erreicht man, indem
<link linkend="variable.caching">$caching</link> auf 'true' (oder 1) gesetzt wird.
</para>
<example>
<title>Caching einschalten</title>
<programlisting>
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
$smarty->display('index.tpl');</programlisting>
</example>
<para>
Wenn Caching eingeschaltet ist, wird der Funktionsaufruf display('index.tpl')
das Template normal rendern, zur selben Zeit jedoch auch eine Datei mit
dem Inhalt in das <link linkend="variable.cache.dir">$cache_dir</link> schreiben
(als gecachte Kopie). Beim n&auml;chsten Aufruf von display('index.tpl') wird die
gecachte Kopie verwendet.
</para>
<note>
<title>Technische Bemerkung</title>
<para>
Die im '$cache_dir' abgelegen Dateien haben einen &auml;hnlichen Namen
wie das Template, mit dem sie erzeugt wurden. Obwohl sie eine '.php'-Endung
aufweisen, sind sie keine ausf&uuml;hrbaren PHP-Skripte.
Editieren Sie diese Dateien NICHT!
</para>
</note>
<para>
Jede gecachte Seite hat eine Lebensdauer, die von <link linkend="variable.cache.lifetime">$cache_lifetime</link>
bestimmt wird. Normalerweise betr&auml;gt der Wert 3600 Sekunden (= 1 Stunde). Nach Ablauf dieser Lebensdauer
wird der Cache neu generiert. Sie k&ouml;nnen die Lebensdauer pro Cache bestimmen indem Sie '$caching'
auf 2 setzen. Konsultieren Sie den Abschnitt &uuml;ber <link linkend="variable.cache.lifetime">$cache_lifetime</link>
f&uuml;r weitere Informationen.
</para>
<example>
<title>'$cache_lifetime' pro Cache einstellen</title>
<programlisting>
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = 2; // Lebensdauer ist pro Cache
// Standardwert f&uuml;r '$cache_lifetime' auf 15 Minuten setzen
$smarty->cache_lifetime = 300;
$smarty->display('index.tpl');
// '$cache_lifetime' f&uuml;r 'home.tpl' auf 1 Stunde setzen
$smarty->cache_lifetime = 3600;
$smarty->display('home.tpl');
// ACHTUNG: die folgende Zuweisung an '$cache_lifetime' wird nicht funktionieren,
// wenn '$caching' auf 2 gestellt ist. Wenn die '$cache_lifetime' f&uuml;r 'home.tpl' bereits
// auf 1 Stunde gesetzt wurde, werden neue Werte ignoriert.
// 'home.tpl' wird nach dieser Zuweisung immer noch eine '$cache_lifetime' von 1 Stunde haben.
$smarty->cache_lifetime = 30; // 30 Sekunden
$smarty->display('home.tpl');</programlisting>
</example>
<para>
Wenn <link linkend="variable.compile.check">$compile_check</link> eingeschaltet ist,
werden alle in den Cache eingeflossenen Templates und Konfigurationsdateien
hinsichtlich ihrer letzten &auml;nderung &uuml;berpr&uuml;ft.
Falls eine der Dateien seit der Erzeugung des Cache ge&auml;ndert wurde,
wird der Cache unverz&uuml;glich neu generiert. Dadurch ergibt sich ein
geringer Mehraufwand. F&uuml;r optimale Performace sollte '$compile_check'
deshalb auf 'false' gesetzt werden.
</para>
<example>
<title>'$compile_check' einschalten</title>
<programlisting>
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
$smarty->compile_check = true;
$smarty->display('index.tpl');</programlisting>
</example>
<para>
Wenn <link linkend="variable.force.compile">$force_compile</link> eingeschaltet ist,
werden die Cache-Dateien immer neu generiert und das Caching damit wirkungslos gemacht.
'$force_compile' wird normalerweise nur f&uuml;r die Fehlersuche verwendet.
Ein effizienterer Weg das Caching auszuschalten w&auml;re,
<link linkend="variable.caching">$caching</link> auf 'false' (oder 0) zu setzen.
</para>
<para>
Mit der Funktion <link linkend="api.is.cached">is_cached()</link> kann &uuml;berpr&uuml;ft
werden, ob von einem Template eine gecachte Version vorliegt.
In einem Template, das zum Beispiel Daten aus einer Datenbank bezieht,
k&ouml;nnen Sie diese Funktion verwenden, um den Prozess zu &uuml;berspringen.
</para>
<example>
<title>is_cached() verwenden</title>
<programlisting>
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
if(!$smarty->is_cached('index.tpl')) {
// kein Cache gefunden, also Variablen zuweisen
$contents = get_database_contents();
$smarty->assign($contents);
}
$smarty->display('index.tpl');</programlisting>
</example>
<para>
Mit der <link linkend="language.function.insert">insert</link> Funktion k&ouml;nnen Sie
Teile einer Seite dynamisch halten. Wenn zum Beispiel ein Banner in einer gecachten Seite
nicht gecached werden soll, kann dessen Aufruf mit 'insert' dynamisch gehalten werden.
Konsultieren Sie den Abschnitt &uuml;ber <link linkend="language.function.insert">insert</link>
f&uuml;r weitere Informationen und Beispiele.
</para>
<para>
Mit der Funktion <link linkend="api.clear.all.cache">clear_all_cache()</link> k&ouml;nnen
Sie den gesamten Template-Cache l&ouml;schen. Mit <link linkend="api.clear.cache">clear_cache()</link>
einzelne Templates oder Template-Gruppen.
</para>
<example>
<title>Cache leeren</title>
<programlisting>
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
// alle Cache-Dateien l&ouml;schen
$smarty->clear_all_cache();
// nur Cache von 'index.tpl' l&ouml;schen
$smarty->clear_cache('index.tpl');
$smarty->display('index.tpl');</programlisting>
</example>
</sect1>
<sect1 id="caching.multiple.caches">
<title>Multiple Caches f&uuml;r eine Seite</title>
<para>
Sie k&ouml;nnen f&uuml;r Aufrufe von 'display()' oder 'fetch()' auch mehrere Caches erzeugen.
Nehmen wir zum Beispiel an, der Aufruf von display('index.tpl') erzeuge f&uuml;r
verschieden F&auml;lle unterschiedliche Inhalte und Sie wollen jeden dieser Inhalte
separat cachen. Um dies zu erreichen, k&ouml;nnen Sie eine 'cache_id' beim Funktionsaufruf
&uuml;bergeben.
</para>
<example>
<title>'display()' eine 'cache_id' &uuml;bergeben</title>
<programlisting>
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
$my_cache_id = $_GET['article_id'];
$smarty->display('index.tpl', $my_cache_id);</programlisting>
</example>
<para>
Im oberen Beispiel &uuml;bergeben wir die Variable '$my_cache_id'
als 'cache_id' an 'display()'. F&uuml;r jede einmalige 'cache_id'
wird ein eigener Cache von 'index.tpl' erzeugt. In diesem
Beispiel wurde 'article_id' per URL &uuml;bergeben und als 'cache_id' verwendet.
</para>
<note>
<title>Technische Bemerkung</title>
<para>
Seien Sie vorsichtig, wenn Sie Smarty (oder jeder anderen PHP-Applikation)
Werte direkt vom Client (Webbrowser) &uuml;bergeben. Obwohl das Beispiel oben
praktisch aussehen mag, kann es schwerwiegende Konsequenzen haben. Die 'cache_id'
wird verwendet, um im Dateisystem ein Verzeichnis zu erstellen. Wenn ein Benutzer
also &uuml;berlange Werte &uuml;bergibt oder ein Skript benutzt, das in hohem
Tempo neue 'article_ids' &uuml;bermittelt, kann dies auf dem Server zu Problemen
f&uuml;hren. Stellen Sie daher sicher, dass Sie alle empfangenen Werte auf
ihre G&uuml;ltigkeit &uuml;berpr&uuml;fen und unerlaubte Sequenzen entfernen.
Sie wissen m&ouml;glicherweise, dass ihre 'article_id' nur 10 Zeichen lang sein kann, nur
aus alphanumerischen Zeichen bestehen darf und in der Datenbank eingetragen
sein muss. &uuml;berp&uuml;fen sie das!
</para>
</note>
<para>
Denken Sie daran, Aufrufen von <link linkend="api.is.cached">is_cached()</link>
und <link linkend="api.clear.cache">clear_cache()</link> als zweiten Parameter
die 'cache_id' zu &uuml;bergeben.
</para>
<example>
<title>'is_cached()' mit 'cache_id' aufrufen</title>
<programlisting>
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
$my_cache_id = $_GET['article_id'];
if(!$smarty->is_cached('index.tpl', $my_cache_id)) {
// kein Cache gefunden, also Variablen zuweisen
$contents = get_database_contents();
$smarty->assign($contents);
}
$smarty->display('index.tpl', $my_cache_id);</programlisting>
</example>
<para>
Sie k&ouml;nnen mit 'clear_cache()' den gesamten Cache einer bestimmten 'cache_id'
auf einmal l&ouml;schen, wenn Sie als Parameter die 'cache_id' &uuml;bergeben.
</para>
<example>
<title>Cache einer bestimmten 'cache_id' leeren</title>
<programlisting>
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
// Cache mit 'sports' als 'cache_id' l&ouml;schen
$smarty->clear_cache(null, "sports");
$smarty->display('index.tpl', "sports");</programlisting>
</example>
<para>
Indem Sie allen dieselbe 'cache_id' &uuml;bergeben, lassen sich Caches gruppieren.
</para>
</sect1>
<sect1 id="caching.groups">
<title>Cache-Gruppen</title>
<para>
Sie k&ouml;nnen auch eine feinere Gruppierung vornehmen, indem Sie
'cache_id'-Gruppen erzeugen. Dies erreichen Sie, indem Sie jede Cache-Untergruppe
durch ein '|'-Zeichen (pipe) in der 'cache_id' abtrennen. Sie k&ouml;nnen so viele
Untergruppen erstellen, wie Sie m&ouml;chten.
</para>
<example>
<title>'cache_id'-Gruppen</title>
<programlisting>
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
// leere alle Caches welche 'sports|basketball' als erste zwei 'cache_id'-Gruppen enthalten
$smarty->clear_cache(null, "sports|basketball");
// leere alle Caches welche 'sports' als erste 'cache_id'-Gruppe haben. Dies schliesst
// 'sports|basketball', oder 'sports|(anything)|(anything)|(anything)|...' ein
$smarty->clear_cache(null, "sports");
$smarty->display('index.tpl',"sports|basketball");</programlisting>
</example>
<note>
<title>Technische Bemerkung</title>
<para>
Cache-Gruppierung benutzt nicht den Pfad zum Template f&uuml;r die 'cache_id'. Wenn Sie
zum Beispiel display('themes/blue/index.tpl') aufrufen, k&ouml;nnen Sie NICHT
den ganzen Cache unter 'themes/blue' leeren. Wenn Sie dies tun m&ouml;chten,
m&uuml;ssen Sie die Caches anhand der 'cache_id' gruppieren - zum Beispiel
display('themes/blue/index.tpl','themes|blue');
Danach k&ouml;nnen Sie alle Caches des 'blue-theme' mit clear_cache(null, 'themes|blue');
leeren.
</para>
</note>
</sect1>
</chapter>
<chapter id="advanced.features">
<title>Advanced Features</title>
<sect1 id="advanced.features.prefilters">
<title>'pre'-Filter</title>
<para>
Template 'pre'-Filter sind Filter, welche auf das Template vor dessen Kompilierung
angewendet werden. Dies ist n&uuml;tzlich, um zum Beispiel Kommentare zu entfernen
oder um den Inhalt des Templates zu analysieren. 'pre'-Filter k&ouml;nnen auf verschiedene
Arten geladen werden. Man kann sie <link linkend="api.register.prefilter">registrieren</link>,
aus dem Plugin-Verzeichnis mit <link linkend="api.load.filter">load_filter()</link> laden
oder <link linkend="variable.autoload.filters">$autoload_filters</link> verwenden.
Smarty &uuml;bergibt der Funktion als ersten Parameter den Template-Quellcode und erwartet
als R&uuml;ckgabewert den bearbeiteten Quellcode.
</para>
<example>
<title>Template 'pre'-Filter verwenden</title>
<programlisting>
&lt;?php
// f&uuml;gen Sie folgende Zeilen in Ihre Applikation ein
function remove_dw_comments($tpl_source, &$smarty)
{
return preg_replace("/&lt;!--#.*--&gt;/U","",$tpl_source);
}
// registrieren Sie den 'pre'-Filter
$smarty->register_prefilter("remove_dw_comments");
$smarty->display("index.tpl");
?&gt;
{* Smarty Template 'index.tpl' *}
&lt;!--# diese Zeile wird vom 'pre'-Filter entfernt--&gt;</programlisting>
</example>
</sect1>
<sect1 id="advanced.features.postfilters">
<title>'post'-Filter</title>
<para>
Template 'post'-Filter sind Filter, welche auf das Template nach dessen Kompilierung
angewendet werden. 'post'-Filter k&ouml;nnen auf verschiedene Arten
geladen werden. Man kann sie <link linkend="api.register.prefilter">registrieren</link>,
aus dem Plugin-Verzeichnis mit <link linkend="api.load.filter">load_filter()</link> laden
oder <link linkend="variable.autoload.filters">$autoload_filters</link> verwenden.
Smarty &uuml;bergibt der Funktion als ersten Parameter den Template-Quellcode und erwartet
als R&uuml;ckgabewert den bearbeiteten Quellcode.
</para>
<example>
<title>Template 'post'-Filter verwenden</title>
<programlisting>
&lt;?php
// f&uuml;gen Sie folgende Zeilen in Ihre Applikation ein
function add_header_comment($tpl_source, &$smarty)
{
return "&lt;?php echo \"&lt;!-- Created by Smarty! --&gt;\n\" ?&gt;\n".$tpl_source;
}
// registrieren Sie den 'post'-Filter
$smarty->register_postfilter("add_header_comment");
$smarty->display("index.tpl");
?&gt;
{* kompiliertes Smarty Template 'index.tpl' *}
&lt;!-- Created by Smarty! --&gt;
{* Rest des Template Inhalts... *}</programlisting>
</example>
</sect1>
<sect1 id="advanced.features.outputfilters">
<title>Ausgabefilter</title>
<para>
Wenn ein Template mit 'display()' oder 'fetch()' benutzt wird, kann die
Ausgabe durch verschieden Ausgabefilter geschleust werden. Der Unterschied zu
'post'-Filtern ist, dass Ausgabefilter auf die durch 'fetch()' oder
'display()' erzeugte Ausgabe angewendet werden, 'post'-Filter aber auf das Kompilat vor
seiner Speicherung im Dateisystem.
</para>
<para>
Ausgabefilter k&ouml;nnen auf verschiede Arten
geladen werden. Man kann sie <link linkend="api.register.prefilter">registrieren</link>,
aus dem Plugin-Verzeichnis mit <link linkend="api.load.filter">load_filter()</link> laden
oder <link linkend="variable.autoload.filters">$autoload_filters</link> verwenden.
Smarty &uuml;bergibt der Funktion als ersten Parameter die Template-Ausgabe und erwartet
als R&uuml;ckgabewert die bearbeitete Ausgabe.
</para>
<example>
<title>Ausgabefilter verwenden</title>
<programlisting>
&lt;?php
// f&uuml;gen Sie folgende Zeilen in Ihre Applikation ein
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;
}
// Ausgabefilter registrieren
$smarty->register_outputfilter("protect_email");
$smarty->display("index.tpl");
// von nun an erhalten alle ausgegebenen e-mail Adressen einen
// einfach Schutz vor Spambots.
?&gt;</programlisting>
</example>
</sect1>
<sect1 id="section.template.cache.handler.func">
<title>Cache Handler Funktion</title>
<para>
Als Alternative zum normalen dateibasierten Caching-Mechanismus k&ouml;nnen Sie
eine eigene Cache-Handler Funktion zum lesen, schreiben und l&ouml;schen von
Cache-Dateien definieren.
</para>
<para>
Schreiben Sie eine Funktion in Ihrer Applikation, die Smarty als
Cache-Handler verwenden soll und weisen Sie deren Name der Variable
<link linkend="variable.cache.handler.func">$cache_handler_func</link> zu.
Smarty wird von da an Ihre Funktion zur Bearbeitung des Caches verwenden.
Als erster Parameter wird die 'action' mit einem der folgendende Werte
&uuml;bergeben: 'read', 'write' und 'clear'. Als zweiter Parameter
wird das Smarty-Objekt &uuml;bergeben, als dritter der gecachte Inhalt. Bei einem
'write' &uuml;bergibt Smarty den gecachten Inhalt, bei 'read' &uuml;bergibt Smarty die
Variable als Referenz und erwartet, dass Ihre Funktion die Inhalte zuweist.
Bei 'clear' k&ouml;nnen Sie eine dummy-Variable &uuml;bergeben. Als vierter Parameter
wird der Template-Name &uuml;bergeben (verwendet bei 'write'/'read'), als f&uuml;nfter
Parameter die 'cache_id' (optional) und als sechster die 'compile_id' (auch optional).
</para>
<example>
<title>Beispiel mit einer MySQL Datenbank als Datenquelle</title>
<programlisting>
&lt;?php
/*
Beispiel Anwendung:
include('Smarty.class.php');
include('mysql_cache_handler.php');
$smarty = new Smarty;
$smarty-&gt;cache_handler_func = 'mysql_cache_handler';
$smarty-&gt;display('index.tpl');
die Datenbank hat folgendes 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)
{
// Datenbank Host, Benutzer und Passwort festlegen
$db_host = 'localhost';
$db_user = 'myuser';
$db_pass = 'mypass';
$db_name = 'SMARTY_CACHE';
$use_gzip = false;
// enmalige 'cache_id' erzeugen
$CacheID = md5($tpl_file.$cache_id.$compile_id);
if(! $link = mysql_pconnect($db_host, $db_user, $db_pass)) {
$smarty_obj-&gt;_trigger_error_msg("cache_handler: could not connect to database");
return false;
}
mysql_select_db($db_name);
switch ($action) {
case 'read':
// Cache aus der Datenbank lesen
$results = mysql_query("select CacheContents from CACHE_PAGES where CacheID='$CacheID'");
if(!$results) {
$smarty_obj-&gt;_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':
// Cache in Datenbank speichern
if($use_gzip && function_exists("gzcompress")) {
// compress the contents for storage efficiency
$contents = gzcompress($cache_content);
} else {
$contents = $cache_content;
}
$results = mysql_query("replace into CACHE_PAGES values(
'$CacheID',
'".addslashes($contents)."')
");
if(!$results) {
$smarty_obj-&gt;_trigger_error_msg("cache_handler: query failed.");
}
$return = $results;
break;
case 'clear':
// Cache Informationen l&ouml;schen
if(empty($cache_id) && empty($compile_id) && empty($tpl_file)) {
// alle l&ouml;schen
$results = mysql_query("delete from CACHE_PAGES");
} else {
$results = mysql_query("delete from CACHE_PAGES where CacheID='$CacheID'");
}
if(!$results) {
$smarty_obj-&gt;_trigger_error_msg("cache_handler: query failed.");
}
$return = $results;
break;
default:
// Fehler, unbekannte 'action'
$smarty_obj-&gt;_trigger_error_msg("cache_handler: unknown action \"$action\"");
$return = false;
break;
}
mysql_close($link);
return $return;
}
?&gt;</programlisting>
</example>
</sect1>
<sect1 id="template.resources">
<title>Ressourcen</title>
<para>
Ein Template kann aus verschiedenen Quellen bezogen werden. Wenn Sie
ein Template mit 'display()' ausgeben, die Ausgabe mit 'fetch()'
in einer Variablen speichern oder innnerhalb eines Template ein
weiteres Template einbinden, m&uuml;ssen Sie den Ressourcen-Typ,
gefolgt von Pfad und Template-Namen angeben.
</para>
<sect2 id="templates.from.template.dir">
<title>Templates aus dem '$template_dir'</title>
<para>
Templates aus dem '$template_dir' ben&ouml;tigen normalerweise keinen Ressourcen-Typ,
es wird jedoch empfohlen 'file:' zu verwenden. &Uuml;bergeben Sie einfach den Pfad,
in dem sich das Template relativ zu '$template_dir' befindet.
</para>
<example>
<title>Templates aus '$template_dir' verwenden</title>
<programlisting>
// im PHP-Skript
$smarty->display("index.tpl");
$smarty->display("admin/menu.tpl");
$smarty->display("file:admin/menu.tpl"); // entspricht der vorigen Zeile
{* im Smarty Template *}
{include file="index.tpl"}
{include file="file:index.tpl"} {* entspricht der vorigen Zeile *}</programlisting>
</example>
</sect2>
<sect2 id="templates.from.any.dir">
<title>Templates aus beliebigen Verzeichnissen</title>
<para>
Templates ausserhalb von '$template_dir' ben&ouml;tigen den 'file:' Ressourcen-Typ,
gefolgt von absolutem Pfadnamen und Templatenamen.
</para>
<example>
<title>Templates aus beliebigen Verzeichnissen benutzen</title>
<programlisting>
// im PHP-Skript
$smarty->display("file:/export/templates/index.tpl");
$smarty->display("file:/path/to/my/templates/menu.tpl");
{* im Smarty Template *}
{include file="file:/usr/local/share/templates/navigation.tpl"}</programlisting>
</example>
<sect3>
<title>Windows Dateipfade</title>
<para>
Wenn Sie auf einer Windows-Maschine arbeiten, enthalten absoluten Dateipfade
normalerweise den Laufwerksbuchstaben (C:). Stellen Sie sicher,
dass alle Pfade den Ressourcen-Typ 'file:' haben, um Namespace-Konflikten
vorzubeugen.
</para>
<example>
<title>Templates aus Windows Dateipfaden verwenden</title>
<programlisting>
// im PHP-Skript
$smarty->display("file:C:/export/templates/index.tpl");
$smarty->display("file:F:/path/to/my/templates/menu.tpl");
{* im Smarty Template *}
{include file="file:D:/usr/local/share/templates/navigation.tpl"}</programlisting>
</example>
</sect3>
</sect2>
<sect2 id="templates.from.elsewhere">
<title>Templates aus anderen Quellen</title>
<para>
Sie k&ouml;nnen Templates aus jeder f&uuml;r PHP verf&uuml;gbaren Datenquelle beziehen:
Datenbanken, Sockets, LDAP, usw. Dazu m&uuml;ssen sie nur ein
Ressource-Plugin schreiben und registrieren.
</para>
<para>
Konsultieren Sie den Abschnitt &uuml;ber <link linkend="plugins.resources">Ressource-Plugins</link>
f&uuml;r mehr Informationen &uuml;ber die Funktionalit&auml;ten, die ein derartiges Plugin bereitstellen muss.
</para>
<note>
<para>
Achtung: Sie k&ouml;nnen die interne <literal>file</literal> Ressource nicht
&uuml;berschreiben. Es steht Ihnen jedoch frei, ein Plugin zu schreiben,
das die gew&uuml;nschte Funktionalit&auml;t implementiert und es als alternativen
Ressource-Typ zu registrieren.
</para>
</note>
<example>
<title>Eigene Quellen verwenden</title>
<programlisting>
// im PHP-Skript
// definieren Sie folgende Funktion in Ihrer Applikation
function db_get_template ($tpl_name, &amp;tpl_source, &amp;$smarty_obj)
{
// Datenbankabfrage um unser Template zu laden,
// und '$tpl_source' 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 db_get_timestamp($tpl_name, &$tpl_timestamp, &$smarty_obj)
{
// Datenbankabfrage 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 db_get_secure($tpl_name, &$smarty_obj)
{
// angenommen alle Templates sind sicher
return true;
}
function db_get_trusted($tpl_name, &$smarty_obj)
{
// wird f&uuml;r Templates nicht verwendet
}
// Ressourcen-Typ 'db:' registrieren
$smarty->register_resource("db", array("db_get_template",
"db_get_timestamp",
"db_get_secure",
"db_get_trusted"));
// Ressource im PHP-Skript verwenden
$smarty->display("db:index.tpl");
{* Ressource in einem Smarty Template verwenden *}
{include file="db:/extras/navigation.tpl"}</programlisting>
</example>
</sect2>
<sect2 id="default.template.handler.function">
<title>Standard Template-Handler</title>
<para>
Sie k&ouml;nnen eine Funktion definieren, die aufgerufen wird,
wenn ein Template nicht aus der angegeben Ressource geladen werden konnte.
Dies ist z. B. n&uuml;tzlich, wenn Sie fehlende Templates on-the-fly
generieren wollen.
</para>
<example>
<title>Standard Template-Handler verwenden</title>
<programlisting>
&lt;?php
// f&uuml;gen Sie folgende Zeilen in Ihre Applikation ein
function make_template ($resource_type, $resource_name, &amp;$template_source, &amp;$template_timestamp, &amp;$smarty_obj)
{
if( $resource_type == 'file' ) {
if ( ! is_readable ( $resource_name )) {
// erzeuge Template-Datei, gib Inhalte zur&uuml;ck
$template_source = "This is a new template.";
$template_timestamp = time();
$smarty_obj->_write_file($resource_name, $template_source);
return true;
}
} else {
// keine Datei
return false;
}
}
// Standard Handler definieren
$smarty->default_template_handler_func = 'make_template';
?&gt;</programlisting>
</example>
</sect2>
</sect1>
</chapter>
<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>
<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>
Aus Performancegr&uuml;nden existiert nur ein Plugin-Verzeichnis. Um ein Plugin
zu installieren, speichern Sie es einfach in diesem Verzeichnis. Smarty wird
es danach automatisch erkennen.
</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_DIR . 'plugins/function.html_options.php';</programlisting>
<para>
Das Smarty Objekt wird jedem Plugin immer als letzter Parameter
&uuml;bergeben (ausser bei Variablen-Modifikatoren).
</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>&$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>&$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.
</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>
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 ($content) {
$lang = $params['lang'];
// den $content irgendwie intelligent &uuml;bersetzuen
echo $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>&$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, &$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>&$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>&$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, &$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, &$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>&$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, &$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>&$source</parameter></paramdef>
<paramdef>object <parameter>&$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>&$timestamp</parameter></paramdef>
<paramdef>object <parameter>&$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>&$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>&$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>&$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>
</part>
Reference in New Issue View Git Blame Copy Permalink