Quick Velocity Tutorial

This tutorial explains the basics of Velocity scripts. Most of the basic functions that Velocity is used for are described here. Please take the time to try all examples. 

Start

Start your application and go to the resource files. Right click on the root node which will open a menu. Choose 'New file' and type:

 Hello world

Press the Preview button. A new browser window (or tab, this depends on your personal browser settings) will open showing:

Hello world

In a Velocity script we can combine fixed text with dynamic text. In this tutorial we will explain how, but before we do that, we'd like to show you how to add a remark or comment. Comments are always proceeded by a double hash ##.

## this is a comment
Hello world

Another way to add a comments is using a multi-line comment, which begin with #* and end with *#

#*
 This is a comment
*#
Hello world

Comments can be used to explain your script, either for yourself, or for others who will work on, or read your script. They can also be helpful for CrossmarX when you want support regarding difficult topics.

Variables and method calls

Go back to the editor and write:

Hello $session.getUser()

Here we combine fixed text with dynamic text. Refresh the second browser tab/window and see the result.

A session contains information that is related to one web browser. So when the application is used by different users on different computers they all have their own session. In a session there is always exactly one user, but there can be more users subsequently. Every time there is a login or logout action, a new user is created and set in the session.
In a Velocity script the session is always available as a variable called session. In Velocity variables are always preceded by the dollar sign $. So to use the variable session, say $session.

TIP: to view all variables, include $toc in your script (toc = table of content). All variables will be printed.

A variable refers to an object of a certain class. An object can be an instance of a simple integer or string class, but can also be more complicated like a user session object (the $session variable we used before). Every class has methods, which can be used on variables that belong to that class. A method is capable of doing something, like getting or setting data. To call a method use the dot ('.') after the variable name. In the case of the example, the method getUser() is called from the variable $session.

TIP: in the velocity editor, placing the cursor directly after the variable name and pressing ctrl + space will show a list of all available methods for that variable.

There are some things you should know about method calls:

• Method names are always camel cased. This means that they will be written in lower case characters, but compound words will be capitalized on the compound, like getUser(). More examples will follow below.
• Method calls always have a name followed by a set of brackets (). Between the brackets, additional data can be passed to the method. Examples will follow below.
• A method can be called by placing it behind a dot . after the variable, but can also be called by placing it behind a dot after another method. This way, a second method will be called on the result of the first one. 
  
  

A list of all classes and their methods can be found in the CrossmarX Velocity API. Here are some examples. First, let's get a date from the application object.

Today: $application.newDate()

$application.newDate() returns an object of class CXDate. Now, let's format this date by calling a method of the class CXDate on the result of the first method call.

Today in standard format: $application.newDate().format()

Finally, it is also possible to pass a pattern to the method call.

Today in special format: $application.newDate().format('dd-MMM-yy')

See the CrossmarX Velocity API for details.

Define your own variables

A variable can store values. This allows you to keep the result of a method call for later use. You can:

• assign a constant or the outcome of a method call to a variable
• use the value of the variable in your script
• assign a new value

A variable name 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 '-' and
• underscore '_'

A good practice is to use sensible variable names, that can be understood intuitively. As mentioned before, this will make your script more understandable for yourself, colleagues, or for CrossmarX (when you want support on difficult topics).

You can use the value of a variable anywhere in your script file just by adding it, prefixed with a dollar sign $: e.g. $person, $order, $title, etc. Please be aware that variable names are case-sensitive!   

The #set statement defines and assigns a variable. The easiest example:

#set($var = "Africa")

for a string of characters, or

#set($var = 5)

for an integer. But you can also assign the output of a method call to a variable:

#set($var = $application.newDate().format('dd-MMM-yy'))

When you want to combine the two:

#set($var = "On $application.newDate().format('dd-MMM-yy') we will leave for Africa")

This example shows that first all Velocity methods will be evaluated. Next the output will be concatenated in the string that is assigned to the variable. To show the value of the variable on the screen just use the variable name, in this example:

$var

Once a variable is defined, you can reference the variable anywhere in your document.

TIP: quoting strings with " " will make Velocity evaluate the string as code first, while using ' ' will cause Velocity to ignore any code/variables in the string. 

Example:

#set($var = 4)
#set($x = "$var")
#set($y = '$var')
$x
$y

Will result into output:

4
$var

#set($today = $application.newDate())
.
.
#set($tomorrow = $today.addDays(1))
.
.
Tomorrow in special format: $tomorrow.format('E dd-MMM-yy')

