2003-03-06 23:37:24 +00:00
<!-- Smarty German Documentation Port -->
<!-- $Id$ -->
<!-- $Author$ -->
<!-- $Revision$ -->
<part id="smarty.for.programmers">
<title>Smarty fü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 übergeben,
werden sie in diesem Pfad gesucht. Normalerweise lautet er './templates'.
Das heisst, Smarty erwartet das Template-Verzeichnis im selben Verzeichnis
wie das ausgefü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ü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ü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ü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ält.
</para>
</sect1>
<sect1 id="variable.debug.tpl">
<title>$debug_tpl</title>
<para>
Definiert den Namen des fü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ü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ü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üssel/Wert-Paare,
bei welchen der Schlü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önnen ü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ür weiterführende Informationen.
</para>
</note>
</sect1>
<sect1 id="variable.undefined">
<title>$undefined</title>
<para>
Definiert den Wert von '$undefined' fü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öchten, können Sie mit Hilfe
dieser Variable festlegen. Smarty wird sie danach automatisch laden. Die Variable
enthält ein assoziatives Array, in dem der Schlüssel den Filter-Typ
und der Wert den Filter-Namen definiert. Zum Beispiel:
<informalexample>
<programlisting>
$smarty->autoload_filters = array('pre' => 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 überprüft Smarty,
ob sich das zugrundeliegende Template seit dem letzten Aufruf
geändert hat. Falls es eine Änderung feststellt,
wird das Template neu kompiliert. Seit Smarty 1.4.0 wird
das Template - falls es nicht existiert - kompiliert, unabhängig
davon welcher Wert '$compile_check' hat. Normalerweise ist der
Wert dieser Variable 'true'. Wenn eine Applikation produktiv
eingesetzt wird (die Templates ä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 ändern, wird diese Änderung *nicht* angezeigt.
Wenn caching und 'compile_check' eingeschaltet sind, werden die
gecachten Skripts neu kompiliert, sobald eine Ä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 überschreibt '$compile_check'.
Normalerweise ist dies ausgeschaltet, kann jedoch für die Fehlersuche
nü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önnen auch mehrere Caches fü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önnen Sie 'cache_lifetime'
setzen, bevor Sie das Template einbinden und haben so eine feine Kontrolle darüber,
wann ein bestimmter Cache ablä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ä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ö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ü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äuft. Der Wert 0 bewirkt, dass
der Inhalt immer neu generiert wird (nur sinnvoll für Tests, eine
effizientere Methode wä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önnen Sie alle Cache-Dateien auf einmal entfernen. Mit der
<link linkend="api.clear.cache">clear_cache()</link> Funktion kö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ö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ö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ä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ü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ü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'
überschrieben):
</para>
<itemizedlist>
<listitem><para>Wenn '$php_handling' auf SMARTY_PHP_ALLOW geschaltet ist, wird der Wert auf SMARTY_PHP_PASSTHRU geändert.</para></listitem>
<listitem><para>Ausser den in '$security_settings' definierten, sind keine Funktionen in IF-Statements aufrufbar.</para></listitem>
<listitem><para>Templates kö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
ä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ü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ürdig gelten.
In diesen Verzeichnissen kö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>
2003-09-08 16:35:05 +00:00
<sect1 id="variable.show.info.header">
<title>$show_info_header</title>
<para>
Gibt am Anfang der HTML-Seite die Smarty Version und das Kompilier-Datum des Templates
als Kommentar aus. Normalerweise 'false'.
</para>
</sect1>
<sect1 id="variable.show.info.include">
<title>$show_info_include</title>
<para>
Gibt am Anfang und am Ende jedes eingebundenen Templates einen HTML-Kommentar aus.
Normalerweise 'false'.
</para>
</sect1>
2003-03-06 23:37:24 +00:00
<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ü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ält sich wie 'variables_order' in der php.ini.
</para>
</sect1>
2003-09-08 16:35:05 +00:00
<sect1 id="variable.request.use.auto.globals">
<title>$request_use_auto_globals</title>
<para>
Definiert ob Smarty php's $HTTP_*_VARS[] ($request_use_auto_globals=false welches
der Standardwert ist) oder $_*[] ($request_use_auto_globals=true) verwenden soll.
Dies betrifft Templates die {$smarty.request.*}, {$smarty.get.*}, etc... verwenden.
Achtung: wenn $request_use_auto_globals auf TRUE gesetzt ist, hat <link linkend="variable.request.vars.order">variable.request.vars.order </link>
keine Auswirkungen, da php's Konfigurationswert <literal>gpc_order</literal> verwendet wird.
</para>
</sect1>
2003-03-06 23:37:24 +00:00
<sect1 id="variable.compile.id">
<title>$compile_id</title>
<para>
Persistenter 'compile-identifier'. Anstatt jedem Funktionsaufruf die selbe 'compile_id'
zu ü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önnen Sie diesen Wert auf 'false' setzen. Unterverzeichnisse
sind jedoch effizienter und sollten deshalb mö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ässig HTML-Maskieren wollen,
können Sie array('escape:"htmlall"'); verwenden. Um eine Variable von dieser
2003-09-08 16:35:05 +00:00
Behandlung auszuschliessen, können Sie ihr den Parameter 'smarty' mit dem Modifikator 'nodefaults'
übergeben. Als Beispiel: {$var|smarty:nodefaults}.
2003-03-06 23:37:24 +00:00
Zum Beispiel: {$var|nodefaults}.
</para>
</sect1>
2003-09-08 16:35:05 +00:00
<sect1 id="variable.default.resource.type">
<title>$default_resource_type</title>
<para>
Definiert den Ressourcentyp der von Smarty implizitverwendet werden soll. Standartwert
ist 'file', was dazu führt dass $smarty->display('index.tpl'); und
$smarty->display('file:index.tpl'); identisch sind. Konsultieren Sie das
<link linkend="template.resources">Resource</link> Kapitel für weitere Informationen.
</para>
</sect1>
2003-03-06 23:37:24 +00:00
</chapter>
<chapter id="api.functions">
<title>Methoden</title>
<sect1 id="api.append">
<title>append (anhä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>
</funcsynopsis>
<para>
Wird verwendet, um an Template-Variablen weitere Daten anzuhängen. Sie
können entweder ein Namen/Wert-Paar oder assoziative Arrays,
2003-09-08 16:35:05 +00:00
die mehrere Namen/Wert-Paare enthalten, übergeben.
2003-03-06 23:37:24 +00:00
</para>
<example>
<title>append (anhängen)</title>
<programlisting>
// Namen/Wert-Paare übergeben
$smarty->append("Name","Fred");
$smarty->append("Address",$address);
// assoziatives Array übergeben
$smarty->append(array("city" => "Lincoln","state" => "Nebraska"));</programlisting>
</example>
</sect1>
<sect1 id="api.append.by.ref">
<title>append_by_ref (via Referenz anhä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>
</funcsynopsis>
<para>
Wird verwendet, um an Template-Variablen Werte via Referenz (pass by reference) anstatt via Kopie
2003-09-08 16:35:05 +00:00
anzuhängen. Konsultieren Sie das PHP-Manual zum Thema 'variable referencing'
für weitere Erklärungen.
2003-03-06 23:37:24 +00:00
</para>
<note>
<title>Technische Bemerkung</title>
<para>
2003-09-08 16:35:05 +00:00
'append_by_ref()' ist effizienter als 'append()', da keine Kopie der Variable
erzeugt, sondern auf die Variable im Speicher referenziert wird. Beachten Sie
dabei, dass eine nachträgliche änderung Original-Variable auch die zugewiesene Variable
ändert. PHP5 wird die Referenzierung automatisch übernehmen, diese
Funktion dient als Workaround.
2003-03-06 23:37:24 +00:00
</para>
</note>
<example>
<title>append_by_ref (via Referenz anhängen)</title>
<programlisting>
// Namen/Wert-Paare ü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önnen
entweder Namen/Wert-Paare oder ein assoziatives Array
mit Namen/Wert-Paaren übergeben.
</para>
<example>
<title>assign</title>
<programlisting>
// Namen/Wert-Paare übergeben
$smarty->assign("Name","Fred");
$smarty->assign("Address",$address);
// assoziatives Array mit Namen/Wert-Paaren ü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ür weitere Erklärungen.
</para>
<note>
<title>Technical Note</title>
<para>
2003-09-08 16:35:05 +00:00
'assign_by_ref()' ist effizienter als 'assign()', da keine Kopie der Variable
erzeugt wird, sondern auf die Variable im Speicher referenziert wird. Beachten Sie
dabei, dass eine nachträgliche änderung Original-Variable auch die zugewiesene Variable
ändert. PHP5 wird die Referenzierung automatisch übernehmen, diese
Funktion dient als Workaround.
2003-03-06 23:37:24 +00:00
</para>
</note>
<example>
<title>assign_by_ref (via Referenz zuweisen)</title>
<programlisting>
// Namen/Wert-Paare ü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öschen)</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>clear_all_assign</function></funcdef>
<paramdef><parameter></parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Löscht die Werte aller zugewiesenen Variablen.
</para>
<example>
<title>clear_all_assign (alle Zuweisungen löschen)</title>
<programlisting>
// lösche alle zugewiesenen Variablen
$smarty->clear_all_assign();</programlisting>
</example>
</sect1>
<sect1 id="api.clear.all.cache">
<title>clear_all_cache (Cache vollstä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öscht wird.
</para>
<example>
<title>clear_all_cache (Cache vollständig leeren)</title>
<programlisting>
// leere den gesamten cache
$smarty->clear_all_cache();</programlisting>
</example>
</sect1>
<sect1 id="api.clear.assign">
<title>clear_assign (lösche Zuweisung)</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>clear_assign</function></funcdef>
<paramdef>string <parameter>var</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Löscht den Wert einer oder mehrerer (übergabe als Array) zugewiesener Variablen.
</para>
<example>
<title>clear_assign (lösche Zuweisung)</title>
<programlisting>
// lösche eine einzelne Variable
$smarty->clear_assign("Name");
// lö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öscht den Cache eines bestimmten Templates. Falls Sie mehrere
Caches für ein Template verwenden, können Sie als zweiten Parameter
die 'cache_id' des zu leerenden Caches übergeben. Als dritten Parameter
können sie die 'compile_id' angeben. Sie können Templates auch
gruppieren und dann als Gruppe aus dem Cache löschen. Sehen sie dazu den Abschnitt über
<link linkend="caching">caching</link>. Als vierten Parameter können Sie
ein Mindestalter in Sekunden angeben, das ein Cache aufweisen muss,
bevor er gelö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öschen)</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>clear_compiled_tpl</function></funcdef>
<paramdef>string <parameter>tpl_file</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Löscht die kompilierte Version des angegebenen Templates. Falls
kein Template-Name übergeben wird, werden alle kompilierten
Templates gelöscht. Diese Funktion ist für fortgeschrittene Benutzer.
</para>
<example>
<title>clear_compiled_tpl (kompiliertes Template löschen)</title>
<programlisting>
// ein bestimmtes kompiliertes Template löschen
$smarty->clear_compiled_tpl("index.tpl");
// das gesamte Kompilier-Verzeichnis lö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üssen einen gültigen
<link linkend="template.resources">Template Ressourcen</link>-Typ
inklusive Pfad angeben. Als optionalen zweiten Parameter können
Sie eine 'cache_id' übergeben. Konsultieren
Sie den Abschnitt über <link linkend="caching">caching</link> für weitere Informationen.
</para>
<para>
Als optionalen dritten Parameter können Sie eine 'compile_id' ü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ür jedes Verzeichnis eine
eigene 'compile_id', andernfalls werden Templates mit dem gleichen Namen
überschrieben. Sie können die Variable <link linkend="variable.compile.id">$compile_id</link>
auch einmalig setzen, anstatt sie bei jedem Aufruf von 'display()' zu übergeben.
</para>
<example>
<title>display (ausgeben)</title>
<programlisting>
include("Smarty.class.php");
$smarty = new Smarty;
$smarty->caching = true;
// Datenbank-Aufrufe nur durchfü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ü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ück, anstatt es direkt anzuzeigen. Übergeben Sie
einen gültigen <link linkend="template.resources">Template Ressource</link>-Typ
und -Pfad. Als optionaler zweiter Parameter kann eine 'cache_id' übergeben werden.
Bitte konsultieren Sie den Abschnitt über <link linkend="caching">caching </link>
für weitere Informationen.
</para>
<para>
Als optionalen dritten Parameter können Sie eine 'compile_id' ü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ür jedes Verzeichnis eine
eigene 'compile_id', andernfalls werden Templates mit dem gleichen Namen
überschrieben. Sie können die Variable <link linkend="variable.compile.id">$compile_id</link>
auch einmalig setzen, anstatt sie bei jedem Aufruf von 'fetch()' zu übergeben.
</para>
<example>
<title>fetch</title>
<programlisting>
include("Smarty.class.php");
$smarty = new Smarty;
$smarty->caching = true;
// Datenbank-Aufrufe nur durchfü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.template.vars">
<title>get_template_vars (Template-Variablen extrahieren)</title>
<funcsynopsis>
<funcprototype>
<funcdef>array <function>get_template_vars</function></funcdef>
2003-09-08 16:35:05 +00:00
<paramdef><parameter></parameter></paramdef>
2003-03-06 23:37:24 +00:00
</funcprototype>
</funcsynopsis>
<para>
2003-09-08 16:35:05 +00:00
Gibt ein Array der zugewiesenen Template-Variablen zurück.
2003-03-06 23:37:24 +00:00
</para>
<example>
<title>get_template_vars (Template-Variablen extrahieren)</title>
<programlisting>
2003-09-08 16:35:05 +00:00
// alle zugewiesenen Template-Variablen extrahieren
$tpl_vars = $smarty->get_template_vars();
// Anschauen
var_dump($tpl_vars);</programlisting>
2003-03-06 23:37:24 +00:00
</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ück, wenn ein gültiger Cache fü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önnen Sie die 'cache_id' übergeben,
falls Sie mehrere Caches fü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ö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>
2003-09-08 16:35:05 +00:00
<paramdef>mixed <parameter>impl</parameter></paramdef>
<paramdef>bool <parameter>cacheable</parameter></paramdef>
<paramdef>array or null <parameter>cache_attrs</parameter></paramdef>
2003-03-06 23:37:24 +00:00
</funcprototype>
</funcsynopsis>
<para>
Wird verwendet, um Block-Funktion-Plugins dynamisch zu registrieren.
Übergeben Sie dazu den Namen der Block-Funktion und den Namen der
2003-09-08 16:35:05 +00:00
PHP-Callback-Funktion, die die entsprechende Funktionalität bereitstellt.
</para>
<para>
Der Parameter <parameter>impl</parameter> kann als (a) einen Funktionnamen oder (b) einem Array der Form <literal>array(&$object, $method)</literal>,
wobei <literal>&$object</literal> eine Referenz zu einem Objekt und <literal>$method</literal> der Name der Methode die aufgerufen werden soll ist,
oder als Array der Form <literal>array(&$class, $method)</literal>, wobei <literal>$class</literal> der Name der Klasse und <literal>$method</literal>
der Name der Methode ist die aufgerufen werden soll, übergeben werden.
</para>
<para>
<parameter>$cacheable</parameter> und <parameter>$cache_attrs</parameter> können in den meisten Fällen weggelassen werden. Konsultieren Sie <link linkend="caching.cacheable">Die Ausgabe von cachebaren Plugins Kontrollieren</link> für weitere Informationen.
2003-03-06 23:37:24 +00:00
</para>
<example>
<title>register_block (Block-Funktion registrieren)</title>
<programlisting>
/* PHP */
$smarty->register_block("translate", "do_translation");
2003-09-08 16:35:05 +00:00
function do_translation ($params, $content, &$smarty, &$repeat) {
if (isset($content)) {
2003-03-06 23:37:24 +00:00
$lang = $params['lang'];
// übersetze den Inhalt von '$content'
2003-09-08 16:35:05 +00:00
return $translation;
2003-03-06 23:37:24 +00:00
}
}
{* 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>
2003-09-08 16:35:05 +00:00
<paramdef>mixed <parameter>impl</parameter></paramdef>
<paramdef>bool <parameter>cacheable</parameter></paramdef>
2003-03-06 23:37:24 +00:00
</funcprototype>
</funcsynopsis>
<para>
Wird verwendet, um Compiler-Funktion-Plugins dynamisch zu
registrieren. Übergeben Sie dazu den Namen der Compiler-Funktion und den Namen der
PHP-Funktion, die die entsprechende Funktionalität bereitstellt.
</para>
2003-09-08 16:35:05 +00:00
<para>
Der Parameter <parameter>impl</parameter> kann als (a) einen Funktionnamen oder (b) einem Array der Form <literal>array(&$object, $method)</literal>,
wobei <literal>&$object</literal> eine Referenz zu einem Objekt und <literal>$method</literal> der Name der Methode die aufgerufen werden soll ist,
oder als Array der Form <literal>array(&$class, $method)</literal>, wobei <literal>$class</literal> der Name der Klasse und <literal>$method</literal>
der Name der Methode ist die aufgerufen werden soll, übergeben werden.
</para>
<para>
<parameter>$cacheable</parameter> und <parameter>$cache_attrs</parameter> können in den meisten Fällen weggelassen werden. Konsultieren Sie <link linkend="caching.cacheable">Die Ausgabe von cachebaren Plugins Kontrollieren</link> für weitere Informationen.
</para>
2003-03-06 23:37:24 +00:00
</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>
2003-09-08 16:35:05 +00:00
<paramdef>mixed <parameter>impl</parameter></paramdef>
<paramdef>bool <parameter>cacheable</parameter></paramdef>
<paramdef>array or null <parameter>cache_attrs</parameter></paramdef>
2003-03-06 23:37:24 +00:00
</funcprototype>
</funcsynopsis>
<para>
Wird verwendet, um Template-Funktion-Plugins dynamisch zu
registrieren. Übergeben Sie dazu den Namen der Template-Funktion
und den Namen der PHP-Funktion, die die entsprechende Funktionalität bereitstellt.
2003-09-08 16:35:05 +00:00
</para>
<para>
Der Parameter <parameter>impl</parameter> kann als (a) einen Funktionnamen oder (b) einem Array der Form <literal>array(&$object, $method)</literal>,
wobei <literal>&$object</literal> eine Referenz zu einem Objekt und <literal>$method</literal> der Name der Methode die aufgerufen werden soll ist,
oder als Array der Form <literal>array(&$class, $method)</literal>, wobei <literal>$class</literal> der Name der Klasse und <literal>$method</literal>
der Name der Methode ist die aufgerufen werden soll, übergeben werden.
</para>
<para>
<parameter>$cacheable</parameter> und <parameter>$cache_attrs</parameter> können in den meisten Fällen weggelassen werden. Konsultieren Sie <link linkend="caching.cacheable">Die Ausgabe von cachebaren Plugins Kontrollieren</link> für weitere Informationen.
2003-03-06 23:37:24 +00:00
</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";
2003-09-08 16:35:05 +00:00
return strftime($format,time());
2003-03-06 23:37:24 +00:00
}
// Von nun an kö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>
2003-09-08 16:35:05 +00:00
<paramdef>mixed <parameter>impl</parameter></paramdef>
2003-03-06 23:37:24 +00:00
</funcprototype>
</funcsynopsis>
<para>
Wird verwendet, um Modifikator-Plugins dynamisch zu
registrieren. Übergeben Sie dazu den Namen der Modifikator-Funktion
und den Namen der PHP-Funktion, die die entsprechende Funktionalität
bereitstellt.
</para>
2003-09-08 16:35:05 +00:00
<para>
Der Parameter <parameter>impl</parameter> kann als (a) einen Funktionnamen oder (b) einem Array der Form <literal>array(&$object, $method)</literal>,
wobei <literal>&$object</literal> eine Referenz zu einem Objekt und <literal>$method</literal> der Name der Methode die aufgerufen werden soll ist,
oder als Array der Form <literal>array(&$class, $method)</literal>, wobei <literal>$class</literal> der Name der Klasse und <literal>$method</literal>
der Name der Methode ist die aufgerufen werden soll, übergeben werden.
</para>
2003-03-06 23:37:24 +00:00
<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önnen Sie {$var|sslash} verwenden,
// um "\"-Zeichen (Backslash) aus Zeichenketten zu entfernen. ('\\' wird zu '\',...)</programlisting>
</example>
</sect1>
2003-09-08 16:35:05 +00:00
<sect1 id="api.register.object">
<title>register_object</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>register_object</function></funcdef>
<paramdef>string <parameter>object_name</parameter></paramdef>
<paramdef>object <parameter>$object</parameter></paramdef>
<paramdef>array <parameter>allowed methods/properties</parameter></paramdef>
<paramdef>boolean <parameter>format</parameter></paramdef>
<paramdef>array <parameter>block methods</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Wird verwendet um ein Objekt zu registrieren. Konsultieren Sie den Abschnitt <link linkend="advanced.features.objects">Objekte</link>
für weitere Informationen und Beispiele.
</para>
</sect1>
2003-03-06 23:37:24 +00:00
<sect1 id="api.register.outputfilter">
<title>register_outputfilter (Ausgabefilter registrieren)</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>register_outputfilter</function></funcdef>
2003-09-08 16:35:05 +00:00
<paramdef>mixed <parameter>function</parameter></paramdef>
2003-03-06 23:37:24 +00:00
</funcprototype>
</funcsynopsis>
2003-09-08 16:35:05 +00:00
<para>
Verwenden Sie diese Funktion um dynamisch Ausgabefilter zu registrieren, welche
die Template Ausgabe verarbeiten bevor sie angezeigt wird. Konsultieren Sie
den Abschnitt über <link linkend="advanced.features.outputfilters">Ausgabefilter</link>
für mehr Informationen.
</para>
<para>
Der Parameter <parameter>function</parameter> kann als (a) einen Funktionnamen oder (b) einem Array der Form <literal>array(&$object, $method)</literal>,
wobei <literal>&$object</literal> eine Referenz zu einem Objekt und <literal>$method</literal> der Name der Methode die aufgerufen werden soll ist,
oder als Array der Form <literal>array(&$class, $method)</literal>, wobei <literal>$class</literal> der Name der Klasse und <literal>$method</literal>
der Name der Methode ist die aufgerufen werden soll, übergeben werden.
</para>
2003-03-06 23:37:24 +00:00
</sect1>
<sect1 id="api.register.postfilter">
<title>register_postfilter ('post'-Filter registrieren)</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>register_postfilter</function></funcdef>
2003-09-08 16:35:05 +00:00
<paramdef>mixed <parameter>function</parameter></paramdef>
2003-03-06 23:37:24 +00:00
</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>
2003-09-08 16:35:05 +00:00
<para>
Der Parameter <parameter>function</parameter> kann als (a) einen Funktionnamen oder (b) einem Array der Form <literal>array(&$object, $method)</literal>,
wobei <literal>&$object</literal> eine Referenz zu einem Objekt und <literal>$method</literal> der Name der Methode die aufgerufen werden soll ist,
oder als Array der Form <literal>array(&$class, $method)</literal>, wobei <literal>$class</literal> der Name der Klasse und <literal>$method</literal>
der Name der Methode ist die aufgerufen werden soll, übergeben werden.
</para>
2003-03-06 23:37:24 +00:00
</sect1>
<sect1 id="api.register.prefilter">
<title>register_prefilter ('pre'-Filter registrieren)</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>register_prefilter</function></funcdef>
2003-09-08 16:35:05 +00:00
<paramdef>mixed <parameter>function</parameter></paramdef>
2003-03-06 23:37:24 +00:00
</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
2003-09-08 16:35:05 +00:00
Abschnitt <link linkend="advanced.features.prefilters">'pre'-Filter</link>.
</para>
<para>
Der Parameter <parameter>function</parameter> kann als (a) einen Funktionnamen oder (b) einem Array der Form <literal>array(&$object, $method)</literal>,
wobei <literal>&$object</literal> eine Referenz zu einem Objekt und <literal>$method</literal> der Name der Methode die aufgerufen werden soll ist,
oder als Array der Form <literal>array(&$class, $method)</literal>, wobei <literal>$class</literal> der Name der Klasse und <literal>$method</literal>
der Name der Methode ist die aufgerufen werden soll, übergeben werden.
2003-03-06 23:37:24 +00:00
</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. Übergeben Sie dazu den Ressourcen-Namen und
das Array mit den Namen der PHP-Funktionen, die die Funktionalität implementieren.
Konsultieren Sie den Abschnitt <link linkend="template.resources">template resources</link>
für weitere Informationen zum Thema.
</para>
2003-09-08 16:35:05 +00:00
<note>
<title>Technische Bemerkung</title>
<para>
Ein Ressourcename muss mindestens 2 Zeichen lang sein. Namen mit einem (1) Zeichen
werden ignoriert und als Teil des Pfades verwenden, wie in $smarty->display('c:/path/to/index.tpl');.
</para>
</note>
<para>
Der Parameter <parameter>resource_funcs</parameter> muss aus 4 oder 5 Elementen bestehen. Wenn 4 Elemente übergeben werden,
werden diese als Ersatz Callback-Funktionen fü "source", "timestamp", "secure" und "trusted" verwendet. Mit 5 Elementen
muss der erste Parameter eine Referenz auf das Objekt oder die Klasse sein, welche die benötigten Methoden bereitstellt.
</para>
2003-03-06 23:37:24 +00:00
<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ö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üft, ob das angegebene Template existiert. Als Parameter
können entweder ein Pfad im Dateisystem oder eine Ressource ü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.
Ü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.
Ü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.
Ü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.
Ü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.
Ü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ä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ür für wie lange gecached werden sollen. Wenn sich zum Beispiel die erste Seite Ihrer Website
nur sporadisch ändert, macht es Sinn die Seite für eine
Stunde oder länger zu cachen. Wenn Sie aber eine Seite mit sich minütlich
erneuernden Wetterinformationen haben, macht es möglicherweise keinen Sinn,
die Seite ü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ä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 ähnlichen Namen
wie das Template, mit dem sie erzeugt wurden. Obwohl sie eine '.php'-Endung
aufweisen, sind sie keine ausfü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ägt der Wert 3600 Sekunden (= 1 Stunde). Nach Ablauf dieser Lebensdauer
wird der Cache neu generiert. Sie können die Lebensdauer pro Cache bestimmen indem Sie '$caching'
auf 2 setzen. Konsultieren Sie den Abschnitt über <link linkend="variable.cache.lifetime">$cache_lifetime</link>
fü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
2003-09-08 16:35:05 +00:00
// Standardwert für '$cache_lifetime' auf 5 Minuten setzen
2003-03-06 23:37:24 +00:00
$smarty->cache_lifetime = 300;
$smarty->display('index.tpl');
// '$cache_lifetime' fü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ü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 änderung überprüft.
Falls eine der Dateien seit der Erzeugung des Cache geändert wurde,
wird der Cache unverzüglich neu generiert. Dadurch ergibt sich ein
geringer Mehraufwand. Fü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ür die Fehlersuche verwendet.
Ein effizienterer Weg das Caching auszuschalten wä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 überprüft
werden, ob von einem Template eine gecachte Version vorliegt.
In einem Template, das zum Beispiel Daten aus einer Datenbank bezieht,
können Sie diese Funktion verwenden, um den Prozess zu ü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ö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 über <link linkend="language.function.insert">insert</link>
für weitere Informationen und Beispiele.
</para>
<para>
Mit der Funktion <link linkend="api.clear.all.cache">clear_all_cache()</link> können
Sie den gesamten Template-Cache lö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öschen
$smarty->clear_all_cache();
// nur Cache von 'index.tpl' löschen
$smarty->clear_cache('index.tpl');
$smarty->display('index.tpl');</programlisting>
</example>
</sect1>
<sect1 id="caching.multiple.caches">
<title>Multiple Caches für eine Seite</title>
<para>
Sie können für Aufrufe von 'display()' oder 'fetch()' auch mehrere Caches erzeugen.
Nehmen wir zum Beispiel an, der Aufruf von display('index.tpl') erzeuge für
verschieden Fälle unterschiedliche Inhalte und Sie wollen jeden dieser Inhalte
separat cachen. Um dies zu erreichen, können Sie eine 'cache_id' beim Funktionsaufruf
übergeben.
</para>
<example>
<title>'display()' eine 'cache_id' ü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 übergeben wir die Variable '$my_cache_id'
als 'cache_id' an 'display()'. Für jede einmalige 'cache_id'
wird ein eigener Cache von 'index.tpl' erzeugt. In diesem
Beispiel wurde 'article_id' per URL ü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) ü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 überlange Werte übergibt oder ein Skript benutzt, das in hohem
Tempo neue 'article_ids' übermittelt, kann dies auf dem Server zu Problemen
führen. Stellen Sie daher sicher, dass Sie alle empfangenen Werte auf
ihre Gültigkeit überprüfen und unerlaubte Sequenzen entfernen.
Sie wissen möglicherweise, dass ihre 'article_id' nur 10 Zeichen lang sein kann, nur
aus alphanumerischen Zeichen bestehen darf und in der Datenbank eingetragen
sein muss. überpü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 ü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önnen mit 'clear_cache()' den gesamten Cache einer bestimmten 'cache_id'
auf einmal löschen, wenn Sie als Parameter die 'cache_id' ü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öschen
$smarty->clear_cache(null, "sports");
$smarty->display('index.tpl', "sports");</programlisting>
</example>
<para>
Indem Sie allen dieselbe 'cache_id' übergeben, lassen sich Caches gruppieren.
</para>
</sect1>
<sect1 id="caching.groups">
<title>Cache-Gruppen</title>
<para>
Sie kö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önnen so viele
Untergruppen erstellen, wie Sie mö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ür die 'cache_id'. Wenn Sie
zum Beispiel display('themes/blue/index.tpl') aufrufen, können Sie NICHT
den ganzen Cache unter 'themes/blue' leeren. Wenn Sie dies tun möchten,
müssen Sie die Caches anhand der 'cache_id' gruppieren - zum Beispiel
display('themes/blue/index.tpl','themes|blue');
Danach können Sie alle Caches des 'blue-theme' mit clear_cache(null, 'themes|blue');
leeren.
</para>
</note>
</sect1>
2003-09-08 16:35:05 +00:00
<sect1 id="caching.cacheable">
<title>Die Ausgabe von cachebaren Plugins Kontrollieren</title>
<para>
Seit Smarty-2.6.0 kann bei der Registrierung angegeben werden ob ein Plugin
cached werden soll. Der dritte Parameter für register_block, register_compiler_function
und register_function heisst <parameter>$cacheable</parameter>, der Standardwert ist TRUE, was in Smarty vor
Version 2.6.0 üblich war.
</para>
<para>
Wenn ein Plugin mit $cacheable=false registriert wird, wird er bei jedem Besuch der Seite aufgerufen, selbst wenn die Site aus dem Cache stammt. Die Pluginfunktion verhält sich ein wenig wie <link linkend="plugins.inserts">insert</link>.
</para>
<para>
Im Gegensatz zu <link linkend="language.function.insert">{insert}</link> werden die Attribute standartmässig nicht gecached. Sie können das caching jedoch mit dem vierten Parameter <parameter>$cache_attrs</parameter> kontrollieren. <parameter>$cache_attrs</parameter> ist ein Array aller Attributnamen die gecached wertden sollen.
</para>
<example>
<title>Preventing a plugin's output from being cached</title>
<programlisting>
index.php:
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
function remaining_seconds($params, &$smarty) {
$remain = $params['endtime'] - time();
if ($remain >=0)
return $remain . " second(s)";
else
return "done";
}
$smarty->register_function('remaining', 'remaining_seconds', false, array('endtime'));
if (!$smarty->is_cached('index.tpl')) {
// objekt $obj aus datenbank dem template zuweisen
$smarty->assign_by_ref('obj', $obj);
}
$smarty->display('index.tpl');
index.tpl:
Time Remaining: {remain endtime=$obj->endtime}</programlisting>
<para>
Der Wert von $obj->endtime ändert bei jeder Anzeige der Seite, selbst wenn die Seite gecached wurde. Das Objekt $obj wird nur geladen wenn die Seite nicht gecached wurde.
</para>
</example>
<example>
<title>Verhindern dass Template Blöcke gecached werden</title>
<programlisting>
index.php:
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
function smarty_block_dynamic($param, $content, &$smarty) {
return $content;
}
$smarty->register_block('dynamic', 'smarty_block_dynamic', false);
$smarty->display('index.tpl');
index.tpl:
Page created: {"0"|date_format:"%D %H:%M:%S"}
{dynamic}
Now is: {"0"|date_format:"%D %H:%M:%S"}
... do other stuff ...
{/dynamic}</programlisting>
</example>
<para>
Um sicherzustellen dass ein Teil eines Templates nicht gecached werden soll, kann dieser Abschnitt in einen {dynamic}...{/dynamic} Block verpackt werden.
</para>
</sect1>
2003-03-06 23:37:24 +00:00
</chapter>
<chapter id="advanced.features">
<title>Advanced Features</title>
2003-09-08 16:35:05 +00:00
<sect1 id="advanced.features.objects">
<title>Objekte</title>
<para>
2003-09-10 11:29:40 +00:00
Smarty erlaubt es, auf PHP Objekt durch das Template zuzugreifen. Dafür gibt es
zwei Wege. Der erste ist, Objekte zu registrieren und wie auf eine eigene Funktion zuzugreifen.
2003-09-08 16:35:05 +00:00
Der andere Weg ist, das Objekt dem Template zuzuweisen und darauf wie auf andere Variablen
2003-09-10 11:29:40 +00:00
zuzugreifen. Die erste Methode hat eine nettere Template Syntax und ist sicherer da der Zugriff
2003-09-08 16:35:05 +00:00
auf ein registriertes Objekt mit Sicherheitseinstellungen kontrolliert werden kann. Der Nachteil
2003-09-10 11:29:40 +00:00
ist, dass registrierte Objekte nicht in Loops verwendet werden können. Welchen Weg Sie einschlagen
2003-09-08 16:35:05 +00:00
wird von Ihren Bedürfnissen definiert, die erste Methode ist jedoch zu bevorzugen.
</para>
<para>
2003-09-10 11:29:40 +00:00
Wenn die Sicherheitsfunktionen eingeschaltet sind, können keine private Methoden (solche die einen '_'-Prefix tragen)
2003-09-08 16:35:05 +00:00
aufgerufen werden. Wenn eine Methode und eine Eigeschaft mit dem gleichen Namen existieren wird die Methode
verwendet.
</para>
<para>
Sie können den Zugriff auf Methoden und Eigenschaften einschränken
indem Sie sie als Array als dritten Registrationsparameter übergeben.
</para>
<para>
Normalerweise werden Parameter welche einem Objekt via Template übergeben
werden genau so übergeben wie dies bei normalen eigenen Funktionen der Fall ist.
Das erste Objekt ist ein assoziatives Array und das zweite das Smarty Objekt selbst.
Wenn Sie die Parameter einzeln erhalten möchten können Sie den vierten
Parameter auf FALSE setzen.
</para>
<para>
2003-09-10 11:29:40 +00:00
Der optionale fünfte Parameter hat nur einen Effekt wenn
<parameter>format</parameter> = <literal>true</literal> ist und eine Liste von
2003-09-08 16:35:05 +00:00
Methoden enthält die als Block verarbeitet werden sollen.
2003-09-10 11:29:40 +00:00
Das bedeutet, dass solche Methoden ein schliessendes Tag im Template
2003-09-08 16:35:05 +00:00
enthalten müssen (<literal>{foobar->meth2}...{/foobar->meth2}</literal>)
und die Parameter zu den Funktionen die selbe Syntax haben wie block-function-plugins:
2003-09-10 11:29:40 +00:00
sie erhalten also die 4 Parameter
2003-09-08 16:35:05 +00:00
<parameter>$params</parameter>,
<parameter>$content</parameter>,
<parameter>&$smarty</parameter> und
2003-09-10 11:29:40 +00:00
<parameter>&$repeat</parameter>,
und verhalten sich auch sonst wie block-function-plugins.
2003-09-08 16:35:05 +00:00
</para>
<example>
2003-09-10 11:29:40 +00:00
<title>registierte oder zugewiesene Objekte verwenden</title>
2003-09-08 16:35:05 +00:00
<programlisting>
<?php
// das objekt
class My_Object {
function meth1($params, &$smarty_obj) {
return "meine meth1";
}
}
$myobj = new My_Object;
// objekt registrieren (referenz)
$smarty->register_object("foobar",$myobj);
// zugriff auf methoden und eigeschaften einschränken
$smarty->register_object("foobar",$myobj,array('meth1','meth2','prop1'));
// wenn wir das traditionelle parameter format verwenden wollen, übergeben wir false für den parameter format
$smarty->register_object("foobar",$myobj,null,false);
// objekte zuweisen (auch via referenz möglich)
$smarty->assign_by_ref("myobj", $myobj);
$smarty->display("index.tpl");
?>
TEMPLATE:
{* zugriff auf ein registriertes objekt *}
{foobar->meth1 p1="foo" p2=$bar}
{* ausgabe zuweisen *}
{foobar->meth1 p1="foo" p2=$bar assign="output"}
ausgabe war: {$output}
{* auf unser zugewiesenes objekt zugreiffen *}
{$myobj->meth1("foo",$bar)}</programlisting>
</example>
</sect1>
2003-03-06 23:37:24 +00:00
<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ützlich, um zum Beispiel Kommentare zu entfernen
oder um den Inhalt des Templates zu analysieren. 'pre'-Filter kö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 übergibt der Funktion als ersten Parameter den Template-Quellcode und erwartet
als Rückgabewert den bearbeiteten Quellcode.
</para>
<example>
<title>Template 'pre'-Filter verwenden</title>
<programlisting>
<?php
// fügen Sie folgende Zeilen in Ihre Applikation ein
function remove_dw_comments($tpl_source, &$smarty)
{
return preg_replace("/<!--#.*-->/U","",$tpl_source);
}
// registrieren Sie den 'pre'-Filter
$smarty->register_prefilter("remove_dw_comments");
$smarty->display("index.tpl");
?>
{* Smarty Template 'index.tpl' *}
<!--# diese Zeile wird vom 'pre'-Filter entfernt--></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ö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 übergibt der Funktion als ersten Parameter den Template-Quellcode und erwartet
als Rückgabewert den bearbeiteten Quellcode.
</para>
<example>
<title>Template 'post'-Filter verwenden</title>
<programlisting>
<?php
// fügen Sie folgende Zeilen in Ihre Applikation ein
function add_header_comment($tpl_source, &$smarty)
{
return "<?php echo \"<!-- Created by Smarty! -->\n\" ?>\n".$tpl_source;
}
// registrieren Sie den 'post'-Filter
$smarty->register_postfilter("add_header_comment");
$smarty->display("index.tpl");
?>
{* kompiliertes Smarty Template 'index.tpl' *}
<!-- Created by Smarty! -->
{* 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ö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 übergibt der Funktion als ersten Parameter die Template-Ausgabe und erwartet
als Rückgabewert die bearbeitete Ausgabe.
</para>
<example>
<title>Ausgabefilter verwenden</title>
<programlisting>
<?php
// fü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.
?></programlisting>
</example>
</sect1>
<sect1 id="section.template.cache.handler.func">
<title>Cache Handler Funktion</title>
<para>
Als Alternative zum normalen dateibasierten Caching-Mechanismus können Sie
eine eigene Cache-Handler Funktion zum lesen, schreiben und lö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
übergeben: 'read', 'write' und 'clear'. Als zweiter Parameter
wird das Smarty-Objekt übergeben, als dritter der gecachte Inhalt. Bei einem
'write' übergibt Smarty den gecachten Inhalt, bei 'read' übergibt Smarty die
Variable als Referenz und erwartet, dass Ihre Funktion die Inhalte zuweist.
Bei 'clear' können Sie eine dummy-Variable übergeben. Als vierter Parameter
wird der Template-Name übergeben (verwendet bei 'write'/'read'), als fü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>
<?php
/*
Beispiel Anwendung:
include('Smarty.class.php');
include('mysql_cache_handler.php');
$smarty = new Smarty;
$smarty->cache_handler_func = 'mysql_cache_handler';
$smarty->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->_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->_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->_trigger_error_msg("cache_handler: query failed.");
}
$return = $results;
break;
case 'clear':
// Cache Informationen löschen
if(empty($cache_id) && empty($compile_id) && empty($tpl_file)) {
// alle löschen
$results = mysql_query("delete from CACHE_PAGES");
} else {
$results = mysql_query("delete from CACHE_PAGES where CacheID='$CacheID'");
}
if(!$results) {
$smarty_obj->_trigger_error_msg("cache_handler: query failed.");
}
$return = $results;
break;
default:
// Fehler, unbekannte 'action'
$smarty_obj->_trigger_error_msg("cache_handler: unknown action \"$action\"");
$return = false;
break;
}
mysql_close($link);
return $return;
}
?></programlisting>
</example>
</sect1>
<sect1 id="template.resources">
<title>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üssen Sie den Ressourcen-Typ,
2003-09-08 16:35:05 +00:00
gefolgt von Pfad und Template-Namen angeben. Wenn kein Resourcetyp angegeben
wird, wird <link linkend="variable.default.resource.type">$default_resource_type</link>
verwendet.
2003-03-06 23:37:24 +00:00
</para>
<sect2 id="templates.from.template.dir">
<title>Templates aus dem '$template_dir'</title>
<para>
Templates aus dem '$template_dir' benötigen normalerweise keinen Ressourcen-Typ,
es wird jedoch empfohlen 'file:' zu verwenden. Ü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ö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önnen Templates aus jeder für PHP verfügbaren Datenquelle beziehen:
Datenbanken, Sockets, LDAP, usw. Dazu müssen sie nur ein
Ressource-Plugin schreiben und registrieren.
</para>
<para>
Konsultieren Sie den Abschnitt über <link linkend="plugins.resources">Ressource-Plugins</link>
für mehr Informationen über die Funktionalitäten, die ein derartiges Plugin bereitstellen muss.
</para>
<note>
<para>
Achtung: Sie können die interne <literal>file</literal> Ressource nicht
überschreiben. Es steht Ihnen jedoch frei, ein Plugin zu schreiben,
das die gewünschte Funktionalitä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, &tpl_source, &$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ü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önnen eine Funktion definieren, die aufgerufen wird,
wenn ein Template nicht aus der angegeben Ressource geladen werden konnte.
Dies ist z. B. nützlich, wenn Sie fehlende Templates on-the-fly
generieren wollen.
</para>
<example>
<title>Standard Template-Handler verwenden</title>
<programlisting>
<?php
// fügen Sie folgende Zeilen in Ihre Applikation ein
function make_template ($resource_type, $resource_name, &$template_source, &$template_timestamp, &$smarty_obj)
{
if( $resource_type == 'file' ) {
if ( ! is_readable ( $resource_name )) {
// erzeuge Template-Datei, gib Inhalte zurü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';
?></programlisting>
</example>
</sect2>
</sect1>
</chapter>
<chapter id="plugins">
<title>Smarty durch Plugins erweitern</title>
<para>
In Version 2.0 wurde die Plugin-Architektur eingeführt, welche für fast alle anpassbaren Funktionalitä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ür die Abwärtskompatibilität wurden das register_* API zur Funktions-Registrierung
beibehalten. Haben Sie früher nicht die API-Funktionen benutzt, sondern die Klassen-Variablen
<literal>$custom_funcs</literal>, <literal>$custom_mods</literal> und andere direkt
geändert, müssen Sie Ihre Skripte so anpassen, dass diese das API verwenden.
Oder sie implementieren die Funktionalitä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ähnt werden, müssen sie zu Beginn der Ausfü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>
2003-09-08 16:35:05 +00:00
Die <link linkend="variable.plugins.dir">plugins directory</link> Variable kann eine Zeichenkette,
oder ein Array mit Verzeichnisnamen sein. Um einen Plugin zu installieren können Sie ihn einfach
in einem der Verzeichnisse ablegen.
2003-03-06 23:37:24 +00:00
</para>
</sect1>
<sect1 id="plugins.naming.conventions">
<title>Namenskonvention</title>
<para>
Plugin-Dateien müssen einer klaren Namenskonvention gehorchen,
um von Smarty erkannt zu werden.
</para>
<para>
Die Plugin-Dateien mü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önnen von Smarty automatisch geladen oder
zur Laufzeit dynamisch mit den register_* API-Funktionen
registriert werden. Um registrierte Plugins wieder zu entfernen,
können die unregister_* API-Funktionen verwendet werden.
</para>
<para>
Bei Plugins, die zur Laufzeit geladen werden, müssen keine Namenskonventionen
beachtet werden.
</para>
<para>
Wenn ein Plugin auf die Funktionalität eines anderen Plugins angewiesen
ist (wie dies bei manchen Smarty Standard-Plugins der Fall ist), sollte
folgender Weg gewählt werden, um das benötigte Plugin zu laden:
</para>
<programlisting>
2003-09-08 16:35:05 +00:00
require_once $smarty->_get_plugin_filepath('function', 'html_options');</programlisting>
2003-03-06 23:37:24 +00:00
<para>
Das Smarty Objekt wird jedem Plugin immer als letzter Parameter
2003-09-08 16:35:05 +00:00
übergeben (ausser bei Variablen-Modifikatoren und bei Blücken wird
<parameter>&$repeat</parameter> nach dem Smarty Objekt übergeben um Rückwärtskompatibel zu bleiben).
2003-03-06 23:37:24 +00:00
</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 übergebenen Parameter werden in der Variable
<parameter>$params</parameter> als assoziatives Array abgelegt. Sie kö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ückzuliefern
(<function>assign</function> Funktion, zum Beispiel).
</para>
<para>
Falls die Funktion dem Template Variablen zuweisen oder
auf eine andere Smarty-Funktionalität zugreifen möchte, kann dazu das
ü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>
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* File: function.eightball.php
* Type: function
* Name: eightball
* Purpose: outputs a random magic answer
* -------------------------------------------------------------
*/
function smarty_function_eightball($params, &$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];
}
?></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>
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* File: function.assign.php
* Type: function
* Name: assign
* Purpose: assign a value to a template variable
* -------------------------------------------------------------
*/
function smarty_function_assign($params, &$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);
}
?></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ö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 übergebene Parameter ist der
Wert mit welchem er arbeiten soll. Die restlichen Parameter sind optional
und hängen von den durchzuführenden Operationen ab.
</para>
<para>
Der Modifikator muss das Resultat seiner Verarbeitung zurü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ätzlichen Parameter.
</para>
<programlisting>
<?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);
}
?></programlisting>
</example>
<para></para>
<example>
<title>Komplexes Modifikator-Plugin</title>
<programlisting>
<?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;
}
?></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}
überschrieben werden.
</para>
<para>
Ihre Funktions-Implementation wird von Smarty zweimal
aufgerufen: einmal für das öffnende und einmal
2003-09-08 16:35:05 +00:00
für das schliessende Tag. (konsultieren Sie den Abschnitt zu <literal>&$repeat</literal>
um zu erfahren wie Sie dies ändern können.)
2003-03-06 23:37:24 +00:00
</para>
<para>
Nur das Öffnungs-Tag kann Attribute enthalten. Alle so übergebenen Attribute
werden als assoziatives Array <parameter>$params</parameter> der Template-Funktion
übergeben. Sie kö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 Öffnungs-Tag stehen auch beim Aufruf für das
schliessende Tag zur Verfügung.
</para>
<para>
Der Inhalt der <parameter>$content</parameter> Variable hängt davon
ab, ob die Funktion für das öffnende Tag oder für das schliessende
Tag aufgerufen wird. Für das öffnende Tag ist der Wert <literal>null</literal>,
fü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>
2003-09-08 16:35:05 +00:00
<para>
Der Parameter <parameter>&$repeat</parameter> wird als Referenz übergeben und
kontrolliert wie oft ein Block dargestellt werden soll. Standardwert von <parameter>$repeat</parameter>
ist beim ersten Aufruf (für das öffnende Tag) <literal>true</literal>, danach immer
<literal>false</literal>.
2003-09-10 11:29:40 +00:00
Jedes Mal wenn eine Funktion für <parameter>&$repeat</parameter> TRUE zurück gibt,
2003-09-08 16:35:05 +00:00
wird der Inhalt zwischen {func} .. {/func} erneut mit dem veränderten
Inhalt als <parameter>$content</parameter> Parameter aufgerufen.
</para>
2003-03-06 23:37:24 +00:00
<para>
Wenn Sie verschachtelte Block-Funktionen haben, kö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ä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>
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* File: block.translate.php
* Type: block
* Name: translate
* Purpose: translate a block of text
* -------------------------------------------------------------
*/
function smarty_block_translate($params, $content, &$smarty)
{
2003-09-08 16:35:05 +00:00
if (isset($content)) {
2003-03-06 23:37:24 +00:00
$lang = $params['lang'];
// den $content irgendwie intelligent übersetzuen
2003-09-08 16:35:05 +00:00
return $translation;
2003-03-06 23:37:24 +00:00
}
}</programlisting>
</example>
</sect1>
<sect1 id="plugins.compiler.functions"><title>Compiler-Funktionen</title>
<para>
Compiler-Funktionen werden während der Kompilierung des Template
aufgerufen. Das ist nützlich, um PHP-Code oder zeitkritische statische
Inhalte in ein Template einzufügen. Sind eine Compiler-Funktion und
eine eigene Funktion unter dem selben Namen registriert, wird die
Compiler-Funktion ausgefü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ä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ück, der in das Template eingefü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>
<?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->_current_file . " compiled at " . date('Y-m-d H:M'). "';";
}
?></programlisting>
<para>
Diese Funktion kann aus dem Template wie folgt aufgerufen werden:
</para>
<programlisting>
{* diese Funktion wird nur zum Kompilier-Zeitpunkt ausgeführt *}
{tplheader}</programlisting>
<para>
Der resultierende PHP-Code würde ungefähr so aussehen:
</para>
<programlisting>
<php
echo 'index.tpl compiled at 2002-02-20 20:02';
?></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ü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öglicherweise bereits durch eine weiteren 'pre'-Filter
bearbeitet wurden, übergeben. Das Plugin muss den resultierenden Wert
zurü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
übergeben, der möglicherweise zuvor von anderen 'post'-Filtern
bearbeitet wurde. Das Plugin muss den veränderten Template-Code zurückgeben.
</para>
<example>
<title>'pre'-Filter Plugin</title>
<programlisting>
<?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('!<(\w+)[^>]+>!e', 'strtolower("$1")', $source);
}
?></programlisting>
</example>
<para></para>
<example>
<title>'post'-Filter Plugin</title>
<programlisting>
<?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 = "<pre>\n<?php print_r(\$this->get_template_vars()); ?>\n</pre>" . $compiled;
return $compiled;
}
?></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ü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 übergeben, welche
verarbeitet werden soll und als zweiter Parameter das Smarty-Objekt.
Das Plugin muss danach die verarbeitete Template-Ausgabe zurü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ür jeden Ressource-Typ müssen 4 Funktionen registriert werden. Jede dieser
Funktionen erhält die verlangte Ressource als ersten Parameter und das Smarty Objekt
als letzten. Die restlichen Parameter hä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 übergeben
wird und in der das Resultat gespeichert werden soll. Die Funktion
gibt <literal>true</literal> zurück, wenn der Ladevorgang erfolgreich war -
andernfalls <literal>false</literal>.
</para>
<para>
Die zweite Funktion fragt das letzte Änderungsdatum der angeforderten
Ressource (als Unix-Timestamp) ab. Der zweite Parameter ist die Variable,
welche via Referenz übergeben wird und in der das Resultat gespeichert werden soll.
Gibt <literal>true</literal> zurück, wenn das Änderungsdatum ermittelt
werden konnte und <literal>false</literal> wenn nicht.
</para>
<para>
Die dritte Funktion gibt <literal>true</literal> oder <literal>false</literal>
zurück, je nachdem ob die angeforderte Ressource als sicher bezeichnet wird
oder nicht. Diese Funktion wird nur fü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ück, je nachdem ob die angeforderte Ressource als vertrauenswü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 ü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>
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* File: resource.db.php
* Type: resource
* Name: db
* Purpose: Fetches templates from a database
* -------------------------------------------------------------
*/
function smarty_resource_db_source($tpl_name, &$tpl_source, &$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, &$tpl_timestamp, &$smarty)
{
// Datenbankabfragen durchfü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, &$smarty)
{
// angenommen alle Templates seien sicher...
return true;
}
function smarty_resource_db_trusted($tpl_name, &$smarty)
{
// wird für Templates nicht verwendet
}
?></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
übergeben, die im Insert-Tag notiert wurden. Sie können
auf diese Werte entweder direkt mit <varname>$params['start']</varname> zugreifen
oder sie mit <varname>extract($params)</varname> importieren.
</para>
<para>
Als Rückgabewert muss das Resultat der Ausführung geliefert werden,
das danach den Platz des <command>insert</command>-Tags im Template einnimmt.
</para>
<example>
<title>Insert-Plugin</title>
<programlisting>
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* File: insert.time.php
* Type: time
* Name: time
* Purpose: Inserts current date/time according to format
* -------------------------------------------------------------
*/
function smarty_insert_time($params, &$smarty)
{
if (empty($params['format'])) {
$smarty->trigger_error("insert time: missing 'format' parameter");
return;
}
$datetime = strftime($params['format']);
return $datetime;
}
?></programlisting>
</example>
</sect1>
</chapter>
</part>
