Velocity Templating Tutorial

Introduction

Velocity is a Java-based templating engine.

Velocity Template Language (VTL) provides the simplest and cleanest way of incorporating the dynamic content in documents by using VTL references.

By combining the template source (HMTL, WORD) with the dynamic content (JSON) it generates the final document (PDF or Images).

Velocity syntax

VTL references/properties in velocity templates start with a $ and are used for getting the value associated with that reference.

The final value resulting from every reference is converted to a string when it is rendered into the final output.

property substituition

Template properties refer to fields in the JSON data, or methods to transform data:

Template:

Client name: $client_name

JSON:

{
  "client_name": "John Doe"
}

Output:

Client name: John Doe

VTL provides also a set of directives which can be used for manipulating the output template. Those directives start with #.

Be aware that Word templates, besides references/properties, are very limited in what Velocity directives can be used. Unless the directive beginning and end are on the same parapgraph, it's highly unlikely they will work properly.

conditionals

#if, #elseif and #else directives provide a way to generate the content based on conditional checks:

Template:

#if($employee.designation == "Manager")
    <h3> Manager </h3>
#elseif($employee.designation == "Senior Developer")
    <h3> Senior Software Engineer </h3>
#else
    <h3> Trainee </h3>
#end

JSON:

{
  "employee": {
    "designation": "Senior Developer"
  }
}

Output:

    <h3> Senior Software Engineer </h3>

loops

#foreach directive allows looping over a collection of objects:

Template:

<ul>
    #foreach($product in $product_list)
        <li> $product.name </li>
    #end
</ul>

JSON:

{
  "product_list": [
    { "name": "Product 1" },
    { "name": "Product 2" },
    { "name": "Product 3" }
  ]
}

Output:

<ul>
    <li>Product 1</li>
    <li>Product 2</li>
    <li>Product 3</li>
</ul>

set

Can be used for setting the value of a reference; this value can be assigned to a variable or a property reference:

#set ($message = "Hello World")
#set ($customer.name = "Brian Mcdonald")

Or it can be used for calculations (multiply or totals inside loops):

Template:

#set ($item_total = 0)
#foreach($item in $items)
#set ($item_total = $item_total + $item.quantity)
<tr>
    <td>$item.name</td>
    <td>$item.quantity)</td>
</tr>
#end
<tr>
    <td>TOTAL</td>
    <td>$item_total</td>
</tr>

JSON:

{
  "items": [
    {
      "name": "Design",
      "price": 40,
      "quantity": 26
    },
    {
      "name": "Development",
      "price": 40,
      "quantity": 80
    },
    {
      "name": "SEO",
      "price": 40,
      "quantity": 20
    },
    {
      "name": "Training",
      "price": 40,
      "quantity": 4
    }
  ]
}

Output:

<tr>
    <td>Design</td>
    <td>26</td>
</tr>
<tr>
    <td>Development</td>
    <td>80</td>
</tr>
<tr>
    <td>SEO</td>
    <td>20</td>
</tr>
<tr>
    <td>Training</td>
    <td>4</td>
</tr>
<tr>
    <td>TOTAL</td>
    <td>130</td>
</tr>

break

#break directive stops any further rendering of current execution scope (i.e. #foreach)

stop

#stop directive stops any further rendering and execution of the template.

Format numbers

$number method allows to format and convert numbers.

• To format numbers, use the $number.format('<format>', value) method. First parameter is the format to apply to the number, second parameter the number value

The format uses the Java DecimalFormat (opens new window) syntax

Template:

<div>
    Price: $number.format('#0.00', $item.price)
</div>

JSON:

{
  "item": {
    "name": "Website design",
    "price": 300
  }
}

Output:

<div>
    Price: 300.00
</div>

• To format numbers as currency, use the $number.currency(value) method.
• To format numbers as integers, use the $number.integer(value) method.

Bar and QR Codes

$bar.code

Method allows to render bar codes. The method supports the following bar code types:

• UPC_A
• UPC_E
• CODE_39
• CODE_128
• PDF417
• EAN_8
• EAN_13

It can receive two or three parameters

• code type (see above)
• code value
• css styles string (optional) to apply to the resulting image.

Example 1: $bar.code("UPC_A", "12345678901")

Example 2: $bar.code("EAN_8", "12345670", "width:150px;")

$qr.code

Method allows to render QR codes.

It receives one or two parameters

• code value
• css styles string (optional) to apply to the resulting image.

Example 1: $qr.code("https://www.docsfold.com")

Example 2: $qr.code("https://www.docsfold.com", "width: 150px;")

Charts

** TODO **

Word Template Limitations

Because of the way the Word document format works, Velocity properties replacement and directives logic is applied on a per paragraph logic.

This will not work if a directive begins in a paragraph and ends in another.

We only recommend using Word templates for simple property replacement and not adding complex logic.