Die Schnittstelle einer Operatorklasse #

Ein Template-Operator ist ein beliebiges PHP-Objekt mit den unten beschriebenen Methoden; es gibt keine Basisklasse und keine Schnittstelle, die implementiert werden müsste. Alles auf dieser Seite stammt aus lib/eztemplate/classes/eztemplate.php (processOperator(), operatorParameterList(), loadAndRegisterOperators()) und lib/eztemplate/classes/eztemplatecompiler.php. Eine geführte Einführung in den ersten eigenen Operator finden Sie unter Einen Operator Schritt für Schritt anlegen.

Inhalt #

1. Die Beispielklasse
2. Der Registrierungseintrag
3. operatorList
4. namedParameterPerOperator und namedParameterList
5. modify
6. operatorTemplateHints
7. Element-Transformationen
8. operatorCompiledStaticData

Die Beispielklasse #

Die Beispiele verwenden C11ExampleOperators, eine Klasse, die für diese Seiten geschrieben wurde. Sie lief auf einer Entwicklungsinstallation nicht als installierte Erweiterung: Das Skript, das die Beispiele gerendert hat, registrierte die Klasse im Speicher bei der Template-Engine (mit demselben Eintrag, den die eztemplateautoload.php einer Erweiterung hinzufügen würde) und lud sie aus einem Arbeitsordner; kompilierte Ergebnisse wurden in einen Arbeitsordner kompiliert. Ihre Operatoren:

Der Registrierungseintrag #

Ein Eintrag von $eZTemplateOperatorArray in einer eztemplateautoload.php (Operatoren registrieren):

Die Engine speichert den Eintrag unter jedem Namen und erzeugt das Objekt, sobald ein Template zum ersten Mal einen davon verwendet.

operatorList #

function operatorList()
{
    return array( 'exp_initials', 'exp_reading_time', 'exp_clamp', 'exp_parameters_seen', 'exp_wrong_hint', 'exp_twice' );
}

Erforderlich. Wenn das Objekt erzeugt wird, registriert die Engine es unter jedem Namen, den diese Methode zurückgibt; dabei kann es anderen Klassen Namen wieder abnehmen (A loaded class takes its names back). Geben Sie genau die Namen Ihres Registrierungseintrags zurück.

namedParameterPerOperator und namedParameterList #

function namedParameterPerOperator()
{
    return true;
}

function namedParameterList()
{
    return array(
        'exp_initials' => array(),
        'exp_reading_time' => array(
            'words_per_minute' => array( 'type' => 'integer', 'required' => false, 'default' => 200 ) ),
        'exp_clamp' => array(
            'min' => array( 'type' => 'numeric', 'required' => true, 'default' => false ),
            'max' => array( 'type' => 'numeric', 'required' => true, 'default' => false ) ),
        // ...
    );
}

• Gibt namedParameterPerOperator() den Wert true zurück, ist namedParameterList() nach Operatornamen geschlüsselt. Fehlt die Methode (oder gibt sie false zurück), gilt die Liste für jeden Operator der Klasse.
• Das Template übergibt Parameter nach Position; die Namen beschriften sie nur in $namedParameters.
• type dient der Dokumentation: Die Engine prüft oder konvertiert den Wert nicht. Prüfen Sie Werte in modify().
• required: Lässt das Template den Parameter weg, schreibt die Engine die Warnung Parameter '<name>' (<position>) missing und ruft modify() trotzdem auf, mit dem default.
• default: der Wert, der verwendet wird, wenn der Parameter fehlt. Fehlt er in der Definition, übergibt die Engine null und warnt Operator '<operator>' has no default value for parameter '<name>' (in interpretierten Templates einmal pro Anfrage, in kompilierten beim Kompilieren).

Optionale und erforderliche Parameter auf einer Entwicklungsinstallation:

{def $node = fetch( 'content', 'node', hash( 'node_id', 89 ) )
     $text = 'one two three four five six seven eight nine ten eleven twelve'}
{$node.name|wash} -> {$node.name|exp_initials}
{$text|exp_reading_time} minute(s) at 200 words a minute, {$text|exp_reading_time( 5 )} at 5
{exp_initials( 'Bold Agency' )}

