Template-Operatoren #

Teil 3, Kapitel 13. Ein Template-Operator ist eine Funktion, die Templates aufrufen können: {mysite_greet( 'Ada' )} oder {$name|mysite_initials}. Er ist das kleinste nützliche Stück PHP, das eine Erweiterung hinzufügen kann, und ein guter Einstieg. Dieses Kapitel baut eine Klasse mit zwei Operatoren; die Klasse und das Template unten wurden von der Template-Engine des Kernels gerendert, bevor diese Seite geschrieben wurde.

Drei Teile #

Der Anschluss #

<?php /* #?ini charset="utf-8"?

[TemplateSettings]
ExtensionAutoloadPath[]=mysite_hello

*/ ?>

Die Registrierung #

extension/mysite_hello/autoloads/eztemplateautoload.php:

<?php
$eZTemplateOperatorArray = array();
$eZTemplateOperatorArray[] = array(
    'script' => 'extension/mysite_hello/classes/mysitehellooperators.php',
    'class' => 'mysiteHelloOperators',
    'operator_names' => array( 'mysite_greet', 'mysite_initials' )
);

Die Engine (eZTemplate::registerAutoloadOperators(), lib/eztemplate/classes/eztemplate.php) registriert die Namen sofort und lädt die Klasse erst, wenn ein Template zum ersten Mal einen davon verwendet. Statt operator_names kann eine Definition operator_names_function angeben, eine Funktion, die die Namen zurückgibt.

Die Klasse #

<?php
/**
 * Template operators of mysite_hello:
 *   {mysite_greet( 'Ada' )}            -> Hello, Ada!
 *   {mysite_greet( 'Ada', 'Welcome' )} -> Welcome, Ada!
 *   {'Ada Lovelace'|mysite_initials}   -> AL
 */
class mysiteHelloOperators
{
    public function operatorList()
    {
        return array( 'mysite_greet', 'mysite_initials' );
    }

    public function namedParameterPerOperator()
    {
        return true;
    }

    public function namedParameterList()
    {
        return array(
            'mysite_greet' => array(
                'name'     => array( 'type' => 'string', 'required' => true, 'default' => '' ),
                'greeting' => array( 'type' => 'string', 'required' => false, 'default' => 'Hello' )
            ),
            'mysite_initials' => array()
        );
    }

    public function modify( $tpl, $operatorName, $operatorParameters, $rootNamespace, $currentNamespace, &$operatorValue, $namedParameters )
    {
        switch ( $operatorName )
        {
            case 'mysite_greet':
                $operatorValue = $namedParameters['greeting'] . ', ' . $namedParameters['name'] . '!';
                break;

            case 'mysite_initials':
                $initials = '';
                foreach ( preg_split( '/\s+/u', trim( (string)$operatorValue ) ) as $word )
                {
                    if ( $word !== '' )
                        $initials .= mb_strtoupper( mb_substr( $word, 0, 1 ) );
                }
                $operatorValue = $initials;
                break;
        }
    }
}

$operatorValue ist die Eingabe eines weitergeleiteten Aufrufs ({$text|mysite_initials} übergibt $text) und die Ausgabe jedes Aufrufs. $namedParameters enthält die Parameter unter den Namen, die Sie deklariert haben, mit eingesetzten Standardwerten.

Das Ergebnis #

Das Template

[{mysite_greet( 'Ada' )}] [{mysite_greet( 'Ada', 'Welcome' )}] [{'Ada Lovelace'|mysite_initials}] [{'émile zola'|mysite_initials}]

ergibt

[Hello, Ada!] [Welcome, Ada!] [AL] [ÉZ]

Beachten Sie die mb_-Funktionen: Namen sind UTF-8, und strtoupper() würde das é zerstören.

Maskieren ist Aufgabe des Templates #

Ein Operator gibt einen Wert zurück; das Template entscheidet, wie er ausgegeben wird. Geben Sie reinen Text zurück und lassen Sie die Templates ihn mit |wash behandeln, es sei denn, Ihr Operator soll HTML erzeugen; dann maskieren Sie jeden Wert, den Sie in dieses HTML einsetzen, mit htmlspecialchars().

Machen Sie ihn rein #

Die besten Operatoren hängen nur von ihren Parametern ab: keine Schreibzugriffe auf die Datenbank, keine Ausgabe, keine Sitzung. Dann lassen sie sich gefahrlos aus gecachten Templates aufrufen und leicht testen. Ein Operator, der Daten braucht (einen Fetch, eine Einstellung), darf sie lesen, sollte aber nie etwas ändern; Änderungen gehören in eine Modul-View.

Häufige Fehler #

Testen #

Da die Klasse nichts außer ihren Parametern braucht, kann ein PHPUnit-Test modify() direkt aufrufen:

<?php
class mysiteHelloOperatorsTest extends PHPUnit\Framework\TestCase
{
    public function testInitials()
    {
        $operators = new mysiteHelloOperators();
        $value = 'Ada Lovelace';
        $operators->modify( null, 'mysite_initials', array(), '', '', $value, array() );
        $this->assertSame( 'AL', $value );
    }
}

Siehe Tests für Erweiterungen.

Einfacher: owsimpleoperator #

Wenn Sie viele kleine Operatoren haben, können Sie mit der Erweiterung owsimpleoperator jeden als einfache Methode schreiben; siehe Von einer Erweiterung lernen, Schritt für Schritt.

RAD #

Assistent für Template-Extensions (/setup/templateoperator) schreibt Operatoren, Fetch-Funktionen, Attribut-Operatoren und Template-Funktionen; siehe Mit RAD: ein Template-Operator in fünf Minuten.

Verwandte Seiten #

• Zurück: View-Ergebnisse, der Pfad und das Pagelayout
• Weiter: Fetch-Funktionen
• Von Hand: ein Template-Operator
• Eingebaute Template-Operatoren
• Freie Dokumentation: Diese Seite darf unter der GNU FDL 1.3 frei kopiert, übersetzt und verbessert werden.