Dieses Dokument beschreibt die wesentlichen Merkmale der Velocity Template Language (VTL). Eine detailliertere Beschreibung finden Sie auf der Velocity-Homepage (Englisch).
Die VTL ist die Schnittstelle zwischen einem Template und den Java-Klassen des ARCWAY Cockpit-Systems. Die ARCWAY Cockpit-Dokumenten-Generierung verwendet die Velocity Engine, um Berichte durch dynamische ARCWAY Cockpit-Inhalte zu erweitern (siehe Berichtsvorlagen).
Referenzen verweisen auf Variablen, Attribute oder Methoden. Um Referenzen
eindeutig zu kennzeichen beginnen sie mit einem "$"-Zeichen, gefolgt von einem Buchstaben (a..z, A..Z).
Die folgenden Zeichen können beliebig aus der Menge Buchstaben, Ziffern, Unterstrich und Bindestrich
gewählt werden. Um eine Referenz eindeutig von anderem Ausgabetext abzutrennen kann der Referenzname
in geschweifte Klammern "{}" gefasst werden (dies ist notwendig wenn z. B. ein Wort aus einer Referenz und
einem Template-Text ohne Leerzeichen zusammengesetzt werden soll)
Beispiel:
$meineVariable-1
${meineVariable-1}
Zeichenketten (String-Variablen) können von der VTL direkt dargestellt werden. Wird auf einen anderen Variablentyp verwiesen
(Zahlen, Aufzählungen oder komplexe Objekte) so wird für die Darstellung immer die "toString" Methode aufgerufen.
Attribute und Methoden werden über den "."-Operator angesprochen. Hier ist zu
beachten, dass das Attribut "MeinAttribut" von der Velocity-Engine auf die
Methode "getMeinAttribut" abgebildet wird.
Methoden können Variablen übergeben bekommen. Dies geschieht per Referenzaufruf.
Wird also eine Variable "a" einer Methode als Parameter "b" übergeben, so modifiziert
jede Änderungen der Variablen mit dem Namen "b" auch die Variable mit dem Namen "a"
und umgekehrt. Nach dem Rücksprung aus der Methode steht der Bezeichner "b"
wieder für die Variable, für die er stand, bevor die Methode aufgerufen wurde.
Beispiel:
$meineVariable-1.meinAttribut
$meinVariable-1.meinMethode()
$meinVariable-1.setAttribut( "mein Inhalt" )
Direktiven werden von der VTL genutzt um Anweisungen auszuführen. Um Direktiven eindeutig zu identifizieren wird ihrem Namen ein "#" vorangestellt.
Die "set-Direktive" weißt einer Referenz einen Wert zu.
Beispiel:
#set ( $meinObjekt = "meineWertzuweisung" )
Folgende Wertzuweisungen sind möglich:
| Variablen-Referenz | #set( $meinObjekt-1 = $meinObjekt-2) |
| Attribut-Referenz | #set( $meinObjekt-3 = $meinObjekt-4.meinAttribut ) |
| Methoden-Referenz (Ergebnis des Methodenaufrufs) | #set( $meinObjekt-5 = $meinObjekt-6.getMethode() ) |
| Zeichenkette | #set( $meinObjekt-7 = "meine Zeichenkette" ) |
| Zahl | #set( $meinObjekt-8 = 12345 ) |
| Aufzählung | #set( $meinObjekt-9 = ["Wert1", "Wert2"] ) |
| arithmentische Ausdrücke | #set( $meinObjekt-10 = $meinObjekt-8 + 111 ) |
Achtung: Wenn ein zugewiesener Ausdruck nicht ermittelt werden kann, bleibt der Wert der Variable unverändert.
Bedingungen werden mit der "if-Direktive" konstruiert. Ist die Bedingungsvariable ("$meineBedingung") vom
vom Typ Boolean, so wird der logische Wert direkt ausgewertet. Alle anderen Variablentypen sind wahr, wenn
ihnen ein Wert zugewiesen wurde (d. h. "NULL" entspricht falsch).
Beispiel:
#if ( $meineBedingung )
weitere Anweisungen
#end
Die Bedingungsvariable kann mit arithmetischen ("<", ">", "==") und logischen ("||", "&&", "!") Operatoren verknüpft werden.
Beispiele:
#if ( $meineBedingung > 10 )
Bedingung ist größer 10
#end
#if ( $meineBedingung1 && !$meineBedingung2 )
Bedingung1 ist erfüllt und Bedingung2 ist nicht erfüllt
#end
Bedingungen können mit der Direktive "#elseif" weiter verzweigt werden. Ein Sonst-Zweig
wird mit Hilfe von "#else" definiert.
Beispiel:
#if ( $meineBedingung1 )
Bedingung1 ist erfüllt
#elseif ( $meineBedingung2 )
Bedingung2 ist erfüllt
#else
keine Bedingung erfüllt
#end
Schleifen werden mit der "foreach-Direktive" realisiert. Diese Direktive durchläuft alle
Elemente einer gegeben Liste. Die Variable "$alleElemente" enthält diese Liste.
Die Variable "$element" enthält in jedem Durchgang immer ein Element der Liste.
Beispiel:
$alleElemente = ["Wert1", "Wert2", "Wert3"]
#foreach( $element in $alleElemente )
$element
#end
... wird wie folgt dargestellt ...
Wert1
Wert2
Wert3
Die Abarbeitung des Templates kann mit Hilfe der "stop-Direktive" gestoppt werden.
Diese Direktive ist nur sinnvoll um Fehler zu finden.
Beispiel:
#stop
Immer wiederkehrende Funktionen können in Makros zusammengefasst werden. Diese
sind Direktiven und müssen sich daher auch an die o. g. Namenskonvention halten.
Einem Makro können (durch Leerzeichen getrennte) Variablen übergeben werden, sofern
diese in der Makro-Definition definiert sind. Makros müssen immer vor dem
ersten Makroaufruf definiert werden.
Beispiel:
#macro ( beispielmacro $arg1 $arg2 )
Anweisungen
#end
#beispielmacro( wert1 wert2 )
Kommentare sollten dazu genutzt werden um die Template-Funktionalität zu
dokumentieren. Die VTL bietet dafür die Möglichkeit einzeilige ("##") und
mehrzeilige ("#*" ... "*#") Kommentare zu verfassen.
Beispiel:
## einzeiliger Kommentar
#*
mehrzeiliger
Kommentar
*#
Um Zeichenfolgen darzustellen, die von der Velocity-Engine als Referenzen
oder Direktiven interpretiert werden würden, gibt es den "\"-Operator.
Alle Zeichen, die dem "\" folgen werden als String interpretiert.
Beispiel:
\beliebigerText
Beispiel:
\#stop
... wird wie folgt dargestellt ...
#stop