This document describes the most important features of the "Velocity Template Language (VTL)". A more detailed view in this issue you can get on the "Velocity-Homepage".
The VTL is a interface between a template and a Cockpit-System Java-Class. The Velocity Engine is used by the Cockpit-Document-Generator in order to provide dynamic Cockpit-Content for reports (see Report Templates).
References refer on variables, properties or methods. References are
determined by the first symbol "$". The next symbols may be any number
of letters("a".."z", "A".."Z"), numbers ("0".."9"), underscore ("_") or
hyphen ("-").
References have a formal notation to differentiate them clearly from other text. In this notation the reference's name is surrounded by curly
braces
(e.g. this is usefull if you want to produce a string concatenation
from a reference and a template-text)
Examples:
$myVar1
${myVar1}
String-References will be printed directly. If a references refers
to another type (like numbers, array lists or complex objects) the
method "toString" is called.
Properties and methods are addressed with the "."-Operator. Please notice that the property "MyProp" is mapped to
the method "getMyProp" by the Velocity-Engine.
References can be passed to methods via call by reference. If a reference "a"
is passed to a method as parameter "b" each modification of reference "b" will
change reference "a" and vice versa. After leaving the method the identifier
"b" will rerepresent the reference it represented before calling the method.
Example:
$myVar1.myProp
$myVar1.myMethod()
$myVar1.setProp( "my content" )
Directives begin with "#" and are used to do something.
The "set-directive" assigns a value to a reference.
Example:
#set ( $myObject = "myValue" )
The following assignments are possible:
| variable reference | #set( $myObject1 = $myObject2) |
| property reference | #set( $myObject3 = $myObject4.meinProp ) |
| method reference (result of the method call) | #set( $myObject5 = $myObject6.getMethod() ) |
| string literal | #set( $myObject7 = "my string" ) |
| number literal | #set( $myObject8 = 12345 ) |
| array list | #set( $myObject9 = ["Value1", "Value2"] ) |
| arithmetic expressions | #set( $myObject10 = $myObject8 + 111 ) |
Note: If the value assignment can not be calculated, the value of the variable will not be altered.
Conditionals are constructed with the "if-directive". If the condition-variable ("$myCondition") is a boolean
the logical value will be directly evaluated. All other objects are true if they have an assigned value (that means
"NULL" equals false).
Example:
#if ( $myCondition )
more instructions
#end
The condition-variable may be an arithmetic ("<", ">", "==") or logical ("||", "&&", "!") expression.
Example:
#if ( $myCondition > 10 )
greater 10
#end
#if ( $myCondition1 && !$myCondition2 )
Condtion1 is fulfilled, Condtion2 not
#end
Condition can enhanced by using "elseif-directive". The last else is realized by the "else-directive".
Example:
#if ( $myCondition1 )
Condtion1 is fulfilled
#elseif ( $myCondition2 )
Condtion2 is fulfilled
#else
no condtion is fulfilled
#end
Loops are realized by the "foreach-directive". These directives loop over all
elements of a given list. The variable "$allElements" covers the list. The variable
"$element" covers only one list-element per loop.
Example:
$allElements = ["Value1", "Value2", "Value3"]
#foreach( $element in $allElements )
$element
#end
... is printed that way ...
Value1
Value2
Value3
The "stop-directive" allows the template designer to stop the execution of the template engine and return.
This is useful for debugging purposes.
Example:
#stop
Macros are used to write new directives (a.k.a. functions) for repeated segements. These directives
also starts with a "#". A macro can take arguments divided by spaces.
Macros have to be defined before first use.
Example:
#macro ( myMacro $arg1 $arg2 )
Instructions
#end
#myMacro( value1 value2 )
Comments allows to document the template-functions. There are single line comments ("##") and
multi-line comments (#*" ... "*#").
Examples:
## single line comment
#*
multi-line
comment
*#
To escape the special meaning of the "$" and "#" character the
"\"-operator is used. All symbols behind "\" will be interpreted
as string.
Example:
\anyText
Example:
\#stop
... is printed that way ...
#stop