Einführung

Das Templateengine mag auf den ersten Blick (und auch auf den zweiten und dritten) Blick etwas gewöhnungsbedürftig sein. Das Templatesystem ist historisch bedingt so wie es ist (das Templatesystem selbst existiert bereits länger als DS und war ursprünglich für php3 ausgelegt). Da die Templates von DS für dieses System geschrieben sind und das Templatesystem gut mit dem Rest des Frameworks harmoniert wird es sich auch nicht allzu bald ändern.

Aufbau

Das Templatesystem besteht aus 5 Teilen.

• Dem TemplateEngine
• Dem Template-Compiler
• Den Templates
• Den nach java compilierten Templates
• Den Codemodulen, welche das Template festlegen und benutzen

Ablauf

1. Template zu Javacode compilieren
2. Compiliertes Template zu Bytecode compilieren
3. Im Modul den Namen des Templates festlegen
4. Im Modul durch Aufruf von Funktionen des Templateengines Templateblöcke initialisieren, Variablen setzen und Blöcke schreiben

Begriffserklärungen

Modul

Meint eine beliebige Klasse, welche das Templateengine benutzt. In DS handelt es sich in der Regel um eine unter net.driftingsouls.ds2.server.modules abgelegte Klasse

Templates

Templates sind nichts anderes als (HTML-)Text angereichert mit Variablen, Templateblöcken, Kontrollblöcken und Funktionsaufrufen

Templateblöcke

Templateblöcke sind gekennzeichnete Abschnitte innerhalb eines Templates. Solche Abschnitte können extrahiert und in beliebige Variablen innerhalb des Templates (wiederholt) eingefügt werden.

Templatefunktionen

Templatefunktionen sind Funktionen, welche zur Kompilierzeit ausgeführt werden. Diese Funktionen generieren beim Aufruf Templatecode, welcher an ihrer Stelle ins Template eingefügt werden

Templatevariablen

Bezeichnet Platzhalter, welche vom Modul aus gefüllt werden können

Benutzung von Templates

Im folgenden auftauchender Beispielcode geht davon aus, dass es sich um ein von DSGenerator abgeleiteten Code handelt (für Klassen unter net.driftingsouls.ds2.server.modules der Regelfall).

Zu aller erst muss das zu verwendende Template festgelegt werden. Dies geschieht über den Aufruf setTemplate(MeinTemplate.html) im Konstruktor. Das Templateengine wird anschliessend initalisiert und das Template geladen. Das Template erhält die ID _MEINTEMPLATE (Name der Datei ohne Endung in Großbuchstaben mit _ als Prefix). Zu beachten ist, dass hier zwar ein Dateiname angegeben wird, jedoch die Datei lediglich in Bytecode-Form vorliegen muss. Der Dateiname wird dabei automatisch in einen Klassennamen ueberfuehrt.

Nach der Initalisierung kann an jeder Stelle im Quellcode mittels getTemplateEngine() auf die Instanz des Templateengines zugegriffen werden.

Um eine Ausgabe zu erzeugen ist nun prinzipiell kein weiterer Schritt notwendig, da das System automatisch nach Abarbeitung aller Actions das Template ausgibt. Da jedoch ein Template ohne dynamische Elemente recht sinnfrei ist nun die verschiedenen Templateelemente:

Templatevariablen

Das einfachste Templatelement ist die Variable. Eine Variable kann vom Modul mit einem Wert gefüllt werden. Die Syntax im Template sieht wie folgt aus:

{variablenname}

Um eine Variable mit einem Wert zu füllen existiert die Funktion set_var des TemplateEngines?. Diese akzeptiert sowohl eine einzelne als auch mehrere Variablen/Wert-Kombinationen auf einmal.

getTemplateEngine().set_var("variablenname1", wert1, "variablenname2", wert2, "variablenname3", wert3);

Hinweis: Das Templateengine konvertiert automatisch alle Werte in Strings. Es können daher beliebige Objekte als Werte eingesetzt werden.

if-then-else

Das Templateengine erlaubt neben Templatevariablen auch if und else-Blöcke. Die Bedingung kann dabei entweder nur eine Templatevariable (es wird geprüft, ob diese Variable wahr ist) oder eine einfache Bedingung sein.

Die Syntax lautet wie folgt:

{if Variablenname}

{/endif}

oder:

{if Variablenname}

{else}

{/endif}

Hinweis: Es gibt kein elseif

Bedingungen in If-Statements

Das Templatesystem unterstützt nur sehr rudimentäre Bedingungen in If-Statements (wenn jemand dies ändern möchte - nur zu). Es geht grob gesagt nur folgendes:

• Test ob eine Variable wahr ist (String nicht leer, Boolean true, Zahl ungleich 0. siehe TemplateEngine.isVarTrue(String)
• Test ob eine Variable nicht wahr ist (Negation). Dabei wird dem Variablennamen ein ! vorran gestellt. Zu beachten ist, dass zwischen ! und Variablennamen ein Leerzeichen sein musss
• Vergleich mit einer Zahl (geht logischerweise nur, wenn die Variable eine Zahl enthält oder sich zu einer konvertieren lässt). Nach dem Variablennamen muss dazu der Vergleichsoperator (Alle in Java gültigen Vergleichsoperatoren für Zahlen sind möglich) und danach der Wert geschrieben werden. Vor und nach dem Operator muss ein Leerzeichen stehen. Beispiel

  {if Variablenname >= 0.1} ... {/endif}
  

Templateblöcke

Templateblöcke sind Templateabschnitte, welche wiederholt ins Template geschrieben werden sollen. Wie oft und wohin sie geschrieben werden sollen legt dabei das Modul fest.

Der Ablauf sieht wie folgt aus:

1. Block aus dem Template extrahieren
2. An der Position im Template eine festgelegte Variabe schreiben (nicht den Inhalt der Variable, sondern die Variable, welche anschliessend ein Wert zugewiesen bekommen kann).
3. Den Block 0-n Mal in eine oder mehrere Templatevariablen schreiben. Der Inhalt des Blocks wird dabei bei jedem Schreibvorgang ausgewertet (d.h. Variablen werden die Werte zugewiesen, if-Statements werden ausgewertet usw).

Die Syntax eines Blocks im Template:

<!-- BEGIN blockname -->
 Text innerhalb des Blocks
<!-- END blockname -->

In einen Templateblock können dabei weitere Blöcke und andere Templateanweisungen stehen.

Im Modul wird ein Block wie folgt benutzt:

Initalisierung eines Blocks

getTemplateEngine().set_block("parentid", "blockid", "Ersatzvariablenname");

Die Parent-ID ist dabei die ID des Elternblocks oder, wenn es keinen Elternblock gibt, die ID der Template-Datei (siehe Oben). Block-ID ist die ID die der Block bekommen soll. Ersatzvariablenname ist der Name, den die Variable bekommen soll, welche an Stelle des Blocks ins Template gesetzt werden soll. Der Block befindet sich anschliessend separat vom Template im Speicher. Das Template selbst hat keine Referenzen mehr auf den Block.

Einsetzen eines Blocks in eine Templatevarable

getTemplateEngine().parse("Variablenname", "blockid", append);

Der Variablenname ist der Name der Variable, in der der Block geschrieben werden soll. Block-ID ist die ID des zu schreibden Blocks. Append ist ein Boolean und legt fest ob der alte Inhalt der Variable überschrieben (false) oder der neue am Ende der Variable angehangen werden soll (true).

Templatefunktionen

TODO