About this Guide
This guide is the reference for the Velocity Template Language (VTL). For more information, please also refer to the Velocity User Guide.
References
Variables
Notation:
$ [ ! ][ { ][ a..z, A..Z ][ a..z, A..Z, 0..9, -, _ ][ } ]
Examples:
- Normal notation:
$mud-Slinger_9 - Silent notation:
$!mud-Slinger_9 - Formal notation:
${mud-Slinger_9}
Properties
Notation:
$ [ { ][ a..z, A..Z ][ a..z, A..Z, 0..9, -, _ ]* .[a..z, A..Z ][ a..z, A-Z, 0..9, -, _ ]* [ } ]
Examples:
- Regular Notation: $customer.Address
- Formal Notation: ${purchase.Total}
Methods
Notation:
$ [ { ][ a..z, A..Z ][ a..z, A..Z, 0..9, -, _ ]* .[ a..z, A..Z ][ a..z, A..Z, 0..9, -, _ ]*( [ opional parameter list... ] ) [ } ]
Examples:
- Regular Notation: $customer.getAddress()
- Formal Notation: ${purchase.getTotal()}
- Regular Notation with Parameter List: $page.setTitle( "My Home Page" )
VTL Properties can be used as a shorthand notation for VTL Methods that take get and set. Either $object.getMethod() or $object.setMethod() can be abbreviated as $object.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.
Directives
#set - Establishes the value of a reference
Format:
#set( $ref = [ ", ' ]arg[ ", ' ] )
Usage:
- $ref - The LHS of the assignment must be a variable reference or a property reference.
- arg - The RHS of the assignment, arg is parsed if enclosed in double quotes, and not parsed if enclosed in single quotes. If the RHS evaluates to null , it is not assigned to the LHS.
Examples:
- Variable reference: #set( $monkey = "bill" )
- String literal: #set( $monkey.Friend = "monica" )
- Property reference: #set( $monkey.Blame = $whitehouse.Leak )
- Method reference: #set( $monkey.Plan = $spindoctor.weave($web) )
- Number literal: #set( $monkey.Number = 123 )
- Range operator: #set( $monkey.Numbers = [1..3] )
- Object array: #set( $monkey.Say = ["Not", $my, "fault"] )
The RHS can also be a simple arithmetic expression, such as:
- Addition: #set( $value = $foo + 1 )
- Subtraction: #set( $value = $bar - 1 )
- Multiplication: #set( $value = $foo * $bar )
- Division: #set( $value = $foo / $bar )
- Remainder: #set( $value = $foo % $bar )
#if / #elseif / #else - output conditional on truth of statements
Format:
#if( [condition] ) [output] [ #elseif( [condition] ) [output] ]* [ #else [output] ] #end
Usage:
- condition - If a boolean, considered true if it has a true false; if not a boolean, considered true if not null.
- output - May contain VTL.
Examples:
- Equivalent Operator: #if( $foo == $bar )
- Greater Than: #if( $foo > 42 )
- Less Than: #if( $foo < 42 )
- Greater Than or Equal To: #if( $foo >= 42 )
- Less Than or Equal To: #if( $foo <= 42 )
- Equals Number: #if( $foo == 42 )
- Equals String: #if( $foo == "bar" )
- Boolean NOT: #if( !$foo )
#foreach - Loops through a list of objects
Format:
#foreach( $ref in arg ) statement #end
Usage:
- $ref - The first variable reference is the item.
- arg - May be one of the following: a reference to a list (i.e. object array, collection, or map), an array list, or the range operator.
- statement - What is output each time Velocity finds a valid item in the list denoted above as arg . This output is any valid VTL and is rendered each iteration of the loop.
Examples of the #foreach(), omitting the statement block :
- Reference: #foreach ( $item in $items )
- Array list: #foreach ( $item in ["Not", $my, "fault"] )
- Range operator: #foreach ( $item in [1..3] )
Velocity provides an easy way to get the loop counter so that you can do something like the following:
The default name for the loop counter variable reference, which is specified in the velocity.properties file, is $velocityCount. By default the counter starts at 1, but this can be set to either 0 or 1 in the velocity.properties file. Here's what the loop counter properties section of the velocity.properties file appears:
#include - Renders local file(s) that are not parsed by Velocity
Format:
#include( arg[, arg2, ... argn] )
- arg - Refers to a valid file under TEMPLATE_ROOT.
Examples:
- String: #include( "disclaimer.txt", "opinion.txt" )
- Variable: #include( $foo, $bar )
#parse - Renders a local template that is parsed by Velocity
Format:
#parse( arg )
- arg - Refers to a template under TEMPLATE_ROOT.
Examples:
- String: #parse( "lecorbusier.vm" )
- Variable: #parse( $foo )
Recursion permitted. See parse_directive.maxdepth in velocity.properties to change from parse depth. (The default parse depth is 10.)
#stop - Stops the template engine
Format:
#stop
Usage:
This will stop execution of the current template. This is good for debugging a template.
#macro - Allows users to define a Velocimacro (VM), a repeated segment of a VTL template, as required
Format:
#macro( vmname $arg1 [ $arg2 $arg3 ... $argn ] ) [ VM VTL code... ] #end
- vmname - Name used to call the VM ( #vmname )
- $arg1 $arg2 [ ... ] - Arguments to the VM. There can be any number of arguments, but the number used at invocation must match the number specified in the definition.
- [ VM VTL code... ] - Any valid VTL code, anything you can put into a template, can be put into a VM.
Once defined, the VM is used like any other VTL directive in a template.
VMs can be defined in one of two places:
- Template library: can be either VMs pre-packaged with Velocity or custom-made, user-defined, site-specific VMs; available from any template
- Inline: found in regular templates, only usable when velocimacro.permissions.allowInline=true in
velocity.properties.