|
About
Community
Docs
Tools
Comparisons
Site Translations
|
|
About this Guide
|
The Velocity User Guide is intended to help page designers and
content providers get acquainted with Velocity and the syntax of its
simple yet powerful scripting language, the Velocity Template
Language (VTL). Many of the examples in this guide deal with using
Velocity to embed dynamic content in web sites, but all VTL examples
are equally applicable to other pages and templates.
Thanks for choosing Velocity!
|
|
|
What is Velocity?
|
Velocity is a Java-based template engine. 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. Velocity
separates Java code from the web pages, making the web site more
maintainable over the long run and providing a viable alternative to
Java Server Pages
(JSPs) or PHP.
Velocity can be used to generate web pages, SQL, PostScript and
other output from templates. It can be used either as a standalone
utility for generating source code and reports, or as an integrated
component of other systems. When complete, Velocity will provide
template services for the Turbine web application
framework. Velocity+Turbine will provide a template service that
will allow web applications to be developed according to a true MVC
model.
|
|
|
What can Velocity do for me?
|
|
The Mud Store Example
|
Suppose you are a page designer for an online store that specializes
in selling mud. Let's call it "The Online Mud Store". Business is
thriving. Customers place orders for various types and quantities of
mud. They login to your site using their username and password,
which allows them to view their orders and buy more mud. Right now,
Terracotta Mud is on sale, which is very popular. A minority of your
customers regularly buys Bright Red Mud, which is also on sale,
though not as popular and usually relegated to the margin of your
web page. Information about each customer is tracked in your
database, so one day the question arises, Why not use Velocity to
target special deals on mud to the customers who are most interested
in those types of mud?
Velocity makes it easy to customize web pages to your online
visitors. As a web site designer at The Mud Room, you want to make
the web page that the customer will see after logging into your
site.
You meet with software engineers at your company, and everyone has
agreed that $customer will hold information pertaining to
the customer currently logged in, that $mudsOnSpecial will
be all the types mud on sale at present. The $flogger
object contains methods that help with promotion. For the task at
hand, let's concern ourselves only with these three references.
Remember, you don't need to worry about how the software engineers
extract the necessary information from the database, you just need
to know that it works. This lets you get on with your job, and lets
the software engineers get on with theirs.
You could embed the following VTL statement in the web page:
 |
