User Tools

Site Tools


de:developer:expression-language:start

Diese Dokumentationsseite ist Mitglied des Entwicklerteils dieses Wikis.

Expression Language / Ausdruckssprache

Allgemeines und zur Geschichte

Die Ausdruckssprache (kurz: EL-Code, engl. Expression Language) ist um November 2009 (genauer Commit ist leider nicht mehr feststellbar) zum Mailer-Projekt dazu gekommen. Sie soll das Einbinden von Daten in Templates z.B. mit Array-Elementen durch kleine, einfache Ausdrücke ersetzen, die für Grafik-Designer sehr einfach zu verstehen sind. Zudem werden damit auch die Templates von PHP-Codeteilen weiterhin freigehalten und der PHP-Code selbst weiter abgebaut, da viele Array-Initialisierungen nun entfallen. Dabei soll weiterhin die Funktionalität und Flexiblität von seitens PHP nicht leiden. Es wird also sehr komplexer PHP-Code hinter kleinen, einfachen EL-Code gekapselt, ohne dabei Einbüsse in Kauf nehmen zu müssen.

Somit ist ein Teil der “Logik” in die Templates gewandert, was auch beim “Kompilieren” der Templates in den Cache-Dateien (siehe Dateien im Verzeichnis inc/cache/_compiled/) zu sehen ist, da dort Funktionsaufrufe eingebunden werden.

Der EL-Code versteht sich als eine Art Template-Sprache, die aber (wie viele andere) nicht zu kompliziert ist und sich nur auf eine Zeile Code beläuft, die mit ein bischen Englischkenntnissen durchaus auch von Nichtprogrammierern verstehbar ist.

Der EL-Code ist zudem sehr flexibel gehalten, so dass z.B. in der englischen Sprache andere PHP-Funktionen verwendet werden können, falls die Standardfunktionen nicht ausreichend sein sollten.

Allgemeine Syntax

Die Syntax der zuletzt hinzugefügten Expression-Language (oder kurz: EL, zu deutsch Ausdruckssprache) ist so einfach wie möglich gehalten, um KISS zu beachten.

Der Ausdruckscode fängt mit einer öffnenden geschwungener Klammer und einem Prozenzeichen an ({%), gefolgt von dem Expression-Tag-Identifier (kurz: ETI) der nur Buchstaben enthält und schliesst mit einem Prozentzeichen und einer schliessenden geschwungenen Klammer (%}). Optionale “Pipe-Through” Funktionen, welche jede beliebe PHP-Funktion oder eigen geschriebene sind, die keinen oder nur einen Parameter erwarten und werden mit einem Komma (,) direkt hinter dem ETI plus den eigentlichen Funktionsnamen angehängt. Die Reihenfolge ist im Gegensatz zu PHP umgekehrt, somit kommt zuerst die innere und dann die äussere Funktion. Optionale Daten werden bei ohne einer “Pipe-Through” Funktion direkt nach dem ETI oder nach der letzten “Pipe-Through” Funktion mit einem Gleichheitszeichen (=) abgetrennt angehängt. Die Daten selbst können auch wieder ein EL-Code sein, jedoch nur einmal. Der EL-Code ist somit nur einmal verschachtelbar, da tiefere Verschachtelungen den Code nur wieder unübersichtlich machen und sich somit leichter Bugs einschleichen.

Der EL-Code kann sowohl in Email- als auch in HTML-Templates (auch JavaScript mit eingeschlossen) eingebunden werden. Auch kann dieser direkt in den ausgegeben Text (siehe Verzeichnis inc/language/) und somit auch an (fast) jeder beliebigen Stelle im PHP-Code eingebunden sein. Es sollte aber dabei beachtet werden, dass der EL-Code “kompiliert” werden muss. Mehr dazu behandelt die Seite für die Template-Engine.

Nach der oben beschriebenen Syntax sind die folgenden Beispiele alle gültig.

Ein simpler, datenloser Ausdruckscode wie in vielen Zeilentemplates gesehen:

Ein Ausdruckscode mit dynamisch eingesetzten Template-Daten:

Beispiel 1: {%pipe,translateComma=$content[points]%}

