Dynamic content in emails. Velocity.

Dynamic email content is used to add the required data or settings when sending them to user. For example, goods ordered by customer, client name or his personal promo code.

In our system, dynamic content option is featured by using of Apache Velocity library. On the current page, we'll review the main features of the Velocity language.

Getting the single parameter

All external data that incomes into messages gets into the data object, so write this to get the required parameter:

$!data.get('parameter name')

Getting elements from the massive by index

If we want to get the massive element by index we specify the name of the massive and the element index:

$!data.get('massive name').get(0) - if massive contains only values, where 0 is index of the element.

$!data.get('massive name').get(0).get('parameter name') - if massive contains objects with parameters.

This method is suitable when massive size is known in advance. If you specify the index of the element that is not exist in the massive then error will occur when sending a message.

Get the massive size

$!data.get('massive name').size()

Algorithm to get all the massive elements

To get all the elements of a required massive, use the #foreach loop.

Syntax:

#foreach($item in $data.get('massive name'))
$item.get('name') ...
#end

where $item is a variable that will be assigned with the current massive element and allowed to access within the loop. In this case, the whole list of massive elements will be displayed in turn.

For more detailed situation of its use in dynamic email marketing, check the examples of transferring orders en/support/orders-automation#messages

or abandoned carts /en/support/abandoned-carts

Evaluate

Syntax:

#set($var='value')

The value may be specific one, another variable or expression.

Comparing

Comparing operators:

Syntax:

$!param1 gt $!param2

Conditions

Conditions may be useful for several reasons:

• if you want only to get some specific data (for example, only one category of products);

• if you want to display a certain amount of goods in one block not breaking the design, etc.

Syntax

#if ($data.get('params')=='value')
(content)
#end

If result is negative then we can get an alternative:

#if($data.get('param')=='value')
(content)
#else
(alternate content)
#end

You can also check several conditions:

#if($data.get('param')=='value1')
(content 1)
#elseif($data.get('param')=='value2')
(content 2)
#else
(alternate content)
#end

You can combine several conditions using the logical operators and, or:

#if ($data.get('param1')=='value1' and $data.get('param2')=='value2')
(content)
#end

You can invert the condition:

#if (!($data.get('param')=='value'))
(content)
#end

Arithmetic operations

Addition: $mathTool.add($v1, $v2)

Subtraction: $mathTool.sub($v1, $v2)

Multiplication: $mathTool.mul($v1, $v2)

Division: $mathTool.div($v1, $v2)

Formatting Numbers

$numberTool.integer($v1) - displays an integer without rounding.

To output money amounts with two decimal places, you can use the following function:

$!numberTool.format('#.00',$v1)

Date displaying in message

You can display the current date using the function:

$!dateTool.currentDate()

You can specify the format to display date and/or time:

$!dateTool.currentDate('dd.MM.yyyy HH:mm:ss')

If date has Unix TimeStamp format (for example, 1495479520000) then it may be converted into a readable format using the function:

$!dateTool.formatDate('dd.MM.yyyy',$!data.get('date'))

either specifying the format:

$!dateTool.formatDate('yyyy-MM-dd HH:mm:ss',$!data.get('date'))

Checking for a non-empty value

If you need to check is parameter transmitted and wasn’t it empty you can use the following code:

#if($data.get('param') and $data.get('param')!=’’)
(content)
#end

It may be useful when message contains some appeal to subscriber but not all clients have their names specified.

Working with strings

Get the string length:

$!var.length()

Get the string part:

$!var.substring(start index, end index)

Replace the part of the string with a different value:

$!var.replace('what needs to be changed','value to set instead')

Change Case:

#set ($example = "UkRaInE")  

$example.toUpperCase()  // UKRAINE
$example.toLowerCase()  // ukraine

Basically, this is all the essential info you can use when configuring your email marketing dynamic content. If you need more detailed Apache Velocity user guides, click the links below:

http://velocity.apache.org/engine/1.7/user-guide.html

http://people.apache.org/~henning/velocity/html/index.html