The #set statement is one of a handful of statements used in Velocity that are frequently used. All of them are preceded by a #.

• #if
• #else and #elseif
• #foreach and #break
• #end
• #parse
• #include
• #define
• #macro
• #stop

These statements will be explained later in this tutorial. To make statements more readable, we encourage you to start each statement on a new line, although you are not required to do so.

Briefly summarized:

• Variables: begin with a $ and are used to store something
• Method calls: begin with a dot . and are used to do something with a variable
  
• Statements: begin with  a # and are used to control the flow of the script
  
  

Hiding empty Velocity variables

If a variable is unassigned or empty, Velocity will consider the variable as standard text and print it out. Consider the following script.

price: $price

The variable $price has no value and the script above results in:

price: $price

If you don't want this to happen add an exclamation mark after the dollar sign. This tells Velocity not to display anything when the variable is empty.

price: $!price
<br />

#set($price = 100) 
price: $!price

The output will now be:

price:
price: 100

Note that the $! notation is only relevant when you want to display the (string) value of the variable. There is no point in using it when passing the variable to another variable or method. For example #set($price2 = $!price) works, but the exclamation mark is really pointless here.

Add a surrounding page

A surrounding page is wrapped around the content of your current document. Here you can read how to change the default surrounding page.

Until now, the output of our work was just a blank page with the result of the scripts. You can get the output within a surrounding page by adding the following line.

$document.surround()

The variable $document is always available in your context. See java class XDocument in the CrossmarX Velocity API for  further details.

When you want a specific surrounding page, do something like:

$document.surround('/mysurroundingpage.vm')

Make sure you have a file called mysurroundingpage.vm and inside this file call the content with $document.getContent() in order to see the content of the current page in the surrounding page.

Getting a table

Now let's get some data from our application database. Put the following line of velocity code in your file. In our example we use a class named product. You should replace 'product' with the name of one the classes in your blueprint. Be sure that you use the class name exactly as defined in the blueprint.

$session.getTable('product').toHTML()

This gets a table with objects of the class product, and transforms the table to HTML. You can also assign the table to a variable, and perform method calls on the variable.

#set($table = $session.getTable('product'))
$table.size()
$table.toHTML()

We will show more about what you can do with tables in section 10 of this tutorial.

Getting a single record

The easiest way to get a single record from the database, is by asking the session. Suppose there is a class product, do the following.

$session.getFirstRecord('product').toHTML()

The first record of the class product is shown on screen with the fields in a listed order. To show the fields as a table, we need:

$session.getFirstRecord('product').asTable().toHTML()

Suppose the class has a single key field id. To get the product with id = 1 we need to do the following:

$session.getRecord('product', 1).toHTML()

Now that we have a record, we can get all kind of information from the record. We can simply get the value from a single field with the method get. We have to pass the name of the field, exactly as it is defined in the blueprint.

#set($product = $session.getFirstRecord('product'))
#set($productName = $product.get('name'))
#set($productPrice = $product.get('price'))
The price of the product $productName is $productPrice

 

Using the http request

Now save the file as test.vm.

Rewrite your page to: 

#set($id = $request.getInteger('productnumber'))
#set($product = $session.getRecord('product', $id))
$product.toHTML()

For this example we use an application that is called 'myapplication' and runs on development. Go to the following URL in a new tab in your browser and change 'myapplication' in to match your application name.

https://myapplication.cx-develop.nl/test.vm?productnumber=1

In the request we added the parameter productnumber=1. When this script is executed, the value of productnumber is read from the request. Since we asked for the product record with id 1, the first product appears on the window. Feel free to change the productnumber in the http request to see details of other products.

Pay attention that the parameters in the request are case sensitive. So if you have the parameter Productnumber you should also use $request.getInteger('Productnumber')

To read more about securely using the request go to this page.

 

Conditions: if-then-else

Now rewrite your page to:

#set($id = $request.getInteger("productnumber"))
#set($product = $session.getRecord('product', $id))
$product.toHTML()
#if($id == 2) 
    Extra discount!!!
#end

The #if statement in Velocity defines a condition. The text between the #if and #end is only handled when the condition evaluates to true. In this case the text "Extra discount!!!" is only printed on the page when the id equals 2.

Conversely, if $id doesn't equal 2, the condition evaluates as false, and there is no output. So when we use the same url as above https://myapplication.cx-develop.nl/test.vm?productnumber=1 there will be no output from the #if statement, but if we change the id to two https://myapplication.cx-develop.nl/test.vm?productnumber=2, the text will show.