pipe ist hier ein allgemeiner ETI, der “Pipe-Through” die Daten durch jede angegebene Funktion “hindurchpumpt”, wie z.B. Wasser durch eine Pipeline gepumpt wird. Dies gilt auch für jeden anderen ETI: Jede verwendere Funktion darf maximal einen (es geht auch keinen Parameter) gezwungengen Parameter akzeptieren (weiteren Parameter sind optional zu schreiben, da der EL-Code noch nicht mehr als einen Parameter verarbeiten kann). Bei diesem Beispiel wird ein direkter Datenwert aus der Template-“Variable” $content[points] an die Funktion translateComma() weitergegeben, die die “Rohzahl” in das Format der aktuell ausgewählten Sprache umwandelt.

Beispiel 2:{%user,gender,translateGender=$content[userid]%}

Die direkte Mitglieds-Id aus der Template-Variable $content[userid] wird zum Aufsuchen des Mitglieddatensatzes aus der Tabelle user_data verwendet, um den Dateneintrag gender (Geschlecht, Anrede) zu laden und diesen an die Funktion translateGender() zu übergeben, die den Rohwert in eine von Menschen lesbare Form bringt (wie z.B. “Herr” für M). Stände anstelle von $content[userid] dort ein direktes $userid, wäre die Mitglieds-Id aus der aktuell verwendeten Sitzung verwendet. $userid funktioniert aber nur in Email-Templates, da die Funktion loadEmailTemplate() dies noch als Parameter hat, loadTemplate() jedoch nicht. Jedoch ist der Code-Block in loadEmailTemplate() zum Laden der Mitgliedsdaten veraltet und wird in den kommenden Revision entfernt. Es kann dann wie bei der Funktion loadTemplate() die Mitglieds-Id über das Datenfeld $content an das Template übergeben werden.

Ein Ausdruckscode mit statischen Daten:

Beispiel: {%config,translateComma=points_register%}

Der Expression-Tag-Indicator config deutet an, dass Daten aus der Konfigurationstabelle geladen werden. Es soll dabei der Wert des Konfigurationseintrages points_register geladen und an die Funktion translateComma() übergeben werden, die die “Rohzahl” der Anmeldegutschrift in eine menschenlesbare Form umwandelt (“übersetzt”).

Genauer genommen, wird ein Callback auf die Funktion getPointsRegister() versucht auszuführen, fehlt diese Funktion, wird ein Logbucheintrag erzeugt und der Konfigurationsschlüssel points_register an die Funktion getConfig() übergeben. Mehr zum Thema Wrapper-Funktionen der Version 0.2.1-FINAL dort.

Ein Ausdruckscode mit zwei "Pipe-Through" Funktionen:

Beispiel: {%pipe,getTotalPoints,translateComma=$content[userid]%}

Der ETI pipe ist ein allgemeiner “Pipe-Through” ETI. Die über das Template-Array $content übergebene User-Id wird dabei zuerst an getTotalPoints() und anschließend deren Ausgabe an translateComma() übergeben, damit das Gesamtguthaben des Mitgliedes in ein der Sprache angepasstes Format umgewandelt wird, um dann im Template ausgegeben werden zu können.

Ein Ausdruckscode der Erweiterung ext-user mit dynamischen Daten und einer "Pipe-Through" Funktion:

Beispiel: {%user,gender,translateGender=$userid%}

Der hier verwendete ETI ist user und deutet an, dass dieser Code nur mit installierter Erweiterung ext-user funktionieren wird. Dieser ETI lädt Daten aus der Tabelle user_data nach und zwar des aktuell eingeloggten Users (der gerade den Aufruf des EL-Codes ausgelöst hat). Dieser wird immer $userid angegeben. Mehr dazu aber im Abschnitt zu EL-Daten.

Genauer genommen wird die Spalte gender geladen, welche in codierter Form das Geschlecht bzw. eher Anrede des Mitgliedes darstellt, es ist auch “Firma” auswählbar. Anschliessend wird diese durch die Funktion translateGender() in eine menschenlesbare Form gebracht (da sonst die Rohdaten ausgegeben werden).

Sprachauswahl:

Diese Seite ist auch in den folgenden Sprachen erhältlich: English

de/developer/expression-language/start.txt · Last modified: 2012/11/03 20:52 by quix0r