Eigene Template-Funktionen #

Eine Template-Funktion ist ein Tag wie {include ...}, {cache-block}...{/cache-block} oder {def ...}: Sie nimmt benannte Parameter, kann einen Rumpf haben und schreibt Ausgabe oder ändert Variablen. Operatoren dagegen nehmen einen Wert und geben einen zurück (Funktionen und Operatoren). Diese Seite zeigt, wie eine Erweiterung eine Funktion hinzufügt und was die Engine erwartet, aus lib/eztemplate/classes/eztemplate.php und lib/eztemplate/classes/eztemplatemultipassparser.php.

Inhalt #

1. Wann Sie eine Funktion schreiben
2. Die Beispielfunktion
3. Die Methoden
4. Sie registrieren
5. Sie nutzen
6. Hinweise zur Kompilierzeit
7. Funktionen des Kernels erweitern und überschreiben

Wann Sie eine Funktion schreiben #

Schreiben Sie eine Funktion, wenn das Tag einen Rumpf braucht (das Markup zwischen öffnendem und End-Tag umschließen, wiederholen oder auffangen), Variablen im Namensraum des Aufrufers setzen muss oder steuert, was gerendert wird. Für Wert hinein, Wert heraus schreiben Sie einen Operator; zum Lesen von Daten eine Fetch-Funktion. Für wiederverwendbares Markup ohne PHP ist ein {include} eines Template-Teils einfacher als beides.

Die Beispielfunktion #

{c11_box title=... class=...}body{/c11_box} umschließt ihren Rumpf mit einem <section> samt maskierter Überschrift. Die Klasse, wie eine Erweiterung sie in extension/myextension/autoloads/c11examplefunction.php ausliefern würde:

class C11ExampleFunction
{
    /** The function names this class answers */
    function functionList()
    {
        return array( 'c11_box' );
    }

    /** true: the function has a body and an end tag {/c11_box} */
    function hasChildren()
    {
        return true;
    }

    function process( $tpl, &$textElements, $functionName, $functionChildren, $functionParameters,
                      $functionPlacement, $rootNamespace, $currentNamespace )
    {
        if ( !isset( $functionParameters['title'] ) )
        {
            $tpl->warning( $functionName, 'Missing parameter: title', $functionPlacement );
            return;
        }
        // parameters arrive unevaluated: evaluate each one
        $title = $tpl->elementValue( $functionParameters['title'], $rootNamespace, $currentNamespace, $functionPlacement );
        $class = isset( $functionParameters['class'] )
               ? $tpl->elementValue( $functionParameters['class'], $rootNamespace, $currentNamespace, $functionPlacement )
               : 'box';

        // render the body in the caller's namespaces
        $body = array();
        foreach ( (array)$functionChildren as $child )
            $tpl->processNode( $child, $body, $rootNamespace, $currentNamespace );

        $textElements[] = '<section class="' . htmlspecialchars( $class ) . '"><h2>' . htmlspecialchars( $title ) . '</h2>'
                        . implode( '', $body ) . '</section>';
    }
}

Die Methoden #

process( $tpl, &$textElements, $functionName, $functionChildren, $functionParameters, $functionPlacement, $rootNamespace, $currentNamespace ):

• $textElements: Hängen Sie Ausgabezeichenketten an dieses Array an (nicht mit echo ausgeben);
• $functionChildren: der gelesene Rumpf, eine Liste von Knoten; rendern Sie sie mit $tpl->processNode( $child, $textElements, $rootNamespace, $currentNamespace ), in Ihr eigenes Array, wenn Sie den Rumpf nachbearbeiten wollen, wie das Beispiel;
• $functionParameters: die benannten Parameter unausgewertet, nach Namen geordnet; werten Sie sie mit $tpl->elementValue( $functionParameters['name'], $rootNamespace, $currentNamespace, $functionPlacement ) aus. Ein Parameter, den das Template nicht geschrieben hat, ist nicht gesetzt;
• Variablen: $tpl->setVariable( $name, $value, $currentNamespace ) und $tpl->variable( $name, $currentNamespace ) lesen und schreiben die Variablen des Aufrufers (eZTemplateBlockFunction nutzt sie für set-block);
• $functionPlacement: wo das Tag steht, für $tpl->warning() und $tpl->error().

Sie registrieren #

In extension/myextension/autoloads/eztemplateautoload.php, neben etwaigen Operatoren:

<?php
$eZTemplateFunctionArray = array();
$eZTemplateFunctionArray[] = array( 'script' => 'extension/myextension/autoloads/c11examplefunction.php',
                                    'class' => 'C11ExampleFunction',
                                    'function_names' => array( 'c11_box' ) );

