Apache Velocity Language Basics
All VTL statements, begins with the
# character. For rendering process: the Velocity Templating Engine will:
search through your web page to find all
Then determine which mark the beginning of VTL statements, and which of the
#characters that have nothing to do with VTL.
It is recommended to start each VTL statement on a new line.
There are three types of references in the VTL:
In VTL, References begin with $ and are used to get something. Directives begin with # and are used to do something.
All variables/references in VTL begins with the
$ character,followed by a VTL Identifier.
- A VTL Identifier must start with an alphabetic character (i.e. a to z case insensitive). The rest of the characters are limited to the following types of characters: alphabetic, numeric,
In VTL, the variable can get its value from either a set directive in the template, or from the Java code. Example: for
#set( $foo = "bar" ),
"bar" will replace all
$foo variables in VTL.
Once a value has been assigned to a variable, you can reference the variable anywhere in your HTML document. Example:
<html> <body> #set( $foo = "Velocity" ) Hello $foo World! </body> <html>
String values are always enclosed in quotes, either single or double quotes:
Single quotes will ensure that the quoted value will be assigned to the reference as is.
Double quotes allow you to use velocity references and directives to interpolate
"Hello $name", the
$namewill be replaced by the referenced value.
Properties have a distinctive format.
The shorthand notation consists of a leading
$ character followed a VTL Identifier, followed by a dot character
. and another VTL Identifier
$customer.Address has two meanings:
VTL should look in the hashtable named as
customer, then return the value associated with the key
VTL should find a referring to a method called
Methods are references that consist of a leading
$ character followed a VTL Identifier, followed by a VTL Method Body.
A VTL Method Body consists of a VTL Identifier followed by an left parenthesis character
(, followed by an optional parameter list, followed by right parenthesis character
$customer.getAddress() $purchase.getTotal() $page.setTitle( "My Home Page" ) $person.setAttributes( ["Strange", "Weird", "Excited"] )
a shorthand notation for VTL Methods
In the example above, The property
$customer.Address has the exact same effect as using the method
It is generally preferable to use a Property when available.
The main difference between Properties and Methods is that you can specify a parameter list to a Method.
Array as Lists
As of Velocity 1.6, all array references are treated as fixed-length lists. User can call
java.util.List methods on array references. Example:
$myarray.isEmpty() $myarray.size() $myarray.get(2) $myarray.set(1, 'test')
From Velocity 1.6, setter methods can have different parameter list:
$sun.setPlanets('Earth', 'Mars', 'Neptune') $sun.setPlanets('Mercury') $sun.setPlanets() ## Will just pass in an empty, zero-length array
Other Syntax Information
In VTL, A single line comment begins with
## and finishes at the end of the line. Example:
## This is a single line comment.
Multi-line comments, which begin with
#* and end with
*#, are available to handle this scenario.
This is text that is outside the multi-line comment. Online visitors can see it. *# Thus begins a multi-line comment. Online visitors won't see this text because the Velocity Templating Engine will ignore it. *# Here is text outside the multi-line comment; it is visible.
User can also set javadoc-style annotation in VTL comment block:
#** This is a VTL comment block and may be used to store such information as the document author and versioning information: @author @version 5 *#