Ausgabe:

Fit & Healthy -> FH
1 minute(s) at 200 words a minute, 3 at 5

{150|exp_clamp( 0, 100 )} {-5|exp_clamp( 0, 100 )} {42|exp_clamp( 0, 100 )}
{42|exp_clamp( 0 )}

Ausgabe:

100 0 42
42

Von der Template-Engine protokolliert:

WARNING eZTemplateOperatorElement: Parameter 'max' (1) missing
WARNING exp_clamp: min and max must be numbers

Die zweite Zeile übergibt nur min: Die Engine warnt wegen max, übergibt dessen Standardwert false, und die eigene Prüfung des Operators lehnt den Aufruf ab und lässt die Eingabe unverändert (42).

modify #

function modify( $tpl, $operatorName, $operatorParameters, $rootNamespace, $currentNamespace,
                 &$operatorValue, $namedParameters, $placement = false )

Was exp_parameters_seen über seine Argumente meldet, einmal als Funktion aufgerufen und einmal über die Pipe:

{def $b = 'bee'}
{exp_parameters_seen( 'a', $b )}
{'piped'|exp_parameters_seen}

Ausgabe:

value=NULL named={"first":"a","second":"bee"} raw count=2 first raw element type=1 second evaluated again='bee' placement=[[2,0,18],[2,30,48],"var\/tmp\/examples\/ld-op\/03-what-modify-receives.tpl"]
value='piped' named={"first":"first-default","second":"second-default"} raw count=0 first raw element type=none second evaluated again=NULL placement=[[3,0,51],[3,27,78],"var\/tmp\/examples\/ld-op\/03-what-modify-receives.tpl"]

Ausgabe mit dem Template-Compiler (in einen Arbeitsordner kompiliert):

value=NULL named={"first":"a","second":"bee"} raw count=2 first raw element type=1 second evaluated again='bee' placement=false
value='piped' named={"first":"first-default","second":"second-default"} raw count=0 first raw element type=none second evaluated again=NULL placement=false

Was die Ausgabe zeigt:

• in der Aufrufform ist $operatorValue NULL; über die Pipe ist es die Eingabe;
• $namedParameters enthält die ausgewerteten Werte mit eingesetzten Standardwerten;
• $operatorParameters enthält Element-Arrays (Typ 1 ist eZTemplate::TYPE_STRING), und $tpl->elementValue( $operatorParameters[1], $rootNamespace, $currentNamespace, $placement ) wertet eines erneut aus; verwenden Sie das nur für Operatoren, die einen Parameter verzögert oder mehrfach auswerten müssen;
• $placement ist in einem interpretierten Template [[Startzeile, Spalte, Position], [Endzeile, Spalte, Position], Template-Datei] und in einem kompilierten false. Übergeben Sie es trotzdem an $tpl->warning( $operatorName, $text, $placement ): Warnungen kompilierter Templates haben dann zwar keine Zeilennummer, werden aber trotzdem geschrieben.

Regeln für modify(): Weisen Sie das Ergebnis $operatorValue zu; geben Sie nie etwas mit echo aus; geben Sie Text unmaskiert zurück und lassen Sie das Template ihn mit |wash maskieren; schreiben Sie bei ungültiger Eingabe eine Warnung und lassen Sie $operatorValue unverändert oder setzen Sie einen neutralen Wert; ändern Sie aus einem Operator heraus weder Inhalte noch Einstellungen (die Ausgabe wird gecacht, und Operatoren laufen, während Seiten kompiliert und gerendert werden).

operatorTemplateHints #

Optional. Teilt dem Template-Compiler mit, was ein Operator tut, geschlüsselt nach Operatornamen:

function operatorTemplateHints()
{
    return array(
        // correct: takes the piped value, returns a value, no parameters
        'exp_initials' => array( 'input' => true, 'output' => true, 'parameters' => false ),
        // wrong on purpose: the operator uses its piped value but says it takes none
        'exp_wrong_hint' => array( 'input' => false, 'output' => true, 'parameters' => false ),
        // ...
    );
}

