Velocity jumpstart

SiteVision portlets often uses Apache Velocity for rendering output. Velocity is a markup language that has a small footprint, a simple syntax and good performance.

This page briefly shows you the basics of Velocity.

Accessing objects

When you write code in a Velocity template, you have access to all objects available in the Velocity context. Each object is registered with a name and you use the name (prefixed with a dollar-sign) to access the object.

For example: if an instance of a java.util.ArrayList is registered as "myList" in the context, you access it as follows in your Velocity template:

$myList

Invoking methods

You invoke methods as you would in Java.

For example: if an instance of a java.util.ArrayList is registered as "myList" in the context, you invoke the size method as follows in your Velocity template:

$myList.size()

Invoking no-args get methods

If you invoke a get-method that has no arguments, you can use the short-name notation Velocity provides.

For example: if you want to call the getThing method of an object that is registered as "anObject" in the Velocity context you can do so in three ways:

$anObject.getThing()

The one above is obvious. Just use the full method name. The two below is using the short-name notation to execute the getThing method:

$anObject.Thing
$anObject.thing

Note that you will get into trouble if anObject actually has a public member called Thing or thing and you use the short-name notation!

Comments

All lines that starts with two ## are considered as single line comments. For example:

## This is a single line comment

Comments that span multiple lines are demarcated with #* and *#. For example:

#*
This is a multiple
line comment
*#

Selections

Selections in Velocity is done using the familiar if/elseif/else idiom. For example:

#if ($something == 1)
  ...
#elseif ($somethingIsTrue)
  ...
#else
  ...
#end

Note that #elseif is one word (i.e. Not #else if). Also note that the end of a selection statement is demarcated with an #end

Iterations

Iterations in Velocity is done with the foreach construct. Hence, to iterate in Velocity you must have some kind of collection/iterator.

An example of how to iterate the items in a java.util.ArrayList registered as "myList" in the context:

#foreach ($anItem in $myList)
$anItem.doSomething()
...
#end

Note that you specify the name of the item (i.e. $anItem above) variable as you like (a variable name can only contain characters ['a'..'z', 'A'..'Z', '0'..'9', '-', '_']). Also note that the end of the foreach construct is demarcated with an #end

Assigning objects and values

Variables is assigned using the set construct. For example:

#set ($myThing = 1)

You can also use the actual value in assignments (once it is assigned) and do simple mathematical operations. For example:

#set ($count = 0)
#foreach ($anItem in $myList)
#set ($count = $count + 1)
...
#end

$count should be equal to $myList.size()

Caveats

No null assignments

You can not assign a null value to a Velocity object. If you try to assign or use a null value, the previous value will be used instead!

For example, the result of:

#set ($myVariable = "Hello")
My variable: $myVariable <br />
#set ($myVariable = $anObject.thisMethodReturnsNull())
My variable: $myVariable

will be:

My variable: Hello <br />
My variable: Hello

No parsing of assignments enclosed in single quotes

If you assign something enclosed in single quotes, it will not be parsed.

For example, the result of:

#set ($myVariable = '$anObject.Thing')
Hello $myVariable

will be:

Hello $anObject.Thing

Tips and trix

Check for null values

You can do a simple if-statement to check if a value exist. For example:

#if ($anObject)
$anObject.xxx
#end

Ensure no null value

You can use the ! operator to ensure nothing will be printed if it is null

$!anObject.doSomething()

An example: If you have a link object (named "link" on the context) and it has no title (i.e. getTitle method returns null). If your Velocity template look like this:

<a href="..." title="$link.Title">A link</a><br />
<a href="..." title="$!link.Title">A link again</a>

Then the rendered result will be this:

<a href="..." title="$link.Title">A link</a><br />
<a href="..." title="">A link again</a>

E.g. When Velocity doesn't find what you specify, your statement will be printed 'as-is'!

Explicit statement

Sometimes you have to explicitly tell Velocity where your statement really ends. This is done with curly brackets.

For example if you want to call the thing method on anObject and some text is directly after your statement:

${anObject.Thing}text

(Without brackets Velocity would look for a method or variable named "Thingtext" and fail)

Null check/assignment workaround

As stated above - Velocity ignores null assignments. A common strategy to work around this is to use the "Check for null value" strategy stated above. You sometimes end up with code like this:

## Ensure doStuff() returns non-null value
#if ($myObject.doStuff())
   #set ($thing = $myObject.doStuff())
   $thing.doThis()
   $thing.doThat()
   ...
#end

The downside with this strategy is that it requires two subsequent method invocations. That is of course a bad thing if the method does costly things.

Tip! The ScriptUtil Opens in new window. interface of the SiteVision Public API allows you to do it more efficiently using the getNonNullValue method (available since SiteVision 2.6.2). The code above can be better utilized as:

## Assign thing - Boolean.FALSE if result is null
#set ($thing = $scriptUtil.getNonNull(${myObject.doStuff()}))

#if ($thing)
   $thing.doThis()
   $thing.doThat()
   ...
#end

Velocity and XHTML

Ensure that string demarcation characters in method arguments does not collide with mandatory characters in XHTML. A simple solution for this problem is to use single quotes instead of quotes. For example:

Resources

Apache velocity User guide

External link, opens in new window.

Last updated: 2010-10-27

Custom templates

se-sto-pio-sv5-1.sitevision-cloud.net
18.222.163.31