Smarty und die Template-Sprache: die Unterschiede im Detail #

Die Tabelle nebeneinander zeigt, wo die beiden Sprachen übereinstimmen. Diese Seite nimmt sich die Stellen vor, an denen sie es nicht tun, erklärt jede aus dem Code der Template-Engine und zeigt, was auf einer Entwicklungsinstallation geschieht, wenn eine Gewohnheit aus Smarty auf die Template-Sprache trifft.

Exponential führt Smarty-Templates selbst aus: Ein Design kann Smarty-5-Templates (.stpl) neben seinen .tpl-Templates enthalten, mit jedem Operator, jeder Fetch-Funktion, jeder Template-Funktion, jeder Override-Regel und jedem Cache des Template-Systems. Wenn Sie lieber weiter Smarty schreiben, lesen Sie Von .tpl zu .stpl umziehen und (Englisch) Smarty templates (.stpl) next to .tpl; die Konverter wandeln auch in beide Richtungen um.

Inhalt #

1. Keine Arithmetik in Infixschreibweise
2. Keine Vergleiche in Infixschreibweise
3. Operatoren statt Symbole
4. Keine automatische Maskierung
5. Unbekannte Operatoren reichen ihre Eingabe durch
6. def und set sind streng
7. Klammern in CSS und JavaScript
8. Kein PHP in Templates
9. Operatoren und Funktionen sind registrierte PHP-Klassen
10. Daten kommen aus fetch, und Werte sind Objekte
11. Overrides statt Vererbung
12. Namensräume
13. Leerraum um Tags
14. Verwandte Seiten

Keine Arithmetik in Infixschreibweise #