Der Interpreter ignoriert Hinweise; der Compiler vertraut ihnen. Ein falscher Hinweis ist daher ein Fehler, der sich nur in kompilierten Templates zeigt, was bei einer Standardinstallation bedeutet: bei jedem Besucher.

{'fit & healthy'|exp_initials} {'fit & healthy'|exp_wrong_hint}

Ausgabe:

FH FIT & HEALTHY

Ausgabe mit dem Template-Compiler (in einen Arbeitsordner kompiliert):

FH

Ein Operator ohne operatorTemplateHints() wird in einen Laufzeitaufruf von $tpl->processOperator() kompiliert, der modify() genauso aufruft wie der Interpreter. Das ist immer korrekt, nur langsamer; lassen Sie Hinweise weg, bis Sie die Geschwindigkeit brauchen.

Element-Transformationen #

Ein Operator, dessen Arbeit einfaches PHP ist, kann dieses PHP in das kompilierte Template schreiben, sodass zur Laufzeit kein Operator-Objekt aufgerufen wird. exp_twice multipliziert seine Eingabe mit zwei:

// hints
'exp_twice' => array( 'input' => true, 'output' => true, 'parameters' => false,
                      'element-transformation' => true, 'transform-parameters' => true,
                      'input-as-parameter' => 'always',
                      'element-transformation-func' => 'twiceTransformation' ),

// the method the compiler calls
function twiceTransformation( $operatorName, &$node, $tpl, &$resourceData,
                              $element, $lastElement, $elementList, $elementTree, &$parameters )
{
    $values = array( $parameters[0] );
    return array( eZTemplateNodeTool::createCodePieceElement( "%output% = %1% * 2; // exp_twice, compiled\n", $values ) );
}

%1% wird durch den Code des ersten Werts in $values ersetzt (hier die Eingabe über die Pipe), %output% durch die Variable, die das Ergebnis erhält. Geben Sie false zurück (kein Array), wenn sich der Aufruf nicht transformieren lässt, zum Beispiel wenn ein Parameter nicht konstant ist (eZTemplateExecuteOperator::fetchTransform() macht das so); der Compiler behält dann einen Laufzeitaufruf bei. modify() muss den Operator für interpretierte Templates trotzdem implementieren:

{def $n = 21}
{$n|exp_twice} {4|exp_twice|exp_twice}

Ausgabe:

42 16

Ausgabe mit dem Template-Compiler (in einen Arbeitsordner kompiliert):

42 16

Ein Auszug aus dem PHP, das der Compiler auf einer Entwicklungsinstallation für die zweite Zeile ({4|exp_twice|exp_twice}) erzeugt hat: Die Konstante wurde in die erste Multiplikation eingefaltet, und es wird kein Operator-Objekt aufgerufen:

$var1 = 4 * 2; // exp_twice, compiled
if (! isset( $var1 ) ) $var1 = NULL;
while ( is_object( $var1 ) and method_exists( $var1, 'templateValue' ) )
    $var1 = $var1->templateValue();
$var = $var1 * 2; // exp_twice, compiled

Interpretierte und kompilierte Ergebnisse müssen immer gleich sein; testen Sie beide. Die Operatoren der Bibliothek sind die beste Referenz: eZTemplateStringOperator (phpMap und customMap machen PHP-Funktionen zu Code) und eZTemplateArithmeticOperator.

operatorCompiledStaticData #

Mit 'static' => true in den Hinweisen ruft der Compiler operatorCompiledStaticData( $operatorName ) einmal auf und schreibt den zurückgegebenen Wert als Konstante in das kompilierte Template (die Template-Bibliothek nutzt das für true() und false() in eZTemplateLogicOperator). Verwenden Sie es nur für Werte, die sich zwischen dem Kompilieren und dem nächsten Leeren des Caches nie ändern, niemals für Benutzer-, Zeit- oder Inhaltsdaten.

Verwandte Seiten #

• Einen Operator Schritt für Schritt anlegen
• Operatoren registrieren
• Kernel-Operatoren überschreiben
• Der Template-Compiler
• Template-Operatoren schreiben (Einführung für Anwendungsentwickler)
• Freie Dokumentation: Diese Seite darf unter der GNU FDL 1.3 frei kopiert, übersetzt und verbessert werden.