Quick Intro to Velocity

The Velocity Template Language (VTL) is embedded mark-up which can be included in text files and interpreted by the Velocity processor. It allows the content of documents (like XML, web pages, etc) to be parameterized. Some commonly used elements of VTL are:

Variables

A variable consists of leading "$" followed a reference name of the variable. A reference name is a sequence of alphanumeric characters. A reference name may also contain a dash or underscore character, but must begin with a alphanumeric character.

Examples:

$example
$example-another

igpp.docgen parses a variety of file formats (i.e., text, PDS3 label) and generates variable definitions to reflect the content. Variables are placed in named context which can be referenced using a dot notation. For example, if the variable "this" is placed in the "my" context it can be referenced with the syntax:

$my.example

If a variable does not exist the reference string is output by Velocity. To have a blank string appear you can use a "silent" reference. A silent reference is one with a exclamation point (!) following the dollar sign ($). For example:

$!my.example

Will output the value of "my.example" if it exists and blank string if it does not.

In the preceding examples the shorthand notation for variables was used. If the value of variable is to be embedded in another string you can use the format reference notation which quotes the variable name in curly braces. For example:

${my.example}

Methods

A reference may also refer to a method (function) associated with the class of variable. In docgen values are either a String, ArrayList of String or a HashMap.

Some commonly used methods are:

Data Type Conversion

It is sometimes necessary to convert the data type of a value from a String to an Integer or double in order to perform math on the value. Two contexts are defined for this purpose.

File Information

When generating metadata it is often necessary to determine some information about the file such the size of last modificaiton data. A context called "File" which is tied to the igpp.util.File class is defined. With the "File" context the size of a file can be obtained with a call like:

$File.getSize(pathname)

An MD5 checksum for the file can be obtained with a call like:

$File.getMD5(pathname)

See the igpp.util.File documentation for more details.

Date Conversion

Time values used in metadata often must confirm to a particular format. The most commonly used format is called ISO8601. A context called "Date" is tied to the igpp.util.Date class. With the "Date" context you can convert time values in just about any format to the ISO8601 format with the call:

$Date.getISO8601DateString(string)

You can also get the time string for the current moment with a call to

$Date.getNow()

See the igpp.util.Date documentation for more details.

Math

Mathematical expressions are evaluated when defining a variable using #set and in #if statements. To use a calaculated value, for example based on the sum or two other values, you must define a new varaible using #set and then use the new variable in the desired context. For example, the sum of the value $offset and $length.

#set($total = Integer.parseInt($offset) + Integer.parseInt($length)) 

Flow Control

The Velocity Template Language supports flow control while processing the content of a template. There are two commonly used methods. One is the "if" control and the other is the "foreach" control. In the Velocity Template Language directives, like "if" and "foreach" have a "#" prefix.

if

With the "if" control actions or sections of a document can be included based on a logical comparison. For example, if a variable has a certain value.

Example:

#if($my.example == "yes")  
  Include this in the output.  
#end

You can also use "if" to determine if a value is an array or a single value by checking for the existence of the "size()" method.

Example:

#if($my.example.size())
   It's an array.
#end

foreach

With the "foreach" control a set of actions can be taken for every item in an array. If the variable $my.example were an array then each item can be assigned to a local variable and the local variable can be used within a block a text.

Example:

#foreach ($item in $my.example)  
   Do this for $item.
#end

Methods

A variable may also have methods (functions) than can perform some task. Some commonly used methods for arrays are:

Determine number of elements in an array called "$my.example":

$my.example.size()

Additional information about [Velocity](http://velocity.apache.org/engine/devel/user-guide.html "Velocity")

Next: Built-in Context