Some remarks:

• An #if statement should always be closed with an #end statement.
• Instead of ==, you can also use != (does not equal), > (greater than), >= (equals or greater than), < (smalller than)  or , <= (equals or smaller than) 
• To keep your files readable always indent the text between the #if and #end. We at CrossmarX prefer to use one space as indentation.
• The == operator can be used to compare strings.

If you run this script without a productnumber parameter in the request, you will get a velocity error because $session.getRecord("product", $id) will fail when $id has no value. To prevent this you can wrap everything from line inside another #if statement.

#set($id = $request.getInteger("productnumber"))
#if($id)
    #set($product = $session.getRecord('product', $id))
    $product.toHTML()
    #if($id == 2) 
        Extra discount!!!
    #end
#end

You can also use the #else and #elseif statements. See the following example:

#if($id > 10) 
    Very much extra discount!!!
#elseif($id > 2)
    Extra discount
#else 
    No extra discount
#end

You can also use the #if statement to check a boolean variable directly:

#set($isBlack = true)
#if($isBlack)
    text to be displayed when variable isBlack is true.
#end

The text will now be displayed.

Another useful (but for some unfamiliar) feature of Velocity is the ability to evaluate a non-boolean variable directly. When this is done, Velocity simple checks if the variable has a value. Here we will show two examples: 

#set($color = "black")
#if($color)
    text to be displayed when variable 'color' has a value
#end

#set($color = $null)
#if($color)
    text to be displayed when variable 'color' has a value
#end

The text in the first example will be displayed. The text in the second example will not be displayed. We use the $null variable to unset the value of an other variable. This is a neat trick; $null is a variable wich we never asign a value to, so we can use it to reset other variables.

A loop: foreach

The #foreach statement defines a loop. It is commonly used to perform actions on every individual record of a table, e.g. to show product data in a HTML table on a window.

#set($products = $session.getTable('product')) 
<table> 
#foreach($product in $products)
    <tr> 
        <td>$product.get('name')</td>
        <td>$product.get('price')</td>
    </tr>
#end   
</table>

A HTML table will be shown with a row for every individual product containing the name and the price.

Another usage of a loop. Here the loop is used to perform a calculation.

#set($order_lines = $session.getTable('order_line')) 
#set($totalQuantity = 0)
#foreach($order_line in $order_lines)
    #set($quantity = $order_line.get('quantity'))
    #set($totalQuantity = $totalQuantity + $quantity)
#end   
Total quantity: $totalQuantity

When you want to break from the for loop, use #break. In this example we break out of the loop after 10 iterations. You can use the $foreach.count variable (local to the loo) to check the number of iterations. Other options are $foreach.index (starts with 0 in the first iteration) and $foreach.hasNext, to check if the end of the iteration has been reached or not.

#set($order_lines = $session.getTable('order_line'))
#set($totalQuantity = 0)
#foreach($order_line in $order_lines)
    #set($quantity = $order_line.get('quantity'))
    #set($totalQuantity = $totalQuantity +$quantity)
    #if($foreach.count == 10)
        #break
    #end
#end 
Total quantity: $totalQuantity

When you want to stop the evaluation of the whole script, use #stop.

#if($something == 'stop now')
    #stop
#end
This line will never be reached.

Note on secure use of foreach loops

It is highly discouraged to use a foreach loop to iterate over all the parameters in the request and storing the values in variables. Blindly accepting request parameters could lead to a security breach by accepting malicious content (see this page for more about cross site scripting). Only check for known parameters from the request!

 

Using relations from the data model

Most applications have relations between classes. This means that records are also related, and these relations can be used in the Velocity script. We will show you an example from a web shop of a surf school application. In this application we have (at least) two classes:

• person
• order

There is a one-to-many relation between person and order. This means that the class order is a connected class of person, and the class person is a foreign class of order. We can use this to get to the related records easily.

#set($person = $session.getFirstRecord('person'))
#set($orders = $person.getConnectedTable('order'))
$orders.toHTML()

In this example, first a person record is retrieved from the database, and next all the orders of this person are requested and printed.

And the other way around:

#set($order = $session.getFirstRecord('order'))
#set($person = $order.getForeignRecord('person'))
$person.toHTML()

You can also get information from the person directly from the order record. Suppose the class person has a field last name. We can directly access data from a foreign record, just by using a field name from the foreign class.

#set($order = $session.getFirstRecord('order'))
#set($personName = $order.get('person.last name'))
$personName

