You can find velocity mannual from http://velocity.apache.org/engine/devel/user-guide.html.

Here is summarize on how to use velocity.

Velocity Usage:

Velocity is a Java-based template engine. 

We can use velocity to define web page instead of JSP, there are several advantages:

 

1. It permits web page designers to reference methods defined in Java code. Web designers can work in parallel with Java programmers to develop web sites according to the Model-View-Controller (MVC) model, meaning that web page designers can focus solely on creating a well-designed site, and programmers can focus solely on writing top-notch code. 
2. Simplify web page logical and make it more easy to be managed by web-designer
3. Web page written in velocity template can be updated without re-deploy you web application.

 

We can also use velocity to generate other output based on template:

 

1. XML
2. SQL
3. Some other file template with dynamic data by defining them in velocity syntax.

 

Variable Definition:

 

The shorthand notation of a variable consists of a leading "$" character followed by a VTL Identifier. A VTL Identifier must start with an alphabetic character (a .. z or A .. Z). The rest of the characters are limited to the following types of characters:

 

• alphabetic (a .. z, A .. Z)
• numeric (0 .. 9)
• hyphen ("-")
• underscore ("_")

Following definition have different meaning:

$count:

Usage: #set($count=10)

define a variable named "count"

$count-1:

Usage: #set($count-1=10)

define a variable named "count-1". Warning: it is not a evaluation to get the value of $count minus 1.

$count -1:

Usage: #set($count=$count -1)

Error!

Exception : org.apache.velocity.exception.ParseErrorException: Encountered "-1" at...

$count - 1:

Usage: #set($count=$count - 1)

execute an evaluation which get result of $count minus 1.

has same value as "$count + -1"

${count}-1:

Usage: #set($count=${count}-1)

Error!

Get the same error as "$count -1". 

${count}- 1:

Usage: #set($count=${count}- 1)

execute an evaluation which get result of $count minus 1.

has same value as "${count}+ -1"

 

Exception

But if you want to display "10-1" in your output, you can use following template:

#set( $count=10)

${count}-1

#[[

$count-1 will lead to "$count-1", because there is no variable named "count-1";

$count -1 will lead to "10 -1" which has one more space than "10-1".

$!count-1 will lead to " ", because there is no variable named "count-1";

]]#

 

Quiet Reference Notation "!" and conditional logical NOT "!"

When Velocity encounters an undefined reference, its normal behavior is to output the image of the reference. For example, suppose the following reference appears as part of a VTL template.

my email is "$email"

In case there is no variable defined for $email, it will display: my email is "$email".

If you set Quiet Reference Notation as following:

my email is "$!email"

In case there is no variable defined for $email, it will display: my email is "".

But conditional logical NOT is different:

#if(!$email)

I have no email.

#else

my email is "#email"

#end

Note: if only one variable is evaluated to determine whether it is true, like if($email). Which will happen under one of two circumstances: 

 

1. $email is a boolean (true/false) which has a true value, or 
2. $email is NOT a boolean and its value is not null.

#include() vs. #parse():

1. include() can contain a set of files separated by commas, like: include("file1.vm", "file2.vm", ...) But parse() can only contain one file.
2. Velocity does not render variables inside included files, but the variables inside parse file will be rendered.
3. You can use variable to replace filename in both.

Properties reference to Variable

Only references to the attribute equivalents of JavaBean getter/setter methods are resolved (i.e. $foo.Name does resolve to the class Foo's getName() instance method, but not to a public Name instance variable of Foo).  

So please make sure your template refer to JavaBean valid getter/setter method.

JavaBean.java as following:

  public class JavaBean {

private String a;

private String b = "Iamb";

public JavaBean() {

}

public String geta() {

return "Iama";

}

public String getA() {

return "IamA";

}

}

Your template test.vm as following:

  $bean.a

$bean.A

$bean.b

Then you set VelocityContext as following:

  VelocityContext context = new VelocityContext();

context.put("bean", new JavaBean());

PrintWriter writer = new PrintWriter(System.out);

Template template = Velocity.getTemplate("test.vm");

template.merge(context, writer);

You will get the output as following:

Iama

IamA

$bean.b

Normally the property lookup rules as following:

1. geta()
2. getA()
3. get("a")
4. isA()

Directive:

#set:

We can set a variable in velocity with #set directive:

#set($count=10)

literal:

string literals that are enclosed in double quote characters will be parsed and rendered. 

However, when the string literal is enclosed in single quote characters, it will not be parsed

Condition: 

#if(condition1)

...

#elseif(condition2)

...

#else

...

#end 

Loops:

#foreach ($each in $all)

...

#end

you can use #break to stop looping.

velocity.properties:

I would like to discuss velocity.properties and how it control default velocity render behavior.

To be updated later.