|
|
|
<HTML>
<BODY>
Hello $customer.Name!
<table>
#foreach( $mud in $mudsOnSpecial )
#if ( $customer.hasPurchased($mud) )
<tr>
<td>
$flogger.getPromo( $mud )
</td>
</tr>
#end
#end
</table>
|
|
|
|
|
The exact details of the foreach statement will be
described in greater depth shortly; what's important is the impact
this short script can have on your web site. When a customer with a
penchant for Bright Red Mud logs in, and Bright Red Mud is on sale,
that is what this customer will see, prominently displayed. If
another customer with a long history of Terracotta Mud purchases
logs in, the notice of a Terracotta Mud sale will be front and
center. The flexibility of Velocity is enormous and limited only by
your creativity.
Documented in the VTL Reference are the many other Velocity
elements, which collectively give you the power and flexibility you
need to make your web site a web presence. As you get more
familiar with these elements, you will begin to unleash the power of
Velocity.
|
|
|
|
|
Velocity Template Language (VTL): An Introduction
|
The Velocity Template Language (VTL) is meant to provide the
easiest, simplest, and cleanest way to incorporate dynamic content
in a web page. Even a web page developer with little or no
programming experience should soon be capable of using VTL to
incorporate dynamic content in a web site.
VTL uses references to embed dynamic content in a web site,
and a variable is one type of reference. Variables are one type of
reference that can refer to something defined in the Java code, or
it can get its value from a VTL statement in the web page
itself. Here is an example of a VTL statement that could be embedded
in an HTML document:
This VTL statement, like all VTL statements, begins with the
# character and contains a directive: set. When an
online visitor requests your web page, the Velocity Templating
Engine will search through your web page to find all #
characters, then determine which mark the beginning of VTL
statements, and which of the # characters that have nothing
to do with VTL.
The # character is followed by a directive, set.
The set directive uses an expression (enclosed in brackets)
-- an equation that assigns a value to a variable.
The variable is listed on the left hand side and its value on the
right hand side; the two are separated by an = character.
In the example above, the variable is $a and the value is
Velocity. This variable, like all references, begins with
the $ character. Values are always enclosed in quotes; with
Velocity there is no confusion about data types, as only strings
(text-based information) may be passed to variables.
The following rule of thumb may be useful to better understand how
Velocity works: References begin with $ and are
used to get something. Directives begin with # and are used
to do something.
In the example above, #set is used to assign a value to a
variable. The variable, $a, can then be used in the
template to output "Velocity".
|
|
|
References
|
There are three types of references in the VTL: variables,
properties and methods. As a designer using the VTL, you and your
engineers must come to an agreement on the specific names of
references so you can use them correctly in your templates.
Everything coming to and from a reference is treated as a String
object. If there is an object that represents $foo (such as
an Integer object), then Velocity will call its
.toString() method to resolve the object into a String.
Variables
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 ("_")
Here are some examples of valid variable references in the VTL:
|
|
|
|
$foo
$mudSlinger
$mud-slinger
$mud_slinger
$mudSlinger1
|
|
|
|
|
When VTL references a variable, such as $foo, the variable
can get its value from either a set directive in the
template, or from the Java code. For example, if the Java variable
$foo has the value bar at the time the template is
requested, bar replaces all instances of $foo on
the web page. Alternatively, if I include the statement
The output will be the same for all instances of $foo that
follow this directive.
Properties
The second flavor of VTL references are properties, and 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. These are examples
of valid property references in the VTL:
|
|
|
|
$customer.Address
$purchase.Total
|
|
|
|
|
Take the first example, $customer.Address. It can have two
meanings. It can mean, Look in the hashtable identified as
customer and return the value associated with the key
Address. But $customer.Address can also be
referring to a method (references that refer to methods will be
discussed in the next section); $customer.Address could be
an abbreviated way of writing $customer.getAddress(). When
your page is requested, Velocity will determine which of these two
possibilities makes sense, and then return the appropriate value.
Methods
A method is defined in the Java code and is capable of doing
something useful, like running a calculation or arriving at a
decision. 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 (")"). These
are examples of valid method references in the VTL:
|
|
|
|
$customer.getAddress()
$purchase.getTotal()
$page.setTitle( "My Home Page" )
$person.setAttributes( ["Strange", "Weird", "Excited"] )
|
|
|
|
|
The first two examples -- $customer.getAddress() and
$purchase.getTotal() -- may look similar to those used in
the Properties section above, $customer.Address and
$purchase.Total. If you guessed that these examples must be
related some in some fashion, you are correct!
VTL Properties can be used as a shorthand notation for VTL Methods.
The Property $customer.Address has the exact same effect as
using the Method $customer.getAddress(). 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.
The shorthand notation can be used for the following Methods
|
|
|
|
$sun.getPlanets()
$annelid.getDirt()
$album.getPhoto()
|
|
|
|
|
We might expect these methods to return the names of planets
belonging to the sun, feed our earthworm, or get a photograph from
an album. Only the long notation works for the following Methods.
|
|
|
|
$sun.getPlanet( ["Earth", "Mars", "Neptune"] )
## Can't pass a parameter list with $sun.Planets
$sisyphus.pushRock()
## Velocity assumes I mean $sisyphus.getRock()
$book.setTitle( "Homage to Catalonia" )
## Can't pass a parameter list
|
|
|
|
|
Formal Reference Notation
Shorthand notation for references was used for the examples listed
above, but there is also a formal notation for references, which is
demonstrated below:
|
|
|
|
${mudSlinger}
${customer.Address}
${purchase.getTotal()}
|
|
|
|
|
In almost all cases you will use the shorthand notation for
references, but in some cases the formal notation is required for
correct processing.
Suppose you were constructing a sentence on the fly where
$vice was to be used as the base word in the noun of a
sentence. The goal is to allow someone to choose the base word and
produce one of the two following results: "Jack is a pyromaniac." or
"Jack is a kleptomaniac.". Using the shorthand notation would be
inadequate for this task. Consider the following example:
There is ambiguity here, and Velocity assumes that
$vicemaniac, not $vice, is the Identifier that you
mean to use. Finding no value for $vicemaniac, it will
return $vicemaniac. Using formal notation can resolve this
problem.
Now Velocity knows that $vice, not $vicemaniac, is
the reference. Formal notation is often useful when references are
directly adjacent to text in a template.
Quiet Reference Notation
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.
|
|
|
|
<input type="text" name="email" value="$email"/>
|
|
|
|
|
When the form initially loads, the variable reference
$email has no value, but you prefer a blank text field to
one with a value of "$email". Using the quiet reference notation
circumvents Velocity's normal behavior; instead of using
$email in the VTL you would use $!email. So the
above example would look like the following:
|
|
|
|
<input type="text" name="email" value="$!email"/>
|
|
|
|
|
Now when the form is initially loaded and $email still has
no value, an empty string will be output instead of "$email".
Formal and quiet reference notation can be used together, as
demonstrated below.
|
|
|
|
<input type="text" name="email" value="$!{email}"/>
|
|
|
|
|
|
|
|
Getting literal
|
VTL uses special characters, such as $ and #, to
do its work, so some added care should be taken where using these
characters in your templates. This section deals with escaping the
$ character.
Currency
There is no problem writing "I bought a 4 lb. sack of potatoes at
the farmer's market for only $2.50!" As mentioned, a VTL identifier
always begins with an upper- or lowercase letter, so $2.50 would not
be mistaken for a reference.
Escaping Valid VTL References
Cases may arise where there is the potential for Velocity to get
confused. Escaping special characters is the best way to
handle VTL's special characters in your templates, and this can be
done using the backslash ( \ ) character.
|
|
|
|
#set( $email = "foo" )
$email
|
|
|
|
|
If Velocity encounters a reference in your VTL template to
$email, it will search the Context for a corresponding
value. Here the output will be foo, because $email is
defined. If $email is not defined, the output will be
$email.
Suppose that $email is defined (for example, if it has the
value foo), and that you want to output $email. There are a few
ways of doing this, but the simplest is to use the escape character.
|
|
|
|
## The following line defines $email in this template:
#set( $email = "foo" )
$email
\$email
\\$email
\\\$email
|
|
|
|
|
renders as
Note that the \ character bind to the $
from the left. The bind-from-left rule causes \\\$email to
render as \\$email. Compare these examples to those in
which $email is not defined.
|
|
|
|
$email
\$email
\\$email
\\\$email
|
|
|
|
|
renders as
|
|
|
|
$email
\$email
\\$email
\\\$email
|
|
|
|
|
Notice Velocity handles references that are defined differently
from those that have not been defined. Here is a set directive that
gives $foo the value gibbous.
|
|
|
|
#set( $foo = "gibbous" )
$moon = $foo
|
|
|
|
|
The output will be: $moon = gibbous -- where $moon
is output as a literal because it is undefined and gibbous
is output in place of $foo.
It is also possible to escape VTL directives; this is described in
more detail in the Directives section.
|
|
|
Directives
|
References allow template designers to generate dynamic content for
web sites, while directives -- easy to use script elements
that can be used to creatively manipulate the output of Java code --
permit web designers to truly take charge of the appearance and
content of the web site.
#set
The #set directive is used for setting the value of a
reference. A value can be assigned to either a variable reference or
a property reference, and this occurs in brackets, as demonstrated:
|
|
|
|
#set( $primate = "monkey" )
#set( $customer.Behavior = $primate )
|
|
|
|
|
The left hand side (LHS) of the assignment must be a variable
reference or a property reference. The right hand side (RHS) can be
one of the following types:
- Variable reference
- String literal
- Property reference
- Method reference
- Number literal
- ArrayList
These examples demonstrate each of the aforementioned types:
|
|
|
|
#set( $monkey = $bill ) ## variable reference
#set( $monkey.Friend = "monica" ) ## string literal
#set( $monkey.Blame = $whitehouse.Leak ) ## property reference
#set( $monkey.Plan = $spindoctor.weave($web) ) ## method reference
#set( $monkey.Number = 123 ) ##number literal
#set( $monkey.Say = ["Not", $my, "fault"] ) ## ArrayList
|
|
|
|
|
NOTE: In the last example the elements defined with the
[..] operator are accessible using the methods defined
in the ArrayList class. So, for example, you could access
the first element above using $monkey.Say.get(0).
The RHS can also be a simple arithmetic expression:
|
|
|
|
#set( $value = $foo + 1 )
#set( $value = $bar - 1 )
#set( $value = $foo * $bar )
#set( $value = $foo / $bar )
|
|
|
|
|
If the RHS is a property or method reference that evaluates to
null, it will not be assigned to the LHS. It is
not possible to remove an existing reference from the context via
this mechanism. This can be confusing for
newcomers to Velocity. For example:
|
|
|
|
#set( $result = $query.criteria("name") )
The result of the first query is $result
#set( $result = $query.criteria("address") )
The result of the second query is $result
|
|
|
|
|
If $query.criteria("name") returns the string
"bill", and $query.criteria("address") returns
null, the above VTL will render as the following:
|
|
|
|
The result of the first query is bill
The result of the second query is bill
|
|
|
|
|
This tends to confuse newcomers who construct #foreach
loops that attempt to #set a reference via a property or
method reference, then immediately test that reference with an
#if directive. For example:
|
|
|
|
#set( $criteria = ["name", "address"] )
#foreach( $criterion in $criteria )
#set( $result = $query.criteria($criterion) )
#if( $result )
Query was successful
#end
#end
|
|
|
|
|
In the above example, it would not be wise to rely on the
evaluation of $result to determine if a query was
successful. After $result has been #set (added to
the context), it cannot be set back to null (removed from
the context). The details of the #if and #foreach
directives are covered later in this document.
One solution to this would be to pre-set $result
to false. Then if the $query.criteria()
call fails, you can check.
|
|
|
|
#set( $criteria = ["name", "address"] )
#foreach( $criterion in $criteria )
#set( $result = false )
#set( $result = $query.criteria($criterion) )
#if( $result )
Query was successful
#end
#end
|
|
|
|
|
Unlike some of the other Velocity directives, the #set
directive does not have an #end statement.
String Literals
When using the #set directive, string literals that are
enclosed in double quote characters will be parsed and rendered, as
shown:
|
|
|
|
#set( $directoryRoot = "www" )
#set( $templateName = "index.vm" )
#set( $template = "$directoryRoot/$templateName" )
$template
|
|
|
|
|
The output will be
However, when the string literal is enclosed in single quote
characters, it will not be parsed:
|
|
|
|
#set( $foo = "bar" )
$foo
#set( $blargh = '$foo' )
$blargh
|
|
|
|
|
By default, this feature of using single quotes to render unparsed
text is available in Velocity. This default can be changed by
editing velocity.properties such that
stringliterals.interpolate=false.
|
|
|
Conditionals
|
If / ElseIf / Else
The #if directive in Velocity allows for text to be
included when the web page is generated, on the conditional that
the if statement is true. For example:
|
|
|
|
#if( $foo )
<strong>Velocity!</strong>
#end
|
|
|
|
|
The variable $foo is evaluated to determine whether it is
true, which will happen under one of two circumstances: (i)
$foo is a boolean (true/false) which has a true value, or
(ii) the value is not null. Remember that the Velocity context only
contains Objects, so when we say 'boolean', it will be represented
as a Boolean (the class). This is true even for methods that return
boolean - the introspection infrastructure will return
a Boolean of the same logical value.
The content between the #if
and the #end statements become the output if the
evaluation is true. In this case, if $foo is true, the
output will be: "Velocity!". Conversely, if $foo has a
null value, or if it is a boolean false, the statement evaluates
as false, and there is no output.
An #elseif or #else element can be used with an
#if element. Note that the Velocity Templating Engine
will stop at the first expression that is found to be true. In the
following example, suppose that $foo has a value of 15
and $bar has a value of 6.
|
|
|
|
#if( $foo < 10 )
<strong>Go North</strong>
#elseif( $foo == 10 )
<strong>Go East</strong>
#elseif( $bar == 6 )
<strong>Go South</strong>
#else
<strong>Go West</strong>
#end
|
|
|
|
|
In this example, $foo is greater than 10, so the first
two comparisons fail. Next $bar is compared to 6, which is
true, so the output is Go South.
Please note that currently, Velocity's numeric comparisons are constrained
to Integers - anything else will evaluate to false. The only exception
to this is equality '==', where Velocity requires that the objects on each
side of the '==' is of the same class.
Relational and Logical Operators
Velocity uses the equivalent operator to determine the relationships between variables.
Here is a simple example to illustrate how the equivalent operator is used.
|
|
|
|
#set ($foo = "deoxyribonucleic acid")
#set ($bar = "ribonucleic acid")
#if ($foo == $bar)
In this case it's clear they aren't equivalent. So...
#else
They are not equivalent and this will be the output.
#end
|
|
|
|
|
Velocity has logical AND, OR and NOT operators as well.
For further information, please see the
VTL Reference Guide
Below are examples demonstrating the use of the
logical AND, OR and NOT operators.
|
|
|
|
## logical AND
#if( $foo && $bar )
<strong> This AND that</strong>
#end
|
|
|
|
|
The #if() directive will only evaluate to true
if both $foo
and $bar are true. If $foo is false, the
expression will evaluate to false; $bar will not be
evaluated. If $foo is true, the Velocity Templating
Engine will then check the value of $bar; if
$bar is true, then the entire expression is true and
This AND that becomes the output. If
$bar is false, then there will be no output as the entire
expression is false.
Logical OR operators work the same way, except only one of the
references need evaluate to true in order for the entire
expression to be considered true. Consider the following example.
|
|
|
|
## logical OR
#if( $foo || $bar )
<strong>This OR That</strong>
#end
|
|
|
|
|
If $foo is true, the Velocity Templating Engine has no
need to look at $bar; whether $bar is true or
false, the expression will be true, and This OR That
will be output. If $foo is false,
however, $bar must be checked. In this case, if
$bar is also false, the expression evaluates to false and
there is no output. On the other hand, if $bar is true,
then the entire expression is true, and the output is
This OR That
With logical NOT operators, there is only one argument :
|
|
|
|
##logical NOT
#if( !$foo )
<strong>NOT that</strong>
#end
|
|
|
|
|
Here, the if $foo is true, then !$foo evaluates to
false, and there is no output. If $foo is false, then
!$foo evaluates to true and NOT that will be
output. Be careful not to confuse this with the quiet reference $!foo
which is something altogether different.
|
|
|
Parse
|
The #parse script element allows the template designer to
import a local file that contains VTL. Velocity will parse the VTL
and render the template specified.
Like the #include directive, #parse can take a
variable rather than a template. Any templates to which
#parse refers must be included under TEMPLATE_ROOT. Unlike
the #include directive, #parse will only take a
single argument.
VTL templates can have #parse statements referring to
templates that in turn have #parse statements. By default
set to 10, the parse_directive.maxdepth line of the
velocity.properties allows users to customize maximum
number of #parse referrals that can occur from a single
template. (Note: If the parse_directive.maxdepth property
is absent from the velocity.properties file, Velocity
will set this default to 10.) Recursion is permitted, for example,
if the template dofoo.vm contains the following lines:
|
|
|
|
Count down.
#set( $count = 8 )
#parse( "parsefoo.vm" )
All done with dofoo.vm!
|
|
|
|
|
It would reference the template parsefoo.vm, which
might contain the following VTL:
|
|
|
|
$count
#set( $count = $count - 1 )
#if( $count > 0 )
#parse( "parsefoo.vm" )
#else
All done with parsefoo.vm!
#end
|
|
|
|
|
After "Count down." is displayed, Velocity passes through
parsefoo.vm, counting down from 8. When the count
reaches 0, it will display the "All done with parsefoo.vm!" message.
At this point, Velocity will return to dofoo.vm and
output the "All done with dofoo.vm!" message.
|
|
|
Stop
|
The #stop script element allows the template designer to
stop the execution of the template engine and return. This is useful
for debugging purposes.
|
|
|
Velocimacros
|
The #macro script element allows template designers to
define a repeated segment of a VTL template. Velocimacros are very
useful in a wide range of scenarios both simple and complex. This
Velocimacro, created for the sole purpose of saving keystrokes and
minimizing typographic errors, provides an introduction to the
concept of Velocimacros.
| |
