Advanced
The following documentation goes into more details on how to use the personalization and templating engine.
You will learn about builtin filters, how to control whitespace if you include if/else statements, what kind of comparison you can use and more.
Filters
Sidenote - filters with arguments
You may have noticed some filters take arguments. When this is the case, there is two way to give the arguments:
Using a named argument as such:
join(separator=',')Directly giving the value as such:
join(',')
In the following reference we will denote arguments that can be given unnamed as such: argName?: type where the ? indicates the argument is optional.
General filters
Filters for numbers
Filters for strings only
Filters for tag collections only
Chaining filters
It is possible to chain filters to produce more complex results, however you need to make sure the input and output types are compatible between filters.
For example, you can't call formatDate on a number or even a string, the type has to be a date. Look at the table above to know what filters are compatible.
Here is a valid example of chaining multiple filters:
Given a user with this tag collection t.exams: ["2017-10-09T14:53:54Z", "2017-10-11T16:53:54Z"] the example evalutes to:
As you can see we take the last value of the tag collection which returns a string, then pass that to date which parses it and returns a date type. Finally we pass that to formatDate.
Expression
An expression is something that returns any kind of value. It can a math operation, a comparison, a function call, a reference to an attribute or tag or even a literal value.
Examples:
Expression are used in:
if/else ifconditionsvariable assignment
expression output
{{ ... }}
Comparison
Type comparison rules
When comparing two values, they have to be of the same type otherwise it won't work.
The rules are as follows:
A
stringcan only be compared with anotherstringA
datecan only be compared with anotherdateA
durationcan be compared with anotherdurationor anumber. When comparing with anumberit is treated as days; in other words{{ $myDuration == 3 }}is equivalent to{{ $myDuration == 3d }}.A
distancecan be compared with anotherdistanceor anumber. When comparing with anumberit is treated as meters; in other words{{ $myDistance == 200 }}is equivalent to{{ $myDistance == 200m }}A
numbercan be compared with anothernumberor aboolean.
Operators
==compares two values for equality!=compares two values for inequality>returns true if the left hand side is greater than the right hand side>=returns true if the left hand side is greater than or equal to the right hand side<returns true if the left hand side is lower than the right hand side<=returns true if the left hand side is lower than or equal to the right hand side
Combining comparisons
As in any programming languages, you can combine comparisons easily:
andreturns true if both the left hand side and the right and side are trueorreturns true if either the left hand side is true or the right hand side is truenotnegates a statement(and)to group expressions.
Data types
Standard
Standard types include:
string. You can write a literal string by using a
'character like this:'This is a string'. To use a'inside your string you need to double it like this:'It''s great'integer. You can write a literal integer like this:
230.float. You can write a literal float like this:
20.30boolean. A boolean is either
trueorfalse
Date
Date is a special type that can't be created by a literal. However they are produced in a couple of cases:
if an attribute is a date (that is either a
NSDateor ajava.util.Datefor iOS and Android respectively).by converting a UNIX timestamp (number of seconds since January 1, 1970):
{{ 1491814800|date|formatDate('yyyy-MM') }}by using the keyword
nowwhich returns the date at the time of execution
Duration
Duration is a special integer with a time unit. Units can be:
days:
40dhours:
24hminutes:
30mseconds:
46s
Distance
Distance is a special integer with a distance unit. It is also always positive. Units can be:
meters:
5600mkilometers:
83km
Casting rules
You can cast values into different types by using a casting operation, provided the types are compatible. The casting operation looks like this:
Casting looks exactly like a filter but it simply converts the original value to the type if the rules allow it.
The rules of casting are as follows:
string
✓
✓
✓
✓1
✓
✓
int
✓
✓
✓
✓2
✓
✓
float
✓
✓
✓
X
✓
✓
bool
✓
✓
✓
X
X
X
date
✓
✓2
X
X
X
X
distance
✓3
✓
✓
✓
X
X
duration
✓4
✓
✓
✓
X
X
1 The string has to follow the pattern yyyy-MM-dd'T'HH:mm:ss or the resulting date will be empty.
2 Casting from date to int will return the UNIX timestamp in seconds. Casting from int to date will treat the integer as a UNIX timestamp in seconds.
3
Rules:
casting from
stringtodistancewill treat the string as an integer representing the distance in meters.casting from
inttodistancewill treat the integer as the distance in meters.casting from
floattodistancewill remove the decimal part and treat it as an integer representing the distance in meters.casting from
booleantodistancewill treatfalseas 0 andtrueas 1.
You can pass a conversion distance unit as a parameter to the distance filter.
Valid distance units are detailed above.
Examples:
{{ '100'|distance }}will result into the distance100m{{ '12km'|distance('m') }}will result into the distance12000m{{ 2000|distance('km') }}will result into the distance2000km{{ 43.20440|distance }}will result into the distance43m{{ true|distance('km') }}will result into the distance1km(not that you'd ever do that)
4
Rules:
casting from
stringtodurationwill treat the string as an integer representing the duration in days.casting from
inttodurationwill treat the integer as the duration in days.casting from
floattodurationwill remove the decimal part and treat it as an integer representing the duration in days.casting from
booleantodurationwill treatfalseas 0 andtrueas 1.
You can pass a conversion duration unit as a parameter to the duration filter.
Valid duration units are detailed above.
Examples:
{{ '100'|duration }}will result into the duration100d{{ '100h'|duration }}will result into the duration100h{{ '48h'|duration('d') }}will result into the duration2d{{ 405|duration() }}will result into the duration405d{{ 43.409|duration('m') }}will result into the duration43m{{ true|duration('s') }}will result into the duration1s
Math rules
Math operations on integers and floats work as you would expect:
Will evaluate to:
There are a couple of rules for operations on dates, durations and distances:
adding or subtracting a
durationfrom adatewill return a newdate.subtracting two
dates will return aduration.all operations between a
durationand anumberare allowed and will return adurationin the original unit.all operations between a
distanceand anumberare allowed and will return adistancein the original unit.
Some unusual operators are available for your convenience:
//divides two numbers and returns the truncated integer result. Example:{{ 20 // 7 }}evaluates to2.%returns the remainder of the integer division of two numbers. Example:{{ 11 % 7 }}evaluates to4.**raises the left hand side to the power of the right hand size. Example:{{ 2 ** 3 }}evaluates to8.
Whitespace control
Up until now we haven't really talked about controlling how whitespaces are included - or not - in the message after the template has been rendered.
By whitespace we mean new line characters and leading spaces before either an expression or a statement.
Having control on this behaviour is important so that you can better structure your template and not have to write them all on the same line to avoid having newlines in your output.
Default rules
The default rules are as follows:
Expressions (
{{ ... }}) strips the leading whitespaces if the output of the expression is empty
Example:
With a c.first_name attribute defined, this evaluates to:
Note the space after Hello is kept.
With no c.first_name attribute defined, it evaluates to:
Note that there is only one space: the space after Hello has been removed
Statements (
{% ... %}) always strips the trailing newlines
Example:
!
This evaluates to:
Depending on the current time it will change to afternoon or evening.
Forced behaviour
If the default behaviour doesn't suit you, you can force the behaviour with the following syntax:
{{+ +}}or{%+ +%}will force every whitespace to be kept{{- -}}or<div data-gb-custom-block data-tag="-"></div>will force every whitespace to be stripped
You can mix and match of course: {{+ ... -}} is completely valid.
Example:
Now that we forcefully remove the leading whitespace, with a c.first_name defined it evaluates to:
Another example:
Here we forcefully keep the leading whitespace, with no c.first_name defined it evaluates to:
Note the space is kept.
Custom Audience Data
The Custom Audience API (v1.1) supports attaching attributes and tags to installation IDs.
When a campaign targets such an audience, they can be used in your message by using the {{ customAudienceAttribute(<audience name>, <attribute name>) }} expression.
Example
Take the following Custom Audience API call, ran on the SAMPLE-LEVELUP audience:
The following message:
will result in:
Audience Data
The Audience API supports attaching attributes and tags to profiles.
When a campaign or automation targets such an audience, they can be used in your message by using the {{ audienceAttribute(<audience name>, <attribute name>) }} expression.
Example
Take the following Audience API Update call:
The following message:
will result in:
var onTitleClick = function(event) { var methodName = event.target.dataset.method; document.querySelector(".method-details[data-method='" + methodName + "']") .classList.toggle("method-shown"); } var titles = [].slice.call(document.getElementsByClassName("method-title")); for (var i = 0; i < titles.length; i++) { titles[i].onclick = onTitleClick; }
Last updated
Was this helpful?