Funktionen und Operatoren #

Die Template-Sprache hat zwei Arten benannter Bausteine. Eine Funktion ist ein Tag: {if}, {foreach}, {include}, {cache-block}. Ein Operator erzeugt einen Wert innerhalb eines Ausdrucks: wash, fetch, concat, count. Sie werden in getrennten Listen registriert, durch verschiedene Methoden umgesetzt und unterschiedlich kompiliert. Wer weiß, was was ist, kann die meisten Fragen der Art „Warum funktioniert das hier nicht?“ beantworten.

Inhalt #

1. Auf einen Blick
2. Dieselbe Aufgabe auf beide Arten
3. Von der Ausgabe einer Funktion zu einem Operator
4. Registrierung
5. Die PHP-Seite
6. Interpretiert und kompiliert
7. Was Sie schreiben sollten
8. Verwandte Seiten

Auf einen Blick #

Dieselbe Aufgabe auf beide Arten #

Viele Aufgaben lassen sich mit beiden erledigen, und das Ergebnis ist derselbe Text:

{def $tags = array( 'news', 'sport', 'weather' )}
function: {foreach $tags as $t}{$t}{delimiter}, {/delimiter}{/foreach}
operator: {$tags|implode( ', ' )}
function: {if $tags|count|gt( 2 )}many{else}few{/if}
operator: {cond( $tags|count|gt( 2 ), 'many', 'few' )}

Ausgabe:

function: news, sport, weatheroperator: news, sport, weather
function: manyoperator: many

Die Form mit Funktion liest sich leichter, wenn die Zweige oder der Schleifenrumpf Markup enthalten; die Form mit Operator passt in einen Parameter oder einen Attributwert.

Von der Ausgabe einer Funktion zu einem Operator #

Die Ausgabe von Funktionen ist Text, und set-block macht aus Text wieder einen Wert, mit dem Operatoren arbeiten können:

{set-block variable=list}{foreach array( 'a', 'b', 'c' ) as $x}<{$x}>{/foreach}{/set-block}
[{$list}] [{$list|count_chars}] [{$list|upcase}]

Ausgabe:

[<a><b><c>] [9] [<A><B><C>]

Eine Funktion lässt sich nicht dort nutzen, wo ein Wert erwartet wird. Innerhalb eines Ausdrucks kennt der Parser nur Operatoren, also wird if( ... ) als Operator gesucht:

[{concat( 'a', if( true() ) )}]

Ausgabe:

[a]

Von der Template-Engine protokolliert:

WARNING : Operator 'if' is not registered

Registrierung #

Beide Arten werden in einer Datei eztemplateautoload.php aufgeführt, die eZTemplate::autoload() aus jedem Pfad von site.ini [TemplateSettings] AutoloadPathList und aus jeder Erweiterung in ExtensionAutoloadPath einbindet (<extension>/autoloads/eztemplateautoload.php). Die eigene Datei der Template-Bibliothek, lib/eztemplate/classes/eztemplateautoload.php, zeigt beide Formen:

$eZTemplateOperatorArray[] = array( 'class' => 'eZTemplateTextOperator',
                                    'operator_names' => array( 'concat', 'indent' ) );

$eZTemplateFunctionArray[] = array( 'class' => 'eZTemplateIfFunction',
                                    'function_names' => array( 'if' ),
                                    'function_attributes' => array( 'elseif',
                                                                    'else' ) );

function_attributes nennt die Kind-Tags, die zur Funktion gehören (elseif und else von if; delimiter, break, continue und skip der Schleifen; case von switch). Einträge werden zunächst nur vorgemerkt; die Klasse wird geladen, wenn einer ihrer Namen zum ersten Mal genutzt wird (loadAndRegisterOperators(), loadAndRegisterFunctions()). Ein zweimal registrierter Name behält den zuletzt gelesenen Eintrag; so kann eine Erweiterung einen Operator des Kernels ersetzen; die Seite Operatoren des Kernels überschreiben behandelt das.

Die Ansichtsfunktionen des Kernels (node_view_gui, attribute_view_gui und die anderen Funktionen *_gui) sind alle eine Klasse, eZObjectForwarder in kernel/common/ezobjectforwarder.php, konfiguriert durch die Regeln in kernel/common/eztemplateautoload.php.

Die PHP-Seite #

Eine Operatorklasse beantwortet:

• operatorList(): die Namen, die sie behandelt;
• namedParameterPerOperator() und namedParameterList(): die Parameter, mit type, required und default;
• modify( $tpl, $operatorName, $operatorParameters, $rootNamespace, $currentNamespace, &$operatorValue, $namedParameters, $placement ): liest die Eingabe aus $operatorValue und schreibt das Ergebnis dorthin zurück.

Eine Funktionsklasse beantwortet:

• functionList(): die Namen, die sie behandelt;
• hasChildren(): ob sie ein Block ist (true, false oder ein Array pro Name);
• process( $tpl, &$textElements, $functionName, $functionChildren, $functionParameters, $functionPlacement, $rootNamespace, $currentNamespace ): hängt Ausgabe an $textElements an, setzt Variablen und verarbeitet ihre Kinder mit $tpl->processNode() so oft sie will; so wiederholen Schleifen ihren Rumpf.

Interpretiert und kompiliert #

Wenn site.ini [TemplateSettings] TemplateCompile eingeschaltet ist (der Standard), wird jedes Template einmal in eine PHP-Datei umgewandelt (lib/eztemplate/classes/eztemplatecompiler.php). Beide Arten können daran teilnehmen:

• Eine Funktion mit 'tree-transformation' => true in functionTemplateHints() ersetzt ihren Knoten in templateNodeTransformation() durch erzeugtes PHP. foreach, if, def und set tun das. Eine Funktion ohne diesen Hinweis wird aus der kompilierten Datei über process() aufgerufen.
• Ein Operator mit 'element-transformation' => true in operatorTemplateHints() erzeugt PHP für seinen Aufruf, über die in element-transformation-func genannte Methode (zum Beispiel phpMapTransformation für upcase). Andere werden zur Laufzeit über modify() aufgerufen.

So oder so muss die Ausgabe dieselbe sein wie beim interpretierten Template. Die Beispiele dieser Seiten wurden auf einer Entwicklungsinstallation auf beide Arten gerendert und verglichen; die tatsächlich gefundenen Unterschiede sind auf Sections und foreach und in der Referenz zu foreach vermerkt.

Was Sie schreiben sollten #

• Schreiben Sie einen Operator, um einen Wert zu berechnen, zu formatieren oder nachzuschlagen: Er lässt sich mit jedem anderen Operator kombinieren und in jedem Parameter nutzen. Die meisten Bedürfnisse von Erweiterungen sind Operatoren.
• Schreiben Sie eine Funktion nur, um die Ausgabe zu steuern: einen Block zu wiederholen oder zu überspringen, ihn aufzufangen oder zu cachen oder etwas mit einem eigenen Template zu rendern. Funktionen sind schwerer gut zu schreiben, weil sie Kinder, Namensräume und Kompilierung behandeln.
• Schreiben Sie eine Fetch-Funktion (in der function_definition.php eines Moduls), um Templates Daten aus der Datenbank zu geben: fetch( 'yourmodule', 'yourfunction', hash( ... ) ). Siehe Eine eigene Fetch-Funktion schreiben.

Verwandte Seiten #

• Zurück: Operatoren in Ausdrücken
• Weiter: Referenz der Kontrollstrukturen
• Referenz der Funktionen und Referenz der Operatoren
• Template-Operatoren schreiben
• Ein eigener Template-Operator
• Freie Dokumentation: Diese Seite darf unter der GNU FDL 1.3 frei kopiert, übersetzt und verbessert werden.