Smarty für ProgrammiererKonstantenSMARTY_DIR
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.
SMARTY_DIR
// Pfad zum Smarty Verzeichnis setzen
define("SMARTY_DIR","/usr/local/lib/php/Smarty/");
require_once(SMARTY_DIR."Smarty.class.php");Variablen$template_dir
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.
Technische Bemerkung
Dieses Verzeichnis sollte ausserhalb der DocumentRoot
des Webservers liegen.
$compile_dir
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.
Technische Bemerkung
Diese Einstellung kann als relativer oder als absoluter Pfad
angegeben werden. 'include_path' wird nicht verwendet.
Technische Bemerkung
Dieses Verzeichnis sollte ausserhalb der DocumentRoot
des Webservers liegen.
$config_dir
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.
Technische Bemerkung
Dieses Verzeichnis sollte ausserhalb der DocumentRoot
des Webservers liegen.
$plugins_dir
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'.
Technische Bemerkung
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.
$debugging
Aktiviert die Debugging Konsole.
Die Konsole besteht aus einem Javascript-Fenster, welches Informationen zum
momentan geladenen Template und den zugewiesenen Variablen enthält.
$debug_tpl
Definiert den Namen des für die Debugging Konsole verwendeten Template. Normalerweise
lautet er 'debug.tpl' und befindet sich im SMARTY_DIR Verzeichnis.
$debugging_ctrl
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.
$global_assign
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.
Technische Bemerkung
Server-Variablen können über die '$smarty'-Variable
erreicht werden, zum Beispiel: {$smarty.server.SCRIPT_NAME}.
Konsultieren sie den Abschnitt zu $smarty
für weiterführende Informationen.
$undefined
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.
$autoload_filters
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:
$smarty->autoload_filters = array('pre' => array('trim', 'stamp'),
'output' => array('convert'));
$compile_check
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 $force_compile
und clear_compiled_tpl.
$force_compile
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.
$caching
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: is_cached.
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.
$cache_dir
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.
Technische Bemerkung
Die Angabe muss entweder relativ oder absolut angegeben werden. 'include_path'
wird nicht verwendet.
Technische Bemerkung
Es wird empfohlen ein Verzeichnis ausserhalb der DocumentRoot zu verwenden.
$cache_lifetime
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 $caching
auf 'false' zu setzen).
Wenn $force_compile
gesetzt ist, wird der Cache immer neu generiert (was einem Ausschalten
von caching gleichkommt). Mit der clear_all_cache()
Funktion können Sie alle Cache-Dateien auf einmal entfernen. Mit der
clear_cache() Funktion können Sie
einzelne Cache-Dateien (oder Gruppen) entfernen.
Technische Bemerkung
Falls Sie bestimmten Templates eine eigene Cache-Lifetime geben wollen,
können Sie dies tun indem Sie $caching
auf 2 stellen und '$cache_lifetime' einen einmaligen Wert zuweisen, bevor Sie
'display()' oder 'fetch()' aufrufen.
$cache_handler_func
Sie können auch eine eigene Cache-Handler Funktion definieren.
Siehe Abschnitt zur custom cache handler Funktion.
$cache_modified_check
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 insert
Tags enthalten.
$default_template_handler_func
Diese Funktion wird aufgerufen, wenn ein Template nicht aus der
vorgegebenen Quelle geladen werden kann.
$php_handling
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 {php}{/php}
Tags steht.
SMARTY_PHP_PASSTHRU - Smarty gibt die Tags aus.SMARTY_PHP_QUOTE - Smarty maskiert die Tags als HTML-Entities.SMARTY_PHP_REMOVE - Smarty entfernt die Tags.SMARTY_PHP_ALLOW - Smarty führt den Code als PHP-Code aus.
ACHTUNG: Es wird davon abgeraten, PHP-Code in Templates einzubetten.
Bitte verwenden Sie stattdessen custom functions
oder Variablen-Modifikatoren.
$security
'$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):
Wenn '$php_handling' auf SMARTY_PHP_ALLOW geschaltet ist, wird der Wert auf SMARTY_PHP_PASSTHRU geändert.Ausser den in '$security_settings' definierten, sind keine Funktionen in IF-Statements aufrufbar.Templates können nur aus den im '$secure_dir'-Array definierten Verzeichnissen geladen werden.'fetch()' kann nur verwendet werden um Dateien aus '$secure_dir' zu laden.{php}{/php}-Tags sind nicht erlaubt.Ausser den in '$security_settings' definierten, sind keine PHP-Funktionen direkt als Variablen-Modifikatoren aufrufbar.$secure_dir
Definiert die als 'sicher' geltenden Verzeichnisse als Array.
{include} und {fetch} verwenden diese Verzeichnisse, wenn '$security'
eingeschaltet ist.
$security_settings
Wird verwendet um spezifische Sicherheits-Einstellungen zu
ändern, wenn '$security' eingeschaltet ist.
PHP_HANDLING - true/false. Wenn auf 'true' gesetzt wird '$php_handling' ignoriert.IF_FUNCS - Ist ein Array aller erlaubter Funktionen in IF-Statements.INCLUDE_ANY - true/false. Wenn 'true', kann jedes Template geladen werden, auch ausserhalb der '$secure_dir'-Liste.PHP_TAGS - true/false. Wenn 'true', sind keine {php}{/php}-Tags erlaubt.MODIFIER_FUNCS - Ist ein Array aller Funktionen die als Variablen-Modifikatoren verwendet werden dürfen.$trusted_dir
'$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 {include_php} aufruft,
abgelegt werden.
$left_delimiter
Das zu verwendende linke Trennzeichen der Template-Sprache.
Normalerweise '{'.
$right_delimiter
Das zu verwendende rechte Trennzeichen der Template-Sprache.
Normalerweise '}'.
$show_info_header
Gibt am Anfang der HTML-Seite die Smarty Version und das Kompilier-Datum des Templates
als Kommentar aus. Normalerweise 'false'.
$show_info_include
Gibt am Anfang und am Ende jedes eingebundenen Templates einen HTML-Kommentar aus.
Normalerweise 'false'.
$compiler_class
Definiert den Namen der Compiler-Klasse, die Smarty zum kompilieren
der Templates verwenden soll. Normalerweise 'Smarty_Compiler'. Nur
für fortgeschrittene Anwender.
$request_vars_order
Die Reihenfolge in welcher die Request-Variblen zugewiesen werden.
Verhält sich wie 'variables_order' in der php.ini.
$compile_id
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.
$use_sub_dirs
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.
$default_modifiers
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
Behandlung auszuschliessen, können Sie ihr den Modifikator 'nodefaults' übergeben.
Zum Beispiel: {$var|nodefaults}.
Methodenappend (anhängen)void appendmixed varvoid appendstring varnamemixed var
Wird verwendet, um an Template-Variablen weitere Daten anzuhängen. Sie
können entweder ein Namen/Wert-Paar oder assoziative Arrays,
die mehrere Namen/Wert-Paare enthalten, übergeben.
append (anhängen)
// Namen/Wert-Paare übergeben
$smarty->append("Name","Fred");
$smarty->append("Address",$address);
// assoziatives Array übergeben
$smarty->append(array("city" => "Lincoln","state" => "Nebraska"));append_by_ref (via Referenz anhängen)void append_by_refstring varnamemixed var
Wird verwendet, um an Template-Variablen Werte via Referenz (pass by reference) anstatt via Kopie
anzuhängen. Konsultieren Sie das PHP-Manual zum Thema 'variable referencing'
für weitere Erklärungen.
Technische Bemerkung
'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.
append_by_ref (via Referenz anhängen)
// Namen/Wert-Paare übergeben
$smarty->append_by_ref("Name",$myname);
$smarty->append_by_ref("Address",$address);assign (zuweisen)void assignmixed varvoid assignstring varnamemixed var
Wird verwendet, um einem Template Werte zuzuweisen. Sie können
entweder Namen/Wert-Paare oder ein assoziatives Array
mit Namen/Wert-Paaren übergeben.
assign
// 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"));assign_by_ref (via Referenz zuweisen)void assign_by_refstring varnamemixed var
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.
Technical Note
'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.
assign_by_ref (via Referenz zuweisen)
// Namen/Wert-Paare übergeben
$smarty->assign_by_ref("Name",$myname);
$smarty->assign_by_ref("Address",$address);clear_all_assign (alle Zuweisungen löschen)void clear_all_assign
Löscht die Werte aller zugewiesenen Variablen.
clear_all_assign (alle Zuweisungen löschen)
// lösche alle zugewiesenen Variablen
$smarty->clear_all_assign();clear_all_cache (Cache vollständig leeren)void clear_all_cacheint expire time
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.
clear_all_cache (Cache vollständig leeren)
// leere den gesamten cache
$smarty->clear_all_cache();clear_assign (lösche Zuweisung)void clear_assignstring var
Löscht den Wert einer oder mehrerer (übergabe als Array) zugewiesener Variablen.
clear_assign (lösche Zuweisung)
// lösche eine einzelne Variable
$smarty->clear_assign("Name");
// lösche mehrere Variablen
$smarty->clear_assign(array("Name","Address","Zip"));clear_cache (leere Cache)void clear_cachestring templatestring cache idstring compile idint expire time
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
caching. Als vierten Parameter können Sie
ein Mindestalter in Sekunden angeben, das ein Cache aufweisen muss,
bevor er gelöscht wird.
clear_cache (Cache leeren)
// 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");clear_compiled_tpl (kompiliertes Template löschen)void clear_compiled_tplstring tpl_file
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.
clear_compiled_tpl (kompiliertes Template löschen)
// ein bestimmtes kompiliertes Template löschen
$smarty->clear_compiled_tpl("index.tpl");
// das gesamte Kompilier-Verzeichnis löschen
$smarty->clear_compiled_tpl();display (ausgeben)void displaystring templatestring cache_idstring compile_id
Gibt ein Template aus. Sie müssen einen gültigen
Template Ressourcen-Typ
inklusive Pfad angeben. Als optionalen zweiten Parameter können
Sie eine 'cache_id' übergeben. Konsultieren
Sie den Abschnitt über caching für weitere Informationen.
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 $compile_id
auch einmalig setzen, anstatt sie bei jedem Aufruf von 'display()' zu übergeben.
display (ausgeben)
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");
Verwenden Sie die Syntax von template resources
um Dateien ausserhalb von '$template_dir' zu verwenden.
Beispiele von Template-Ressourcen für 'display()'
// 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");fetchstring fetchstring templatestring cache_idstring compile_id
Gibt die Ausgabe des Template zurück, anstatt es direkt anzuzeigen. Übergeben Sie
einen gültigen Template Ressource-Typ
und -Pfad. Als optionaler zweiter Parameter kann eine 'cache_id' übergeben werden.
Bitte konsultieren Sie den Abschnitt über caching
für weitere Informationen.
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 $compile_id
auch einmalig setzen, anstatt sie bei jedem Aufruf von 'fetch()' zu übergeben.
fetch
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;get_template_vars (Template-Variablen extrahieren)array get_template_vars
Gibt ein Array der zugewiesenen Template-Variablen zurück.
get_template_vars (Template-Variablen extrahieren)
// alle zugewiesenen Template-Variablen extrahieren
$tpl_vars = $smarty->get_template_vars();
// Anschauen
var_dump($tpl_vars);is_cached (gecachte Version existiert)void is_cachedstring template[string cache_id]
Gibt 'true' zurück, wenn ein gültiger Cache für das angegebene Template existiert.
Dies funktioniert nur, wenn caching eingeschaltet ist.
is_cached
$smarty->caching = true;
if(!$smarty->is_cached("index.tpl")) {
// Datenbank-Abfragen, Variablen zuweisen...
}
$smarty->display("index.tpl");
Als optionalen zweiten Parameter können Sie die 'cache_id' übergeben,
falls Sie mehrere Caches für ein Template verwenden.
'is_cached' bei mehreren Template-Caches
$smarty->caching = true;
if(!$smarty->is_cached("index.tpl", "FrontPage")) {
// Datenbank Abfragen, Variablen zuweisen...
}
$smarty->display("index.tpl","FrontPage");load_filter (Filter laden)void load_filterstring typestring name
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'.
Filter-Plugins laden
$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'register_block (Block-Funktion registrieren)void register_blockstring namestring impl
Wird verwendet, um Block-Funktion-Plugins dynamisch zu registrieren.
Übergeben Sie dazu den Namen der Block-Funktion und den Namen der
PHP-Funktion, die die entsprechende Funktionalität bereitstellt.
register_block (Block-Funktion registrieren)
/* PHP */
$smarty->register_block("translate", "do_translation");
function do_translation ($params, $content, &$smarty) {
if ($content) {
$lang = $params['lang'];
// übersetze den Inhalt von '$content'
echo $translation;
}
}
{* template *}
{translate lang="br"}
Hello, world!
{/translate}register_compiler_function (Compiler-Funktion registrieren)void register_compiler_functionstring namestring impl
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.
register_function (Funktion registrieren)void register_functionstring namestring impl
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.
register_function (Funktion registrieren)
$smarty->register_function("date_now", "print_current_date");
function print_current_date ($params) {
extract($params);
if(empty($format))
$format="%b %e, %Y";
echo strftime($format,time());
}
// Von nun an können Sie {date_now} verwenden, um das aktuelle Datum auszugeben.
// Oder {date_now format="%Y/%m/%d"}, wenn Sie es formatieren wollen.register_modifier (Modifikator-Plugin registrieren)void register_modifierstring namestring impl
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.
register_modifier (Modifikator-Plugin registrieren)
// 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 '\',...)register_outputfilter (Ausgabefilter registrieren)void register_outputfilterstring function_name
Wird verwendet, um Ausgabefilter dynamisch zu registrieren.
Ausgabefilter verändern die Ausgabe,
bevor sie angezeigt wird. Konsultieren Sie dazu den
Abschnitt template output filters
register_postfilter ('post'-Filter registrieren)void register_postfilterstring function_name
Wird verwendet, um 'post'-Filter dynamisch zu registrieren. 'post'-Filter werden
auf das kompilierte Template angewendet. Konsultieren Sie dazu den
Abschnitt template postfilters.
register_prefilter ('pre'-Filter registrieren)void register_prefilterstring function_name
Wird verwendet, um 'pre'-Filter dynamisch zu registrieren. 'pre'-Filter werden
vor der Kompilierung auf das Template angewendet. Konsultieren Sie dazu den
Abschnitt template prefilters.
register_resource (Ressource registrieren)void register_resourcestring namearray resource_funcs
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 template resources
für weitere Informationen zum Thema.
register_resource (Ressource registrieren)
$smarty->register_resource("db", array("db_get_template",
"db_get_timestamp",
"db_get_secure",
"db_get_trusted"));trigger_error (Fehler auslösen)void trigger_errorstring error_msg[int level]
Wird verwendet, um eine Fehlermeldung via Smarty auszugeben.
Der level-Parameter kann alle
Werte der 'trigger_error()'-PHP-Funktion haben,
zum Beispiel E_USER_NOTICE, E_USER_WARNING, usw.
Voreingestellt ist E_USER_WARNING.
template_exists (Template existiert)bool template_existsstring template
Diese Funktion prüft, ob das angegebene Template existiert. Als Parameter
können entweder ein Pfad im Dateisystem oder eine Ressource übergeben werden.
unregister_block (Block-Funktion deaktivieren)void unregister_blockstring name
Wird verwendet, um registrierte Block-Funktionen auszuschalten.
Übergeben Sie dazu den Namen der Block-Funktion.
unregister_compiler_function (Compiler-Funktion deaktivieren)void unregister_compiler_functionstring name
Wird verwendet, um registrierte Compiler-Funktionen auszuschalten.
Übergeben Sie dazu den Funktionsnamen der Compiler-Funktion.
unregister_function (Template-Funktion deaktivieren)void unregister_functionstring name
Wird verwendet, um registrierte Template-Funktionen auszuschalten.
Übergeben Sie dazu den Namen der Template-Funktion.
unregister_function
// Template-Designer sollen keinen Zugriff auf das Dateisystem haben
$smarty->unregister_function("fetch");unregister_modifier (Modifikator deaktivieren)void unregister_modifierstring name
Wird verwendet, um registrierte Variablen-Modifikatoren auszuschalten.
Übergeben Sie dazu den Modifikator-Namen.
unregister_modifier
// Verhindern, dass Template-Designer 'strip_tags' anwenden
$smarty->unregister_modifier("strip_tags");unregister_outputfilter (Ausgabefilter deaktivieren)void unregister_outputfilterstring function_name
Wird verwendet, um registrierte Ausgabefilter auszuschalten.
unregister_postfilter ('post'-Filter deaktivieren)void unregister_postfilterstring function_name
Wird verwendet, um registrierte 'post'-Filter auszuschalten.
unregister_prefilter ('pre'-Filter deaktiviern)void unregister_prefilterstring function_name
Wird verwendet, um registrierte 'pre'-Filter auszuschalten.
unregister_resource (Ressource deaktivieren)void unregister_resourcestring name
Wird verwendet, um registrierte Ressourcen auszuschalten.
Übergeben Sie dazu den Namen der Ressource.
unregister_resource (Ressource deaktivieren)
$smarty->unregister_resource("db");Caching
Caching wird verwendet, um display() oder
fetch() 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.
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.
Caching einrichten
Als erstes muss das Caching eingeschaltet werden. Dies erreicht man, indem
$caching auf 'true' (oder 1) gesetzt wird.
Caching einschalten
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
$smarty->display('index.tpl');
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 $cache_dir schreiben
(als gecachte Kopie). Beim nächsten Aufruf von display('index.tpl') wird die
gecachte Kopie verwendet.
Technische Bemerkung
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!
Jede gecachte Seite hat eine Lebensdauer, die von $cache_lifetime
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 $cache_lifetime
für weitere Informationen.
'$cache_lifetime' pro Cache einstellen
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = 2; // Lebensdauer ist pro Cache
// Standardwert für '$cache_lifetime' auf 15 Minuten setzen
$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');
Wenn $compile_check 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.
'$compile_check' einschalten
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
$smarty->compile_check = true;
$smarty->display('index.tpl');
Wenn $force_compile 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,
$caching auf 'false' (oder 0) zu setzen.
Mit der Funktion is_cached() 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.
is_cached() verwenden
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');
Mit der insert 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 insert
für weitere Informationen und Beispiele.
Mit der Funktion clear_all_cache() können
Sie den gesamten Template-Cache löschen. Mit clear_cache()
einzelne Templates oder Template-Gruppen.
Cache leeren
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');Multiple Caches für eine Seite
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.
'display()' eine 'cache_id' übergeben
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
$my_cache_id = $_GET['article_id'];
$smarty->display('index.tpl', $my_cache_id);
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.
Technische Bemerkung
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!
Denken Sie daran, Aufrufen von is_cached()
und clear_cache() als zweiten Parameter
die 'cache_id' zu übergeben.
'is_cached()' mit 'cache_id' aufrufen
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);
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.
Cache einer bestimmten 'cache_id' leeren
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");
Indem Sie allen dieselbe 'cache_id' übergeben, lassen sich Caches gruppieren.
Cache-Gruppen
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.
'cache_id'-Gruppen
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");Technische Bemerkung
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.
Advanced Features'pre'-Filter
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 registrieren,
aus dem Plugin-Verzeichnis mit load_filter() laden
oder $autoload_filters verwenden.
Smarty übergibt der Funktion als ersten Parameter den Template-Quellcode und erwartet
als Rückgabewert den bearbeiteten Quellcode.
Template 'pre'-Filter verwenden
<?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-->'post'-Filter
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 registrieren,
aus dem Plugin-Verzeichnis mit load_filter() laden
oder $autoload_filters verwenden.
Smarty übergibt der Funktion als ersten Parameter den Template-Quellcode und erwartet
als Rückgabewert den bearbeiteten Quellcode.
Template 'post'-Filter verwenden
<?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... *}Ausgabefilter
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.
Ausgabefilter können auf verschiede Arten
geladen werden. Man kann sie registrieren,
aus dem Plugin-Verzeichnis mit load_filter() laden
oder $autoload_filters verwenden.
Smarty übergibt der Funktion als ersten Parameter die Template-Ausgabe und erwartet
als Rückgabewert die bearbeitete Ausgabe.
Ausgabefilter verwenden
<?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.
?>Cache Handler Funktion
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.
Schreiben Sie eine Funktion in Ihrer Applikation, die Smarty als
Cache-Handler verwenden soll und weisen Sie deren Name der Variable
$cache_handler_func 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).
Beispiel mit einer MySQL Datenbank als Datenquelle
<?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;
}
?>Ressourcen
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,
gefolgt von Pfad und Template-Namen angeben.
Templates aus dem '$template_dir'
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.
Templates aus '$template_dir' verwenden
// 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 *}Templates aus beliebigen Verzeichnissen
Templates ausserhalb von '$template_dir' benötigen den 'file:' Ressourcen-Typ,
gefolgt von absolutem Pfadnamen und Templatenamen.
Templates aus beliebigen Verzeichnissen benutzen
// 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"}Windows Dateipfade
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.
Templates aus Windows Dateipfaden verwenden
// 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"}Templates aus anderen Quellen
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.
Konsultieren Sie den Abschnitt über Ressource-Plugins
für mehr Informationen über die Funktionalitäten, die ein derartiges Plugin bereitstellen muss.
Achtung: Sie können die interne file 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.
Eigene Quellen verwenden
// 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"}Standard Template-Handler
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.
Standard Template-Handler verwenden
<?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';
?>Smarty durch Plugins erweitern
In Version 2.0 wurde die Plugin-Architektur eingeführt, welche für fast alle anpassbaren Funktionalitäten
verwendet wird. Unter anderem:
FunktionenModifikatorenBlock-FunktionenCompiler-Funktionen'pre'-Filter'post'-FilterAusgabefilterRessourcenInserts
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
$custom_funcs, $custom_mods 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.
Wie Plugins funktionieren
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.
'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.
Aus Performancegründen existiert nur ein Plugin-Verzeichnis. Um ein Plugin
zu installieren, speichern Sie es einfach in diesem Verzeichnis. Smarty wird
es danach automatisch erkennen.
Namenskonvention
Plugin-Dateien müssen einer klaren Namenskonvention gehorchen,
um von Smarty erkannt zu werden.
Die Plugin-Dateien müssen wie folgt benannt werden:
type.name.php
Wobei Typ einen der folgenden Werte haben kann:
functionmodifierblockcompilerprefilterpostfilteroutputfilterresourceinsert
und Name ein erlaubter Identifikator (bestehend
aus Buchstaben, Zahlen und Unterstrichen) ist.
Ein paar Beispiele: function.html_select_date.php,
resource.db.php,
modifier.spacify.php.
Die Plugin-Funktion innerhalb das Plugin-Datei muss wie folgt benannt werden:
smarty_type_name
type und name haben die selbe Bedeutung wie bei den Plugin-Dateien.
Smarty gibt Fehlermeldungen aus, falls ein aufgerufenes Plugin nicht existiert,
oder eine Datei mit falscher Namensgebung im Verzeichnis gefunden wurde.
Plugins schreiben
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.
Bei Plugins, die zur Laufzeit geladen werden, müssen keine Namenskonventionen
beachtet werden.
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:
require_once SMARTY_DIR . 'plugins/function.html_options.php';
Das Smarty Objekt wird jedem Plugin immer als letzter Parameter
übergeben (ausser bei Variablen-Modifikatoren).
Template-Funktionenvoid smarty_function_namearray $paramsobject &$smarty
Alle einer Funktion übergebenen Parameter werden in der Variable
$params als assoziatives Array abgelegt. Sie können
auf diese Werte entweder direkt mit $params['start'] zugreifen
oder sie mit extract($params) in die Symbol-Tabelle importieren.
Die Ausgabe der Funktion wird verwendet, um das Funktions-Tag im Template
(fetch Funktion, zum Beispiel) zu ersetzen.
Alternativ kann sie auch etwas tun, ohne eine Ausgabe zurückzuliefern
(assign Funktion, zum Beispiel).
Falls die Funktion dem Template Variablen zuweisen oder
auf eine andere Smarty-Funktionalität zugreifen möchte, kann dazu das
übergebene $smarty Objekt verwendet werden.
Sehen Sie dazu:
register_function(),
unregister_function().
Funktionsplugin mit Ausgabe
<?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];
}
?>
Es kann im Template wie folgt angewendet werden:
Question: Will we ever have time travel?
Answer: {eightball}.Funktionsplugin ohne Ausgabe
<?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);
}
?>Variablen-Modifikatoren
Variablen-Modifikatoren sind kleine Funktionen, die auf eine Variable angewendet
werden, bevor sie ausgegeben oder weiterverwendet wird. Variablen-Modifikatoren können
aneinadergereiht werden.
mixed smarty_modifier_namemixed $value[mixed $param1, ...]
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.
Der Modifikator muss das Resultat seiner Verarbeitung zurückgeben.
Sehen Sie dazu:
register_modifier(),
unregister_modifier().
Einfaches Modifikator-Plugin
Dieses Plugin dient als Alias einer PHP-Funktion und erwartet keine
zusätzlichen Parameter.
<?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);
}
?>Komplexes Modifikator-Plugin
<?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;
}
?>Block-Funktionenvoid smarty_function_namearray $paramsmixed $contentobject &$smarty
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.
Ihre Funktions-Implementation wird von Smarty zweimal
aufgerufen: einmal für das öffnende und einmal
für das schliessende Tag.
Nur das Öffnungs-Tag kann Attribute enthalten. Alle so übergebenen Attribute
werden als assoziatives Array $params der Template-Funktion
übergeben. Sie können auf die Werte entweder direkt mit $params['start']
zugreifen oder sie mit extract($params) in die Symbol-Tabelle
importieren. Die Attribute aus dem Öffnungs-Tag stehen auch beim Aufruf für das
schliessende Tag zur Verfügung.
Der Inhalt der $content 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 null,
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.
Wenn Sie verschachtelte Block-Funktionen haben, können Sie
die Eltern-Block-Funktion mit der $smarty->_tag_stack Variable
herausfinden. Lassen Sie sich ihren Inhalt mit 'var_dump()' ausgeben.
Die Struktur sollte selbsterklärend sein.
Sehen Sie dazu:
register_block(),
unregister_block().
Block-Funktionen
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* File: block.translate.php
* Type: block
* Name: translate
* Purpose: translate a block of text
* -------------------------------------------------------------
*/
function smarty_block_translate($params, $content, &$smarty)
{
if ($content) {
$lang = $params['lang'];
// den $content irgendwie intelligent übersetzuen
echo $translation;
}
}Compiler-Funktionen
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.
mixed smarty_compiler_namestring $tag_argobject &$smarty
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.
Sehen Sie dazu:
register_compiler_function(),
unregister_compiler_function().
Einfache Compiler-Funktionen
<?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'). "';";
}
?>
Diese Funktion kann aus dem Template wie folgt aufgerufen werden:
{* diese Funktion wird nur zum Kompilier-Zeitpunkt ausgeführt *}
{tplheader}
Der resultierende PHP-Code würde ungefähr so aussehen:
<php
echo 'index.tpl compiled at 2002-02-20 20:02';
?>'pre'/'post'-Filter
'pre'-Filter und 'post'-Filter folgen demselben Konzept. Der
einzige Unterschied ist der Zeitpunkt der Ausführung.
string smarty_prefilter_namestring $sourceobject &$smarty
'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.
string smarty_postfilter_namestring $compiledobject &$smarty
'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.
'pre'-Filter Plugin
<?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);
}
?>'post'-Filter Plugin
<?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;
}
?>Ausgabefilter
Ausgabefilter werden auf das Template direkt vor der Ausgabe angewendet,
nachdem es geladen und ausgeführt wurde.
string smarty_outputfilter_namestring $template_outputobject &$smarty
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.
Ausgabefilter Plugin
/*
* 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);
}
Ressourcen
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.
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.
bool smarty_resource_name_sourcestring $rsrc_namestring &$sourceobject &$smartybool smarty_resource_name_timestampstring $rsrc_nameint &$timestampobject &$smartybool smarty_resource_name_securestring $rsrc_nameobject &$smartybool smarty_resource_name_trustedstring $rsrc_nameobject &$smarty
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 true zurück, wenn der Ladevorgang erfolgreich war -
andernfalls false.
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 true zurück, wenn das Änderungsdatum ermittelt
werden konnte und false wenn nicht.
Die dritte Funktion gibt true oder false
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.
Die vierte Funktion gibt true oder false
zurück, je nachdem ob die angeforderte Ressource als vertrauenswürdig angesehen wird
oder nicht. Diese Funktion wird nur verwendet, wenn PHP-Skripte via include_php
oder insert eingebunden werden sollen und ein 'src' Attribut übergeben wurde.
Die Funktion sollte aber in jedem Fall definiert werden.
Sehen Sie dazu:
register_resource(),
unregister_resource().
Ressourcen Plugin
<?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
}
?>Inserts
Insert-Plugins werden verwendet, um Funktionen zu implementieren, die
via insert aufgerufen werden.
string smarty_insert_namearray $paramsobject &$smarty
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 $params['start'] zugreifen
oder sie mit extract($params) importieren.
Als Rückgabewert muss das Resultat der Ausführung geliefert werden,
das danach den Platz des insert-Tags im Template einnimmt.
Insert-Plugin
<?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;
}
?>