Because last name is not a field of the class order, you have to prefix the field name with the class name (using a dot as separator).

 Queries

Instead of getting a whole table, you might want a subset. Suppose you only want to retrieve women from the persons in your database. Example: in the class person a field gender can have values male or female. To retrieve only women you have to create a Query:

#set($query = $session.newQuery('person')) 
$query.setFilter('Gender', 'f') 
#set($women = $query.getTable()) 
$women.toHTML()

Now let's extend the query a bit: you do not only want to select the women, but all women should be below the age of 30. Now we have to create a more complex constraint:

#set($query = $session.newQuery('person'))
$query.addFilter('Gender', 'm')
$query.addFilter('Salary', '<', 300000)
##field Salary is datatype money so value is in cents
#set($mensalarybelow3000 = $query.getTable())
$mensalarybelow3000.toHTML()

Some other options to customize a query:

#set($query = $session.newQuery('person'))
$query.addResultField('First name') 
$query.setDistinct(true) 
$query.setMaxSize(20) 
$query.addSortField('Salary', 'desc')
#set($table = $query.getTable())
$table.toHTML()

See the CrossmarX Velocity API for more details.

Organizing your script

Never include the same code twice to reduce maintenance effort. When pieces of code have to be used in different locations, use one of the three following options:

#define

You can define some code blocks in the top of your file and use this at several other locations within the same file. The code block and the main part of the file always share the same variables. Here is an example.

#define($block)
    Hello $who
#end

## ..... other code goes here .....

#set($who = 'World!')
$block

This example will display Hello world!. The define command is very useful to structure your code within one file.

#macro

The macro command is like the define command, but there are differences:

• A macro can have it's own local variables. There are 2 main advantages of using local variables
  • You can use another name for a variable than the name used at the caller. Example to be added.
  • When a macro is called recursively, every recursion can have its own values.
• Macro's are cached by velocity for a higher performance.
• Macro's are usually defined in the macro-manager. In the backstage go to Blueprint -> macro's or use the button with the hash icon # on the toolbar. The macro's you make here are saved in a generated file in your root directory, called macros.pm. This file can not be edited separately.

Macro's are automatically available in all your velocity files. However, it is also possible to define a macro at the top of another file.

Create a macro in the macro-manager

• Go to the backstage and go to the macro-manager Blueprint -> macro's.
• Click on + New macro
• In the field name enter myMacro
• In the field parameters enter $who
• In the field content enter Hello $who
• Press save and look at the file macros.pm 

You should see the following code:

#macro(myMacro $name)
    Hello $name
#end

From another velocity file in your application's resource files,  this macro can now be called as follows:

#myMacro('World!')

This example also displays Hello world!.

The macro command is very useful to structure code in several files. Blocks of code used in several files can be extracted and put in macros.vm. This makes the code easier to understand and more flexible.

#parse

The parse command is used to include and parse the content of another file. Both files share the same variables. Suppose there is another file named test2.vm in the root of your resource files, then it can be parsed into your script like this:

##... some code

#parse("test2.vm")

##... some other code

The parse command is also useful to structure code in several files. It should be used (instead of the macro command), when the second file must also be able to run independently.

#include

The include command is similar to the parse command except it doesn't parse the file. It just includes the code as is. Use:

#include("test2.vm")

 

Tips & tricks

Concatenating a variable and constant text

Variables can also be surrounded by curly brackets, e.g. ${var}. This can be very useful when concatenating variables and regular text. An example: the variable $fruit is an existing variable. Suppose you want to list several fruit juices. To do this you must write:

In my store I have $fruitjuice.

But now the Velocity handler will look for a variable $fruitjuice. To prevent this you should write:

In my store I have ${fruit}juice.

The Velocity handler now knows that the variable is $fruit.

Using null values in velocity

If a variable has a 'null' value, this means it has no value. This is different than being empty, like an empty string or list. In some cases you may need the 'null' value, for example if a method or macro requires you to pass some parameters, but you don't have a value for one of them. In velocity, the only way to assign a null value to a variable is to assign another variable to it. You can use a variable that doesn't exist, that will be treated as null. So if, you want null, just pick a variable name that doesn't yet exist. It's a good idea to use a standard name, we use $null! Assuming the method can handle null values, you could do something like this:

$application.deleteAll('person', $null)

Because the second parameter has the value null all records of the class person will be deleted

See http://velocity.apache.org/engine/releases/velocity-1.7/user-guide.html for more details about how to use velocity.