There are several different types of Script Elements within Velocity. The
overall purpose of these elements is described in the Design Document. The following elements are currently
defined within Velocity and also explained in detail below. All of the elements are
prefixed with a #. For example, #if, #foreach, #set.
Variables
Conditionals:
If / Else
Loops:
Foreach
While (Not Yet Implemented)
Parse
Include
Param
Set
Comment
Stop
Variables
Variables are referenced in a similar fashion to the way that they are in
Perl (ie: they use a $), but they also take advantage of some Java
principles that are easy for template designers to work with. For example:
$foo
$foo.getBar() or $foo.Bar
$data.getUser("jon") or $data.User("jon")
$data.getRequest().getServerName() or $data.Request.ServerName
As you can see in a couple of the examples above there are alternative uses
for the same variables. Velocity takes advantage of Java's introspection and
bean features to resolve the variable names to both objects in the Context
as well as the objects methods. It is possible to embed the variables almost
anywhere in your template and have them be evaluated.
Everything coming to and from the variables is treated as a String object.
If you have an object that is representing $foo such as an Integer object,
then Velocity will call its .toString() method in order to resolve the
object into a String.
Conditionals
If / Else Conditionals
The #if statement in Velocity allows you to conditionally include the text
within the brackets. For example:
#if ($foo)
{
<strong>Velocity Rocks!</strong>
}
The variable $foo is evaluated to see if it is a boolean or not null and the
content within the brackets is what is output if the evaluation is true. As
you can see, this has the advantage over other systems because you do not
need to wrap your HTML code within an out.println(), therefore enabling you
to develop a more MVC solution. Of course there are other solutions to
out.println() within JSP, but they are just as ugly as out.println().
Another example is that you can include #else elements with your #if element.
Note: In the current version of Velocity, it is not possible to do something like what
is shown below. We will be adding this functionality quickly though.
If you would like to emulate the functionality of #elseif, then you can do
so by using nested #if statements. As you would expect, nesting elements
works for all of the elements to an infinite level of nesting. For example,
you can nest a #foreach within a #if. We will be considering in the future
of adding a #elseif to simplify things.
Loops
Foreach Loop
The #foreach element allows you to create loops. For example:
<ul>
#foreach $product in $allProducts
{
<li>$product</li>
}
</ul>
The #foreach loop causes the $allProducts list to be looped over for all
of the elements in the list. Each time through the loop, the value from
$allProducts is placed into the $product variable.
The contents of the $allProducts variable is either a Vector, Hashtable or
Array. Thus, the value that is assigned to the $product variable is a Java
Object and can be referenced from the variable as so. For example, if $product
was really a Product class in Java, you could get the name of the Product
by referencing the $product.Name method (ie: Product.getName()).
Parse
The #parse script element allows you to import a local file and have it
parsed through the Velocity template engine and inserted into the location
where the #parse directive is defined. The current Context is applied to the
variables that are embedded within the template.
#parse /path/to/file.vm
Include
The #include script element allows you to import a local file that is
inserted into the location where the #include directive is defined. The
contents of the file are not rendered through the template engine.
#include /path/to/file.vm
Param
The #param script element allows the template designer to set items
in the context that are static and do not change over the life of the
template.
#param $date = "May 24, 1973"
One difference between Velocity and WebMacro is that the left hand side
variable must be prefixed with a $. We felt that this is more appropriate
for the script element language because you are effectively setting a
variable and the references to variables should be consistent.
Set
The #set script element allows the template designer to set variables within
the Context.
#set $name = "Fred"
One difference between Velocity and WebMacro is that the left hand side
variable must be prefixed with a $. We felt that this is more appropriate
for the script element language because you are effectively setting a
variable and the references to variables should be consistent.
Currently, the above example is the only thing that is supported. We will
eventually be suporting the full range of WebMacro functionality here.
Comment
The ## script element allows the template designer to write comments in
templates that are not placed into the output of the template engine.
## this is a comment
A current problem with Velocity is that the space that comments occupy
is not removed from the template. The newlines should be removed. This
will be fixed shortly.
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.