Schlüssel: class oder function (eine PHP-Funktion, die das Objekt zurückgibt), script, function_names oder function_names_function und function_attributes (die Namen der Unter-Tags, damit der Parser sie kennt, bevor die Klasse geladen ist; die Bibliothek registriert elseif und else von if auf diese Weise). Die Erweiterung braucht außerdem [TemplateSettings] ExtensionAutoloadPath[]=myextension in ihrer settings/site.ini.append.php; siehe Operatoren registrieren, das beide Arrays behandelt.

Sie nutzen #

Nicht als installierte Erweiterung auf einer Entwicklungsinstallation ausgeführt: Das Skript, das diese Beispiele renderte, registrierte den Eintrag oben im Speicher an der Template-Engine, mit der Klasse in einem Arbeitsordner. Interpretierte und kompilierte Ergebnisse waren gleich.

{def $node = fetch( 'content', 'node', hash( 'node_id', 89 ) )}
{c11_box title=$node.name class='teaser'}<p>{$node.children_count} children</p>{/c11_box}
{c11_box title='Plain'}<p>Default class</p>{/c11_box}

Ausgabe:

<section class="teaser"><h2>Fit &amp; Healthy</h2><p>16 children</p></section><section class="box"><h2>Plain</h2><p>Default class</p></section>

Ein fehlender Parameter, von der eigenen Prüfung der Funktion behandelt:

{c11_box}<p>no title</p>{/c11_box}

Ausgabe:

(no output)

Von der Template-Engine protokolliert:

WARNING c11_box: Missing parameter: title

Ein Funktionsname, den niemand registriert hat: Der Parser behandelt ein unbekanntes Tag als Block (sein Standard, wenn keine Klasse auf den Namen antwortet), also wird auch der Rumpf verschluckt, und die Engine protokolliert eine Warnung:

{c11_unknown title='x'}<p>body</p>{/c11_unknown}

Ausgabe:

(no output)

Von der Template-Engine protokolliert:

WARNING : Function "c11_unknown" is not registered

Hinweise zur Kompilierzeit #

functionTemplateHints() gibt pro Funktionsname Schlüssel zurück wie parameters, static, tree-transformation (die Funktion schreibt ihren eigenen Knoten zur Kompilierzeit über templateNodeTransformation() um, wie eZTemplateDelimitFunction es für ldelim/rdelim tut) und die zugehörigen Einstellungen zur Transformation, die die Funktionen der Bibliothek nutzen. Eine Funktion ohne Hinweise, wie das Beispiel, wird zu einem Laufzeitaufruf ihres process() kompiliert, was dasselbe Ergebnis ergibt und die sichere Wahl ist. Fügen Sie Hinweise nur mit einem Test hinzu, der interpretierte und kompilierte Ausgabe vergleicht; die Gründe sind dieselben wie bei Operatoren (operatorTemplateHints).

Funktionen des Kernels erweitern und überschreiben #

Funktionsnamen folgen genau den Regeln für Operatoren: Der letzte Eintrag in einer eztemplateautoload.php für einen Namen gewinnt, und eine Klasse registriert beim Laden alle Namen ihres functionList() (Reihenfolge der Registrierung und Overrides). Auf einer Entwicklungsinstallation ist kein Funktionsname doppelt registriert. Um eine Funktion des Kernels oder der Bibliothek aus einer Erweiterung zu ändern:

• leiten Sie von der Klasse ab, der der Name gehört (zum Beispiel eZTemplateBlockFunction, der set-block, append-block und run-once gehören), überschreiben Sie process() für den Namen, den Sie ändern, und rufen Sie für die anderen parent::process() auf;
• registrieren Sie die Unterklasse für alle Namen der Elternklasse, und halten Sie function_attributes und hasChildren() mit der Elternklasse übereinstimmend;
• entfernen Sie den Eintrag in functionTemplateHints() der Elternklasse für den Namen, den Sie ändern, sonst behalten kompilierte Templates den Code der Elternklasse (der Fall bei Operatoren, auf einer Entwicklungsinstallation gezeigt).

Nicht mit einer Funktion auf einer Entwicklungsinstallation vorgeführt: Das Überschreiben eines Funktionsnamens nutzt denselben Codepfad wie bei Operatoren (registerAutoloadFunctions(), registerFunctionsInternal()), den Operatoren des Kernels überschreiben gerendert zeigt. Das Überschreiben der eigenen Kontrollfunktionen der Sprache (if, foreach, def, include) ändert jedes Template auf dem Siteaccess; ziehen Sie einen neuen Funktionsnamen vor.

Verwandte Seiten #

• Funktionen und Operatoren
• Referenz der Funktionen: jede Funktion der Bibliothek und des Kernels
• Operatoren registrieren
• Die Schnittstelle der Operatorklasse
• Freie Dokumentation: Diese Seite darf unter der GNU FDL 1.3 frei kopiert, übersetzt und verbessert werden.