Velocity directives
A directive is a Velocity keyword starting by a "#", for example "#set", "#if", "#foreach", etc.
Directives can be thought of as "instructions" for handling rendering in a model. They can be used to define variables (#set), apply logical conditions (#if), iterate over collections (#foreach), etc.
1
#set( $name = "Bob" )
2
#foreach( $v in $elements )
3
$v
4
#end
Copied!
To avoid misinterpretations the name of the directive can be bracketed with "{" and "}"
1
#if($x)true#{else}false#end
Copied!
Most used directives
#set
The #set directive is used for setting a value. A value can be assigned to either a simple variable or an object property.
"#set" always defines a "global variable" wherever you use it.
1
#set( $name = "Bob" )
2
#set( $customer.name = "Bob")
3
#set( $user.level = 3 ) ## number literal
4
#set( $a = $b ) ## variable reference
5
#set( $mylist = [ "A", $v, "Z"] ) ## list
Copied!
You cannot set a variable to "null" explicitly
1
#set( $v = null ) ## causes an error
Copied!
NB : if the value to be assigned is null then it will not be assigned!
1
#set( $v = $o.get("abc") )
2
## if get returns null then $v remains unchanged
Copied!
#foreach / #end
The "#foreach" directive is used to loop through a list of objects. Within the "#foreach" directive 2 local variables are created to represent :
- the current item in the loop (you can name it as you want)
- the "$foreach" object providing properties like "count", "index", "hasNext", "first", "last", "parent", "topmost".
The visibility of these variables is only "local" (visible only in the "#foreach" block).
A variable defined with "#set" inside a "#foreach" block remains global (visible outside of the block).
The "$foreach" object is an instance of org.apache.velocity.runtime.directive.ForeachScope.
Examples :
Loop with given values :
1
#foreach ( $item in [1..8] ) ## from 1 to 8
2
. item = $item
3
#end
4
​
5
#foreach ( $item in [3,2,1] ) ## from 3 to 1
6
. item = $item
7
#end
8
​
9
## Everything in a single line
10
#foreach( $item in ['A','B','C','D'] ) ${item}#end
Copied!
Loop with an object (array, list, collection) :
1
#foreach( $attribute in $entity.attributes )
2
$attribute.type $attribute.name
3
#end
Copied!
Map iteration :
1
#set ( $map = {"banana" : "good", "cream" : "bad"} )
2
#foreach($key in $map.keySet() )
3
$key --> $map.get($key)
4
#end
Copied!
Break the current iteration :
1
#foreach ( $item in [1..20] )
2
#if ( $item > 3 ) #break #end
3
. item = $item
4
#end
Copied!
"$foreach.count" loop counter ( 1 to N ) :
1
#foreach ( $item in ["A", "B", "C", "D" ] )
2
. $foreach.count : $item
3
#end
Copied!
"$foreach.index" zero-based index ( 0 to N-1 ) :
1
#foreach ( $item in ["A", "B", "C", "D" ] )
2
. $foreach.index : $item
3
#end
Copied!
"$foreach.hasNext" ( true if not last item ) :
1
#foreach( $customer in $customerList )
2
$customer.Name#if( $foreach.hasNext ),#end
3
#end
Copied!
Nested loops :
It's possible to access outer loops properties by using "$foreach.parent" or "$foreach.topmost"
(e.g. $foreach.parent.index or $foreach.topmost.hasNext).
1
#foreach ( $item1 in ["A", "B", "C", "D" ] )
2
#foreach ( $item2 in [1,2,3 ] )
3
. $foreach.index : $item1 / $item2
4
($foreach.parent.index) ($foreach.topmost.index)
5
#end
6
#end
Copied!
​
#if / #else / #elseif / #end
Conditional output or instructions
Examples :
#if / #end :
1
#if ( $v == 1 ) equals 1 #end
2
​
3
#if ( $v == 1 )
4
equals 1
5
#end
Copied!
#if / #else / #end :
1
#if ( $v == 1 ) equals 1 #else not equals 1 #end
2
​
3
#if ( $v == 1 )
4
equals 1
5
#else
6
not equals 1
7
#end
Copied!
#if / #elseif / #else / #end :
1
#if ( $v == 1 )
2
equals 1
3
#elseif ( $v == 2 )
4
equals 2
5
#else
6
other
7
#end
Copied!
​
#include
The #include directive allows to import a local file at the current position. The file is included "as is" (as a text file, not rendered through the template engine, not parsed).
If more than one file will be included, they should be separated by commas. A variable can be used instead of a literal filename.
Any files to which #include refers must be included under "TEMPLATE_ROOT" ( the "bundle" directory for Telosys ).
Examples :
1
## Include a single file :
2
#include( "myfile.txt" )
3
#include( "include/myfile.txt" )
4
​
5
## Include multiple files :
6
#include( "a.txt", "b.html" )
7
​
8
## Include with variables :
9
#include( $myfile )
10
#include( "header.include", $myfile )
Copied!
​
#parse
The #parse directive allows to import a local Velocity template file.
The file is parsed by the Velocity engine. Only one argument is accepted (only one file for each call, other arguments are ignored). A variable can be used instead of the literal filename.
All the variables defined before the "#parse" call are usable in the parsed file. All the variables defined in the parsed file are usable in the primary file after the "#parse" call.
Any templates to which #parse refers must be included under "TEMPLATE_ROOT" ( the "bundle" directory for Telosys ).
Examples :
1
#parse("foo.vm")
2
#parse($myfile)
3
#parse("include/initvar.vm")
4
## Here we can use variables defined in "initvar.vm"
Copied!
#parse can be used inside "parsed files".
Recursion is permitted (with a condition to stop recursion).
Primary file :
1
#set( $count = 8 )
2
#parse( "foo.vm" )
Copied!
"foo.vm" file with recursive "parse" :
1
#set( $count = $count - 1 )
2
#if( $count > 0 )
3
#parse( "foo.vm" )
4
#else
5
End of recursion.
6
#end
Copied!
​
Other directives
#stop
The #stop directive stops any further rendering and execution of the template. This is true even when the directive is nested within another template accessed through #parse or located in a velocity macro.
The resulting output will contain all the content up to the point the #stop directive was encountered. This is handy as an early exit from a template.
Example :
1
#if ( $v == 12 )
2
#stop
3
#end
Copied!
​
#break
The #break directive stops any further rendering of the current "execution scope".
An "execution scope" can be
- a directive with content : #foreach, #parse, #evaluate, #define, #macro, or #@somebodymacro
- the current template ("root scope").
Unlike #stop, #break will only stop the innermost, immediate scope, not all of them.
Examples :
1
## BREAK at template level (stop template rendering)
2
#break
3
​
4
## BREAK in a single loop
5
#set($mylist = ["A", "B", "C", "D", "E", "F" ])
6
#foreach( $v in $mylist )
7
#if( $foreach.count > 3 )
8
#break
9
#end
10
$foreach.count : $v
11
​
12
## BREAK in a nested loop (break innermost)
13
#set($mylist1 = ["A", "B", "C", "D", "E", "F" ])
14
#set($mylist2 = [1, 2, 3, 4, 5, 6 ])
15
#foreach( $v1 in $mylist1 )
16
#foreach( $v2 in $mylist2 )
17
#if( $foreach.count > 3 )#break
18
#end
19
$foreach.parent.count : $v1 / $foreach.count : $v2
20
#end
21
#end
Copied!
​
#evaluate
The #evaluate directive can be used to dynamically evaluate a statement (piece of Velocity code). This allows to evaluate a string that is created dynamically at render time. '#evalute' works like '#parse' but with content that comes from a variable in memory instead of a file (it's possible to evaluate multiple lines).
Examples :
1
#set($v = 2)
2
#set($statement = '#set($r = $v * 10)' )
3
#evaluate($statement)
4
v : $v
5
statement : $statement
6
r : $r ## r : 20
Copied!
​
#macro
Velocity "macros" allow you to define a portion of VTL code which will then be reusable several times. They are often called "Velocimacro".
Example : basic macro (without argument)
1
#macro( three )
2
#set ( $result = "" )
3
#foreach ( $i in [1..3] ) ${i}#end
4
#end
5
## -------
6
#three()
Copied!
Arguments :
A Velocimacro can take any number of arguments (0 to N arguments). When the Velocimacro is invoked, it must be called with the same number of arguments with which it was defined. Each argument is a local variable and can never be used outside.
Example : macro with 2 arguments
1
#macro( add $a1 $a2 )
2
#set ( $r = $a1 + $a2 )
3
$a1 + $a2 = $r
4
#end
5
## -------
6
#add( 20, 3 )
7
## rendering : 20 + 3 = 23
Copied!
NB : Macros are not functions, they are designed to render and they cannot return a value. But you can simulate a "return value" by setting a variable in the macro and using it after calling the macro or by setting the result as a string.
Example : "Function like call" getting the result as text (with quotes)
1
#macro( add3 $a1 $a2 $a3 )
2
#set ( $r = $a1 + $a2 + $a3)
3
$r## NO EOL
4
#end
5
## -------
6
#set($v = 50)
7
#set( $result = "#add3(10,20,$v)" )
8
result : $result
Copied!
​
#define
The #define directive allows to assign a block of code to a variable. The associated block of code can contain any valid code.
The code associated with a variable by #define is executed when the variable is referenced.
The type of the variable created by #define is org.apache.velocity.runtime.directive.Block$Reference
Example :
1
#define( $block )Hello $who#end
2
#set( $who = 'World!' )
3
$block
Copied!
Differences between "#define" and "#macro" : "
- #macro" accepts parameters so that they provide a context for creation of local variables
- "#define" structure (unless it contains macros) only works with global variables
​
Last modified 7mo ago