Velocity Command Reference

A command adds intelligence to your page. To get started with velocity you only need to know a few basic commands. Complete and more detailed information on velocity can be found in Apache's Velocity User Guide. The application engine uses the latest version 1.7.

#set

The #set command defines and/or assigns a variable. To define a variable $text, and assign a value "Hello World" to it, just use:

#set($text = "Hello world")

To define a numerical value use:

#set($number = 42)

You can also use a variable to store a list of values:

#set($colors = ["red","blue","purple","yellow"])

To retrieve values from a list use:

$colors.get(0)

Please be aware that the first item in a list is always retrieved with 0 (zero)!

Finally, two examples of creating a list of numbers:

#set($list1 = [1,2,3,4,5])
#set($list2 = [1..5])

 

#if

The #if command defines a condition. It always has to be closed with an #end command. You can handle conditions in combination with #else and #elseif.

#if($var == 1)
    first text
#elseif($var == 2)
    second text
#else
    default text
#end

 

#foreach

The #foreach command defines an iteration. This is the only way in Velocity to create a loop. The syntax is:

#foreach($var in $list)
    ... do something with $var ...
#end

A simple use of a loop is:

#set($loop = [1,2,3,4,5])
#foreach($i in $loop)
    $i
#end

Sometimes you may wish to keep to track of the iterations during a loop. Velocity automatically does this for you using the $foreach variable. You can call various methods on the $foreach variable and it's local to the loop. Below an example of a $foreach.count within a nested loop.

#foreach($i in ["a","b","c"])
Main loop $foreach.count:
#foreach($i in [1..3])
    $foreach.count,
#end
#end

Output is:

Main loop 1:1,2,3,
Main loop 2:1,2,3,
Main loop 3:1,2,3,

Various other methods include $foreach.hasNext, $foreach.last, $foreach.first, $foreach.index (a zero-based counter). It is also possible to reference the $foreach variable from within a nested loop with $foreach.parent or $foreach.topMost for the most outer loop.

#break

This command can be used to break out of a loop on a certain condition.

#stop

The #stop command stops the evaluation of the page. This can be helpful in debugging.

Structural commands

These command may be used to structure your code better and use pieces of code repeatedly.

#include

The #include command includes an external file literally. You can use this to include html or text in a page:

#include("/a.txt")

You can include multiple files:

#include("/a.txt", "/b.txt", "/c.txt")

You can also use a variable as a file name:

#include($textfile)

 

#parse

The #parse command includes a file that will be evaluated by the Velocity handler. The syntax is the same as #include. You can use this when you want to use the same Velocity code in several places without having to duplicate it. Note that it is also possible to parse so-called private velocity files (.pm extension) that cannot be accessed with an url (or any file containg velocity code for that matter).

#parse('/a-velocity-file.vm')

 

#evaluate

The #evaluate command is similar to parse in that it evaluates the code, however instead of retreiving the code form a file, it evaluates any given string.

#evaluate('This is $foo. #if($bar) Hello #end')

Be aware that evaluate performs considerably slower than #parse when used repeatedly, since once a file is parsed by velocity, the interpreted (or compiled) code is stored in a cache so when the same file is parsed again, it will be executed more quickly, provided the parsed file hasn't changed of course. Evaluate however, will always interpret the given string, since velocity has no way of nowing wether the string is the same as a previous evaluate.

#define 

Define is a handy way to avoid code repetition. It acts the same as parse however it is defined in the same file as where it is used. The #define assigns the code to a variable of your choice.

#define($foo)
    Hello $bar!
#end
#set($bar = "World")
$foo

The code of the define is evaluated within the current context. Here is the output:

Hello World!

 

#macro

A macro is very much like a define. It may be created and used in a file or placed in a library so that it will be available globally. Furthermore, variables may be passed to a macro that are local to its context.

#macro(hello $foo)
Hello $foo!
#end
#set($foo = "monkey")
#hello("World")<br>
Foo is still $foo

Note that by calling the macro, the content of $foo isn't changed in the global context.

Hello World
Foo is still monkey

As a rule of thumb, macros are used when you need a piece of code to be available globally (meaning it can be used be any other velocity page) or when a local context is needed for example in recursion. 

Note that is is also possible to assign the results of these commands to a variable. Below are two examples:

#set($parseResult = "#parse('/myfile.vm')")
#set($defineResult = "$defineVariable")

 

#try

Normally, when an exception occurs during the execution of your script, the execution of the script will halt, and an error message will be displayed. This behaviour may in certain cases be undesired, for instance when you want your script to continue executing, possible taking some measures based on the nature of the exception. To this purpose you can make use of the try block. The basic form is:

#try($exception)
    <code, possibly causing an exception>
#end

 All code between the #try and #end is executed and rendered until an exception occurs. Once this is the case, execution of your script will resume directly after te try block, and the variable $exception (this can of course be any variable) will contain an object of class ExceptionInfo, containing information on the nature of the exception, and the location of occurrence: script, line number, and column. If no exception occurs, any previous valie in the variable is cleared.

Example:

#try($e)
    #set($myname = $record.get("My name")) ## The field 'My name' does not exist!
#end

#if($e)
    <span class="error"> Something went wrong: $e.getExceptionMessage() </span>
#else
    <span class="success"> Everything went according to plan MWUHAHAHA </span>
#end

 

Read the Quick Velocity Tutorial for more information and examples.