Der Ausdrucksparser (parseVariableTag() in lib/eztemplate/classes/eztemplateelementparser.php) kennt Werte, Variablen, Zugriffe auf Attribute (. und [ ]), Operatoren (name( oder |name) und sonst nichts. Ein + gehört nicht zur Sprache. Er liest die Zahl 1, findet Zeichen, mit denen er nichts anfangen kann, protokolliert einen Parserfehler und gibt aus, was er hatte:

[{1+2}]

Ausgabe:

[1]

Von der Template-Engine protokolliert:

ERROR : parser error @ tl-diff/01-no-infix-arithmetic.tpl:1[2]
Extra characters found in expression, they will be ignored.
+2' (1)

Keine Vergleiche in Infixschreibweise #

Dasselbe gilt für >, <, ==, && und ||. In einem {if} hört der Bedingungsparser nach $a auf, der Rest wird als ungültig gemeldet, und die tatsächlich geprüfte Bedingung ist nur $a. Mit $a = 0 ist sie falsch, also gibt das Template not greater aus, aber nur zufällig: Mit $a = 1 würde dasselbe Tag greater ausgeben, obwohl 1 nicht größer als 1 ist.

{def $a = 0}
[{if $a > 1}greater{else}not greater{/if}]

Ausgabe:

[not greater]

Von der Template-Engine protokolliert:

ERROR : parser error @ tl-diff/02-no-infix-comparison.tpl:2[7]
Invalid parameter characters in function 'if': '> 1'

Operatoren statt Symbole #

Jede Berechnung und jeder Vergleich ist ein Operator, aufgerufen oder über die Pipe: sum, sub, mul, div, mod, inc, dec; eq, ne, gt, ge, lt, le; and, or, not. Sie lassen sich beliebig verschachteln:

{def $a = 0}
[{sum( 1, 2 )}] [{1|sum( 2 )}] [{mul( 3, 4 )}] [{10|sub( 4 )}]
[{if $a|gt( 1 )}greater{else}not greater{/if}]
[{if and( $a|ge( 0 ), $a|lt( 10 ), not( $a|eq( 5 ) ) )}in range{/if}]

Ausgabe:

[3] [3] [12] [6]
[not greater]
[in range]

Keine automatische Maskierung #

Die Engine maskiert Ausgaben nie. Was eine Variable enthält, wird so geschrieben, wie es ist; Text aus Inhalten, URLs oder Anfrageparametern muss also dort, wo er ausgegeben wird, durch wash (oder einen anderen Maskierungsoperator) laufen:

{def $text = '<script>alert(1)</script> & "quotes"'}
raw:    {$text}
washed: {$text|wash}

Ausgabe:

raw:    <script>alert(1)</script> & "quotes"
washed: &lt;script&gt;alert(1)&lt;/script&gt; &amp; &quot;quotes&quot;

Attribute von Inhaltsobjekten, die bereits HTML sind, etwa die Ausgabe eines Rich-Text-Felds, werden über ihre Ansichts-Templates (attribute_view_gui) ausgegeben und dürfen nicht ein zweites Mal gewaschen werden. Siehe Wash und Maskierung.

Unbekannte Operatoren reichen ihre Eingabe durch #

Smarty kann ein Template, das einen unbekannten Modifikator nutzt, nicht kompilieren. Die Template-Sprache protokolliert eine Warnung (Operator '...' is not registered) und lässt den Wert, wie er war. Ein falsch geschriebener Operator hält die Seite also nicht an; er tut stillschweigend nichts, lesen Sie deshalb die Debug-Ausgabe:

[{'unchanged'|nosuchoperator}]

Ausgabe:

[unchanged]

Von der Template-Engine protokolliert:

WARNING : Operator 'nosuchoperator' is not registered

def und set sind streng #

{def} legt eine Variable an und warnt, wenn sie schon existiert (es weist den Wert dann trotzdem zu); {set} ändert eine Variable und weigert sich, eine anzulegen. Beide schreiben eine Warnung, keinen Fehler, die Seite wird also weiter gerendert:

{def $color = 'red'}
{def $color = 'blue'}
{set $size = 'large'}
[{$color}]

Ausgabe:

[blue]

Von der Template-Engine protokolliert:

WARNING def: Variable 'color' is already defined.
WARNING set: Variable 'size' doesn't exist, cannot set

Die Regeln stammen aus eZTemplateDefFunction::process() und eZTemplateSetFunction::process(); siehe Variablen im Detail.

Klammern in CSS und JavaScript #

Jede { beginnt ein Tag. Eine CSS-Regel oder ein JavaScript-Objekt in einem Template wird als Tag gelesen, das nach dem benannt ist, was auf die Klammer folgt; das ist ein Fehler, und alles danach geht verloren. Hier verschwindet sogar das Wort after:

before
.box { color: red; }
after

Ausgabe:

before
.box

Von der Template-Engine protokolliert:

ERROR : parser error @ tl-diff/07-braces-in-text.tpl:2[11]
Invalid parameter characters in function '': ': red; '
WARNING : Function "" is not registered

Die Abhilfen sind dieselben wie bei Smarty: {literal}...{/literal} um den Block oder {ldelim} und {rdelim} für einzelne Klammern. In den Admin-Designs von Exponential gehören Skripte und Styles überhaupt nicht in Templates; sie liegen in Dateien, die über die Skript- und Stylelisten des Designs geladen werden.

before
{literal}.box { color: red; }{/literal}
.box {ldelim} color: red; {rdelim}
after

Ausgabe:

before
.box { color: red; }
.box { color: red; }after

Kein PHP in Templates #

Es gibt kein Tag {php}. Der Parser behandelt es als Funktionsnamen, die Engine hat keine solche Funktion, und der Block wird mit einer Warnung verworfen:

[{php}echo 1;{/php}]

Ausgabe:

[]

Von der Template-Engine protokolliert:

WARNING : Function "php" is not registered

Logik, die PHP braucht, gehört in einen Operator, eine Funktion oder eine Fetch-Funktion einer Erweiterung.

Operatoren und Funktionen sind registrierte PHP-Klassen #

Ein Plugin von Smarty ist eine PHP-Funktion, die über ihren Dateinamen gefunden wird. Ein Template-Operator ist eine Methode einer Klasse, die eine Datei eztemplateautoload.php aufführt ($eZTemplateOperatorArray); die Engine liest diese Listen aus den Pfaden in site.ini [TemplateSettings] AutoloadPathList und aus jeder in ExtensionAutoloadPath genannten Erweiterung (eZTemplate::factory() und eZTemplate::autoload()). Die Klasse wird geladen, wenn einer ihrer Operatoren zum ersten Mal genutzt wird. Template-Funktionen werden auf dieselbe Weise über $eZTemplateFunctionArray registriert. Die beiden werden in Funktionen und Operatoren verglichen.

Daten kommen aus fetch, und Werte sind Objekte #

Ein Template von Smarty bekommt meist alle seine Daten von dem PHP, das es rendert. Ein Template von Exponential fragt Daten oft selbst ab: fetch( 'content', 'list', hash( ... ) ) führt eine Fetch-Funktion des Moduls content mit den Berechtigungen des aktuellen Benutzers aus. Die Werte sind PHP-Objekte (Knoten, Inhaltsobjekte, Attribute), gelesen über attribute(): $node.data_map.title.content. Siehe Zugriff auf Attribute und Grundlagen von fetch.

Overrides statt Vererbung #

Templates von Smarty erweitern einander mit {extends} und {block}. In Exponential umschließt das Pagelayout jede Seite und gibt das Ergebnis der Modulansicht aus ($module_result.content), und das Override-System (override.ini) wählt nach Klasse, Sektion, Knoten, Elternknoten, Ansichtsmodus und mehr, welches Template eine Ansicht rendert. Teile einer Seite werden mit include und den Funktionen *_view_gui geteilt. Siehe Grundlagen der Overrides.

Namensräume #

Variablen leben in Namensräumen. Ein include ohne name läuft im Namensraum des Aufrufers und sieht alle seine Variablen; mit name='box' läuft es in einem eigenen Namensraum und sieht nur die Parameter, die es bekommen hat. section und let mit einem name legen ebenfalls Namensräume an. Siehe Namensräume.

Leerraum um Tags #

Der Parser entfernt einen Zeilenumbruch direkt vor und einen direkt nach jedem Funktions-Tag ({if}, {/foreach}, {def ...}), aber nicht um Ausgabe-Tags wie {$x}. Templates können also jede Funktion in eine eigene Zeile setzen, ohne dem HTML Leerzeilen hinzuzufügen. Siehe Lexikalische Struktur.

Verwandte Seiten #

• Von Exponential-Templates (.tpl) zu Exponential-Smarty-Templates (.stpl) umziehen: Smarty-Templates, von Exponential selbst ausgeführt
• Zurück: Smarty und die Template-Sprache nebeneinander
• Weiter: Ein Template von Smarty umziehen
• Häufige Fehler in Templates
• Logik- und Vergleichsoperatoren
• Literal und Begrenzer
• Freie Dokumentation: Diese Seite darf unter der GNU FDL 1.3 frei kopiert, übersetzt und verbessert werden.