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. You can find the introduction to this topic and some simpler methods to work with email dynamic content in the /blog/dinamicheskiy-kontent-v-pismah article
In eSputnik 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'))
<div>$item.get('name') ... </div>
#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:
|
Velocity comparing operators |
Corresponding comparing operations |
|
gt |
> (more) |
|
lt |
< (less) |
|
ge |
≥ (more or equal) |
|
le |
≤ (less or equal) |
|
== |
= (equal) |
|
!= |
≠ (not equal) |
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')
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: