To use dynamic content to personalize the messages you send with Iterable, use Handlebars. With Handlebars, you can display, format, reference and reason about user profile and event data in message templates.
Table of contents
-
Getting started with Handlebars
- Definition: merge parameter
- Sample user profile data
- Sample event data
- Using Handlebars in HTML source
- Referencing user profile and event fields with Handlebars
- Fields containing spaces or a period, or starting with a number
- Fields containing HTML
- Handlebars helpers and block helpers
- Helpers
- Block helpers
-
Working with strings
- Regular expression matching (#ifMatchesRegexStr)
- Contains a substring (#ifContainsStr)
- Checking equality and alphabetical order (#eq, #lt, #lte, #gt, #gte)
- String length (length)
- Capitalize first letter of a string (capitalizeFirst)
- Capitalize first letter of each word in a string (capitalize)
- Capitalize entire string (upper)
- Lowercase entire string (lower)
- Display default value if no value exists for a parameter (defaultIfEmpty)
- Render HTML contained within a field
- Remove all instances of a specified string (cut)
- Replace all instances of a string (replace)
- Get substring by index (substring)
- Abbreviate string to a specified length (abbreviate)
- Convert to lowercase, remove numbers and special characters, and convert spaces to hyphens (slugify)
- Replace newlines (#breaklines)
- URL encoding (#urlEncode)
- Write the provided argument as a JSON string (toJson)
- Write the provided argument as a URL encoded JSON string (toUrlEncodedJson)
- Base64 encode a merge parameter (#base64)
- Generate a SHA1 HMAC (hmacSHA1)
- Generate a SHA1 hash (sha1, #sha1)
- Generate an MD5 hash (md5, #md5)
- Generate a SHA256 hash (sha256, #sha256)
- Pad a parameter (center)
- Working with numbers (longs and doubles)
-
Working with lists/arrays
- Show item at index (square brackets)
- Iterating over all values (#each)
- Concatenate values in an array into a single string (join)
- Check for an item (#ifContains)
- Minimum value in list (#minInList)
- Maximum value in list (#maxInList)
- Size (size)
- Comparing two arrays (#eq, eq, #neq, neq)
- First and last items (@first, @last)
- Working with objects
- Working with dates
- Conditional and boolean logic
- Other Handlebars helpers
- JSON-LD
- Further reading
Getting started with Handlebars
This section provides an overview of using Handlebars expressions in Iterable to reference, manipulate, and reason about data stored on a user profile or an event.
Definition: merge parameter
Wrapping the name of a user profile or event field in double curly braces creates a merge parameter. When using merge parameter, data from the relevant user profile or event is merged at send time into the template or URL being modified, customizing and personalizing it as necessary.
Sample user profile data
To view a sample user profile, navigate to Audience > Contact Lookup and enter an email address associated with an Iterable user profile. The user profile will look similar to the following:
Sample event data
To view sample events saved by an Iterable project, navigate to Insights > Logs > Events.
Using Handlebars in HTML source
In an Iterable message template, you can add Handlebars expressions directly in the WYSIWYG editor or in its HTML source. When editing the HTML source, it is generally a good idea to comment out any Handlebars expressions that do not output a value.
In rare circumstances, the WYSIWYG editor can get confused by the presence of Handlebars expressions in the HTML source, which can lead to errors. Since the WYSIWYG editor ignores comments in the HTML source, commenting out Handlebars expressions can resolve this issue.
For example, do not enter the following Handlebars expression in a message template's HTML source:
Instead, enter the following:
If you're entering a Handlebars expression that outputs a value (for example,
an expression like {{email}}
that outputs the value of a user profile
field), do not comment it out. Commenting out such an expression would
prevent its value from rendering in the template.
It is safe to comment out Handlebars expressions such as conditionals, looping constructions, closing statements, etc., that do not output any value. For these expressions, there is no risk of preventing a necessary value from rendering in the message template.
The rest of this document displays uncommented Handlebars expressions. That is, it displays them as they should be entered in the WYSIWYG editor, not the HTML source. When editing the HTML source of a message template, adjust the Handlebars expressions as demonstrated in the above example.
Referencing user profile and event fields with Handlebars
To reference any field from a user profile or campaign-triggering event in an Iterable message template, use Handlebars expressions.
The most basic Handlebars expressions simply output the value of a user profile or event field by wrapping its name in curly braces. For example, the following Handlebars expression outputs a user's email address:
NOTES
- Field names are case sensitive.
- The same double curly brace syntax can reference both user profile and event fields.
- If the same field exists on both the user profile and the campaign's triggering event, Iterable will use the value on the event.
Fields containing spaces or a period, or starting with a number
To use Handlebars to reference a field that contains spaces or a period, or starts with a number, surround the field in square brackets (as well as double curly braces).
For example:
WARNING
If possible, avoid using periods in field names, since they can cause difficulty when referencing data stored in nested objects on a user profile or event.
Fields containing HTML
To use Handlebars to display the HTML contained in a user profile or event field, wrap the field in triple curly braces (otherwise, the HTML will render as plain text). For example:
TIP
If the HTML-containing parameter comes from a data feed
Handlebars helpers and block helpers
Handlebars users helpers to manipulate, format, and loop through user profile and event data, to perform calculations, and to apply boolean and conditional logic. Helpers come in two varieties: helpers and block helpers.
Iterable message templates use Handlebars helpers and block helpers to display user and event profile data in a way that is most suitable to each recipient.
NOTE
Helpers and block helpers can work with user profile fields, event fields, and
literals. For example, both the Handlebars expressions in the following example
are valid (assuming the existence of a user profile or event field called
favoriteBook
):
Helpers
A Handlebars helper is a function that takes zero or more parameters and returns a value. For example:
This helper renders the firstName
parameter with its first letter
capitalized. The value stored in the firstName
parameter is not changed.
To nest sequential calls to Handlebars helper methods, use parentheses. For example :
This example lowercases every letter in firstName
, and then capitalizes its
first letter, rendering the output in the message template. Again, the value
stored in firstName
is not modified.
Block helpers
Like helpers, block helpers are functions. They are generally used to perform conditional logic or to iterate over collections of items.
A block helper has an opening statement, a block of content, and a matching
closing statement. The opening statement is always preceded by a #
character.
For example:
This example iterates over the items stored in the shoppingCartItems
,
displaying the name and price for each.
Working with strings
This section describes various helpers useful for working with strings in Handlebars.
Regular expression matching (#ifMatchesRegexStr)
Match an entire string:
Match a substring:
NOTE
Regular expression queries are case-sensitive, which is why this example uses
[Bb]
to search for both cases.
To learn more about using regular expressions in Iterable, read Regular expressions for use in segmentation and Handlebars.
Contains a substring (#ifContainsStr)
Search a string for a particular substring. If the substring is found, render the block's content. For example:
This example searches the haystack
field for "needle". If "needle" is found,
it renders the string "Haystack contains needle!"
Checking equality and alphabetical order (#eq, #lt, #lte, #gt, #gte)
To check whether two strings are in alphabetical order, use the various comparison helpers:
-
#eq
,eq
: equals -
#lt
,lt
: less than -
#lte
,lte
: less than or equal -
#gt
,gt
: greater than -
#gte
,gte
: greater than or equal
NOTES
- If an
#lt
,lt
,#lte
,lte
,#gt
,gt
,#gte
, orgte
expression references a non-existent or null field, the template will fail and the message will not be sent to that user. - Alphabetic order comparisons are case sensitive.
- For detailed information about these comparisons, read the docs about the
Java
compareTo
method. - The below comparisons work for string literals as well as fields on user profiles and events.
For example:
-
To check whether "cat" comes before "dog" in alphabetical order:
This expression renders "cat comes before dog!"
-
To check whether "dog" comes after "cat" in alphabetical order:
This expression renders "dog comes after cat!"
-
To perform a string comparison in a boolean expression, use the non-block versions of these helpers:
For more information about the
#if
helper, see Conditional and boolean logic.
String length (length)
Use the length
method to display the length of a string. For example:
Capitalize first letter of a string (capitalizeFirst)
Use the capitalizeFirst
helper to capitalize the first letter of a string.
For example:
Capitalize first letter of each word in a string (capitalize)
Use the capitalize
helper to capitalize the first letter of each word in a
string. For example:
Capitalize entire string (upper)
Use the upper
helper to capitalize every letter in a string. For example:
Lowercase entire string (lower)
Use the lower
method to lowercase every letter in a string. For example:
Display default value if no value exists for a parameter (defaultIfEmpty)
Use defaultIfEmpty
to display a default value if a parameter is null,
undefined, or an empty string. For example:
Render HTML contained within a field
To render HTML contained in a field, wrap the field in triple curly braces. For example:
Remove all instances of a specified string (cut)
To display a string with all instances of a certain string removed, use the
cut
helper. The following example removes spaces from a string:
Replace all instances of a string (replace)
To replace all instances of one string with another string, use the replace
helper. The following example changes all of a string's spaces to dashes:
Get substring by index (substring)
To display a substring of a string, use the substring
helper.
substring
accepts three parameters:
- (required) The string
- (required) The starting index of the substring.
- (optional) The last index of the substring + 1.
The following example display a substring from myMergeParam
, starting at
index 0 and finishing at index 1 (making the substring two characters long):
Abbreviate string to a specified length (abbreviate)
To abbreviate a string to a specified length, use the abbreviate
helper.
Provide a number describing the final string length, including three characters
for "...". The following example displays the string stored inmyMergeParam
,
abbreviated to four charactacters and three periods:
If myMergeParam
were set to "testing", this example would render "test...".
Convert to lowercase, remove numbers and special characters, and convert spaces to hyphens (slugify)
Use the slugify
helper to lowercase, remove numbers and special characters,
and convert spaces to hyphens in a string. If myMergeParam
were set to "John
Smith", the following example would render "john-smith":
Replace newlines (#breaklines)
To replace "\n" or "\r\n" with "<br/>", use the #breaklines
block helper. For
example:
URL encoding (#urlEncode)
To URL encode a string, use the #urlEncode
block helper. For example:
Write the provided argument as a JSON string (toJson)
Output the parameter in its JSON representation. For example:
Write the provided argument as a URL encoded JSON string (toUrlEncodedJson)
Output the parameter in its URL-encoded JSON representation. For example:
Base64 encode a merge parameter (#base64)
Base64 encode the parameter. Use to Base64 encode email addresses in URLs. For example:
Generate a SHA1 HMAC (hmacSHA1)
To generate a SHA1 HMAC, use the hmacSHA1
helper. This helper concatenates
the passed-in parameters and uses the HMAC Secret specified in
Project > Settings to find the resulting HMAC-SHA1:
Generate a SHA1 hash (sha1, #sha1)
To generate a SHA1 hash:
-
Pass a string (or a field containing a string) to the
sha1
helper. For example:If
field1
were set todocs@iterable.com
, this example would outpute364ed2661a7b922e5bf670f2a0946977bf63ae7
. -
Alternatively, use the
#sha1
block helper. For example:If
userName
were set todocs
andhost
were set toiterable.com
, this example would output the SHA1 hash fordocs@iterable.com
:e364ed2661a7b922e5bf670f2a0946977bf63ae7
.
Generate an MD5 hash (md5, #md5)
To generate an MD5 hash:
-
Pass a string (or a field containing a string) to the
md5
helper. For example:If
userName
were set todocs
andhost
were set toiterable.com
, this example would output the SHA1 hash fordocs@iterable.com
:0e13848b1c7e27eb5d88c5d35b70783e
. -
Alternatively, use the
#md5
block helper. For example:If
userName
were set todocs
andhost
were set toiterable.com
, this example would output the MD5 hash fordocs@iterable.com
:0e13848b1c7e27eb5d88c5d35b70783e
.
Generate a SHA256 hash (sha256, #sha256)
To generate an SHA256 hash:
-
Pass a string (or a field containing a string) to the
sha256
helper. For example:If
field1
were set todocs@iterable.com
, this example would output3a86c6f084291fda367f24e885c74d2f1d50419eb4028d2b1bb2060d8f45ce0b
. -
Alternatively, use the
#sha256
block helper. For example:If
userName
were set todocs
andhost
were set toiterable.com
, this example would output the SHA256 hash fordocs@iterable.com
:3a86c6f084291fda367f24e885c74d2f1d50419eb4028d2b1bb2060d8f45ce0b
.
Pad a parameter (center)
For example, wrap the value of myMergeParam
in "-" characters, until the
total length is 20. For example:
Working with numbers (longs and doubles)
This section describes various helpers useful for working with longs and doubles in Handlebars.
Equals (#ifEq, eq)
There are various ways to test for if one number equals another number:
-
Use
#ifEq
to test if one number is equal to another number and to display a block of content if so.#ifEq
can compare numbers represented as strings, longs, and doubles. Arguments need not be of the same type.-
The following example displays "Equals" if
age
equals 21; otherwise, it displays "Not equals".The
{{else}}
block is optional.
-
Use
eq
to test two numbers for equality as part of a boolean expression.-
The following example compares two sets of numbers. If either set is equal, it displays "Found a match". Otherwise, it displays "No matches".
For numeric comparisons, both arguments passed to
eq
must be of the same type: double or long.-
To output a string based on the result of an
eq
comparison, set values foryes
andno
. For example: For more information on boolean and conditional logic, read Conditional and boolean logic.
-
Greater than (#ifGt, gt)
There are various ways to test whether one number is greater than another number:
-
Use
#ifGt
to test if one number is greater than another number and to display a block of content if so.#ifGt
can compare numbers represented as strings, longs, and doubles. Arguments need not be of the same type.-
The following example displays "Greater than" if
age
is greater than 21; otherwise, it displays "Not greater than".The
{{else}}
block is optional.
-
Use
gt
to test whether one number is greater than another number as part of a boolean expression.-
The following example compares two sets of numbers. If the first number is greater than the second in both sets, it displays "Both are greater than". Otherwise, it displays "At least one is not greater than".
For numeric comparisons, both arguments passed to
gt
must be of the same type: double or long.-
To output a string based on the result of an
gt
comparison, set values foryes
andno
. For example: If a
gt
expression references a non-existent or null field, the template will fail and the message will not be sent to that user.For more information on boolean and conditional logic, read Conditional and boolean logic.
-
Greater than or equal (#ifGte, gte)
There are various ways to test whether one number is greater than or equal to another number:
-
Use
#ifGte
to test if one number is greater than or equal to another number and to display a block of content if so.#ifGte
can compare numbers represented as strings, longs, and doubles. Arguments need not be of the same type.-
The following example displays "Greater than or equal" if
age
is greater than or equal to 21; otherwise, it displays "Not greater than or equal".The
{{else}}
block is optional.
-
Use
gte
to test whether one number is greater than or equal to another number as part of a boolean expression.-
The following example compares two numbers. If the first number is greater than or equal to the the second, it displays "Greater than or equal". Otherwise, it displays "Not greater than or equal".
For numeric comparisons, both arguments passed to
gte
must be of the same type: double or long.-
To output a string based on the result of an
gte
comparison, set values foryes
andno
. For example: If a
gte
expression references a non-existent field, the template will fail and the message will not be sent to that user.For more information on boolean and conditional logic, read Conditional and boolean logic.
-
Less than (#ifLt, lt)
There are various ways to test whether one number is less than another number:
-
Use
#ifLt
to test if one number is less than another number and to display a block of content if so.#ifLt
can compare numbers represented as strings, longs, and doubles. Arguments need not be of the same type.-
The following example displays "Less than" if
age
is less than 21; otherwise, it displays "Not less than".The
{{else}}
block is optional.
-
Use
lt
to test whether one number is less than another number as part of a boolean expression.-
The following example compares two sets of numbers. If the first number is less than the second in both sets, it displays "Both are less than". Otherwise, it displays "At least one is not less."
For numeric comparisons, both arguments passed to
lt
must be of the same type: double or long.-
To output a string based on the result of an
lt
comparison, set values foryes
andno
. For example: If an
lt
expression references a non-existent or null field, the template will fail and the message will not be sent to that user.For more information on boolean and conditional logic, read Conditional and boolean logic.
-
Less than or equal (#ifLte, lte)
There are various ways to test whether one number is less than or equal to another number:
-
Use
#ifLte
to test if one number is less than or equal to another number and to display a block of content if so.#ifLte
can compare numbers represented as strings, longs, and doubles. Arguments need not be of the same type.-
The following example displays "Less than or equal" if
age
is less than or equal to 21; otherwise, it displays "Not less than or equal".The
{{else}}
block is optional.
-
Use
lte
to test whether one number is less than or equal to another number as part of a boolean expression.-
The following example compares two numbers. If the first number is less than or equal to the the second, it displays "Less than or equal". Otherwise, it displays "Not less than or equal".
For numeric comparisons, both arguments passed to
lte
must be of the same type: double or long.-
To output a string based on the result of an
lte
comparison, set values foryes
andno
. For example: If an
lte
expression references a non-existent or null field, the template will fail and the message will not be sent to that user.For more information on boolean and conditional logic, read Conditional and boolean logic.
-
If remainder equals (#ifModEq)
If age
divided by 21 has a remainder or 0, output the contents of the block.
Formatting and rounding (numberFormat)
Use the numberFormat
helper to format and round numbers in various ways.
For example (all examples below use literal numbers, but the numberFormat
works with user profile and event data as well):
-
Format as currency
Output: $5.23
Output: 5,23 €
-
Format as percent
Output: 23%
-
Specify a maximum number of fractional digits
Output: 123.457
-
Specify a minimum number of fractional digits
Output: 123.40000
-
Group digits for easy reading
Output: 1,000,000
-
Use a custom format (as specified by the
DecimalFormat
documentation) Output: 1,234.57
Output: 3.00
-
Round
-
Up (away from zero)
Output: 6
-
Down (towards zero)
Output: 5
-
Ceiling (towards positive infinity)
Output: -5
-
Floor (towards negative infinity)
Output: -6
-
Half even (towards the nearest neighbor; if equidistant, round towards the even neighbor)
Output: 6
-
Half up (towards the nearest neighbor; if equidistant, round up)
Output: -6
-
Half down (towards the nearest neighbor; if equidistant, round down)
Output: -5
NOTES
- When no
roundingMode
is specified,half_even
is used. - For more information and examples, see the Java
RoundingMode
documentation.
-
Addition, subtraction, multiplication, division, modulo (math)
Use the math
helper to perform calculations. For example (all examples
below use literal numbers, but the math
works with user profile and event
data as well):
-
Addition
Output: 5
-
Subtraction
Output: 1
-
Multiplication
Output: 6
-
Division
Output: 1.5
-
Modulo
Output: 1
Working with lists/arrays
This section describes various helpers useful for working with lists
(such as shoppingCartItems
) in Handlebars.
Show item at index (square brackets)
In this example works with the shoppingCartItems
array, accessing the name of
the second item. Note that the array index starts at 0, so the second item is
located at index 1.
Iterating over all values (#each)
This example iterates through the shoppingCartItems
array, displaying the
name
and price
for each item.
You can also capture the index number that is being iterated over by
referencing @index
. If referencing @index
, keep in mind that the first item
in an array has index 0.
For a more detailed example of how to use #each
and @index
, read
Conditional Logic with Handlebars.
Concatenate values in an array into a single string (join)
Optionally, separate array values by one or more characters (eg. ", "). Prefix and suffix are optional.
Check for an item (#ifContains)
This example iterates over the shoppingCartItems
array, determining whether
it contains both, either, or neither "chips" and "dip".
Minimum value in list (#minInList)
This example finds the least expensive item in the shoppingCartItems
array,
based on the price
field of each item:
Maximum value in list (#maxInList)
This example finds the most expensive item in the shoppingCartItems
array,
based on the price
field of each item.
Size (size)
This example finds the sizes of the shoppingCartItems
array.
Comparing two arrays (#eq, eq, #neq, neq)
To compare two arrays, use the #eq
, eq
, #neq
, and neq
helpers.
For two arrays to be considered equal, each array must have the same length and equal items, in the same order.
For example, consider the following arrays, as might be stored on a user profile:
-
array1
=[1,2,3,4,5]
-
array2
=[1,2,3,4,5]
-
array3
=[4,5]
Use the #eq
block helper to output a block of content when two arrays are
equal.
-
The following example outputs "The arrays are equal":
-
The following example outputs "The arrays are not equal":
The
#neq
helper works similarly, but returns true when the two arrays are not equal.Use the (non-block)
eq
helper to compare arrays as part of a boolean expression.-
The following example outputs "The arrays are equal and contain more than two items":
The
ne
helper works similarly, but returns true when the two arrays are not equal.
First and last items (@first, @last)
This example finds the first and last items in the shoppingCartItems
array.
Working with objects
This section describes Handlebars helpers that can be used when working with objects.
Comparing two objects (#eq, eq, #neq, neq)
To compare two objects, use the #eq
, eq
, #neq
, and neq
helpers.
For two objects to be considered equal, each must have the exact same set of keys and values.
For example, consider the following arrays, as might be stored on a user profile:
-
obj1
:{ "a": 1, "b": 2 }
-
obj2
:{ "a": 1, "b": 2 }
-
obj3
:{ "a": 1, "b": 3 }
Use the #eq
block helper to output a block of content when two objects are
equal.
-
The following example outputs "The objects are equal":
-
The following example outputs "The objects are not equal":
The
#neq
helper works similarly, but returns true when the two objects are not equal.Use the (non-block)
eq
helper to compare objects as part of a boolean expression.-
The following example outputs "The objects are equal and b is 2":
The
ne
helper works similarly, but returns true when the two objects are not equal.
Working with dates
This section describes various helpers useful for working with dates in Handlebars.
Date comparison (#ifGt, #ifGte, #ifLt, #ifLte)
The numeric conditionals (#ifGt
, #ifGte
, #ifLt
, #ifLte
) work with
appropriately formatted dates, since the date strings can be formatted as
numeric strings.
Example using #ifGte
:
Example using #ifLt
:
Date formatting (dateFormat)
dateFormat
outputs a given date in the provided format.
Usage (dateFormat)
For example:
Parameters:
-
inputDate
(required)- A string that represents a valid date (either a string literal or a variable that contains a date string).
- Valid input date formats:
-
yyyy-MM-dd HH:mm:ss Z
- For example:
"2018-01-01 00:00:00 -0800"
"2018-06-22 14:00:00 +07:00"
- For example:
- yyyy-MM-dd HH:mm:ss
- Input formats accepted by
dateOptionalTimeParser
-
yyyy-MM-dd HH:mm:ss Z
-
format
(optional)- The format in which to output the date.
- Acceptable values defined by
java.text.SimpleDateFormat
- For example, the following expression outputs a given date's day of the
week (as a number):
- Additional formats include
"short"
,"medium"
,"long"
, and"full"
-
tz
(optional)- The time zone in which to output the date.
- For a list of time zone values, take a look at this blog post
- For example, the following expression takes a date (defined in UTC) and
outputs it in New York's time zone:
- Alternatively, use
tz=timeZone
to select thetimeZone
defined on the user's profile (if applicable).
NOTE
dateFormat
supports an alternate syntax, which uses positional
parameters instead of named parameters:
For example:
When using this syntax:
-
formatString
should be specified in the same way as theformat
parameter, above. - If
formatString
is provided, alocaleString
can also be given. Its value, a string, should be specified as follows:"languageCode_countryCode"
-
languageCode
should be lowercase -
countryCode
should be uppercase -
languageCode
andcountryCode
must be separated by an underscore. - For example:
"en_ES"
,"de_DE"
,"fr_FR"
, etc.
- It is not possible to pass a
localeString
without aformatString
.
full (dateFormat)
Example output: Tuesday, June 19, 2017
long (dateFormat)
Example output: June 19, 2017
medium (dateFormat)
Example output: Jun 19, 2017
short (dateFormat)
Example output: 6/19/17
Format with locale (dateFormat)
Example output: 21. Juni 2017
Format with time zone (dateFormat)
Date math (dateMath)
dateMath
takes a given date and applies date math to it, as specified by a
provided mathematical expression.
Usage (dateMath)
For example:
Parameters:
-
inputDate
(required)- A string that represents a valid date (either a string literal or a variable that contains a date string).
- Valid input date formats:
-
yyyy-MM-dd HH:mm:ss Z
- For example:
"2018-01-01 00:00:00 -0800"
"2018-06-22 14:00:00 +07:00"
- For example:
- yyyy-MM-dd HH:mm:ss
- Input formats accepted by
dateOptionalTimeParser
-
"now"
- The current time (for the time zone defined by the
tz
parameter, if available)
- The current time (for the time zone defined by the
"midnight"
- Midnight for the current day (for the time zone defined by the
tz
parameter, if available)
-
yyyy-MM-dd HH:mm:ss Z
-
dateMathExpression
(required)- A string that represents the date math to apply to
inputDate
. - In a date math expression, use the following time units:
-
y
: Years -
M
: Months -
w
: Weeks -
d
: Days -
h
orH
: Hours -
m
: Minutes -
s
: Seconds
-
- Example:
- This expression starts with
dateParameter
, adds one year, subtracts one month, adds one week, subtracts one day, adds one hour, subtracts one minute, and adds one second.
- A string that represents the date math to apply to
-
format
(optional)- The format in which to output the date.
- Acceptable values defined by
org.joda.time.format.DateTimeFormat
- For example, the following expression subtracts five hours from a given
date and outputs the day of the week (as a number) associated with the
result:
- Additional formats include
"short"
,"medium"
,"long"
, and `"full
-
tz
(optional)- The time zone in which to output the date.
- For a list of time zone values, take a look at this blog post
- For example, the following expression takes an input date (defined in
UTC), subtracts one hour, and outputs the result in New York's time zone:
- Use
tz=timeZone
to select thetimeZone
defined on the user's profile (if applicable)
-
locale
(optional)- Localizes the output to the given language/locale combination.
- Format:
"languageCode_countryCode"
-
languageCode
should be lowercase -
countryCode
should be uppercase -
languageCode
andcountryCode
must be separated by an underscore.
-
- For example, the following expression takes an input date, adds two
hours, and outputs the result for locale
es_ES
:Output: "1 de enero de 2018"
Date math from a given date (dateMath)
Date math from now (dateMath)
Number of days away from a given date (dateMath)
Calculate a person's age (dateMath)
Current date and time (now)
now
outputs the current date and time in the provided format.
Usage (now)
For example:
Parameters:
-
format
(optional)- The format in which to output the date.
- Acceptable values defined by
java.text.SimpleDateFormat
- For example, the following expression outputs the day of the week (as a
number) associated with the current time:
- Additional formats include
"short"
,"medium"
,"long"
, and"full"
Current year (now)
Name of the current day of the week (now)
Current time in epoch milliseconds (timestamp)
timestamp
outputs the current time in epoch milliseconds (number of
milliseconds since 1970-01-01 00:00:00 UTC).
Conditional and boolean logic
This section describes various conditional and boolean logic helpers supported by Handlebars.
True and false
Handlebars evaluates the following values as false:
-
null
values - Empty strings (
""
) - Empty arrays (
[]
) - The boolean value
false
- Any number with a value of zero (
0
,0.0
)
Other values evaluate to true.
If statements (#if)
The #if
helper evaluates a boolean expression. When true, the helper outputs
the contents of a block. The following example outputs "Hi active user!" when
activeUser
evaluates to true (see above); otherwise, it outputs "Hi inactive
user":
#if
can test nested conditions as demonstrated by the following example,
which outputs "You like pets!" to users whose likeCats
or likesDogs
user
profile field is set to true:
And (#and, and)
This section describes how to use #and
and and
in boolean expressions:
-
#and
is similar to#if
, except it evaluates any number of boolean expressions. If they all evaluate to true,#and
outputs its associated block. For example: -
#and
expressions can make use of other Handlebars helpers: -
There also exists a non-block
and
helper. The following example uses this helper to look for any users who like cats, or adults who like dogs: -
and
can output a value based on its evaluation. For example:
Or (#or, or)
This section describes how to use #or
and or
in boolean expressions:
-
#or
is similar to#if
, except it evaluates any number of boolean expressions. If any of those expressions evaluates to true,#or
outputs its associated block. For example: -
#or
expressions can make use of other Handlebars helpers: -
There also exists a non-block
or
helper. The following example uses this helper to look for any users who like cats and either like dogs or are an adult: -
or
can output a value based on its evaluation. For example:
Not (#not, not)
This section describes how to use #not
and not
in boolean expressions:
-
#not
negates the evaluation of a boolean expression. For example, if a user profile has alikesCats
value oftrue
, the following will return "The user does like cats!" -
#not
expressions can make use of other Handlebars helpers: -
There also exists a non-block
not
helper. The following example uses this helper to look for any users who like cats and are not adults: -
not
can output a value based on its evaluation. For example:
Unless (#unless)
#unless
outputs its associated block unless the boolean expression is true.
The following example outputs the text unless activeUser
has a value that
evaluates to true (see True and false).
Other Handlebars helpers
@key and this
If you iterate through an array or object like below:
"translations": {"en_US": "Hello","es_ES": "Hola"
You can use @key
to reference each key (for example, "en_US") and this to
reference each associated value (for example, "Hello"). Paired with the above
object, the below example would output "The translation for es_ES is Hola".
Looking up a value (#lookup)
If you structure your data feed to resemble the example below, you can leverage
the #lookup
helper. The email body of this particular example (below)
consists of two paragraphs:
This takes the language
value from the user's profile, and performs a lookup
against the greetings
array (in this case, matching on "en"). It then returns
the values associated with greeting_1
and greeting_2
within that object.
NOTE
If using #lookup
with the email
field or any other field whose values
contain periods ("."), you must set resolveKey=false
in order for the lookup
to succeed. For example
Assigning a variable (#assign)
You can use #assign
to set a variable that can be used at later points in a
template.
The above example would render "Greetings from Iterable!"
NOTE
The assigned variable will be considered a string.
Inserting fields into snippets
You can pass fields from your template into your snippet. To do so please follow this format:
JSON-LD
If you are using JSON-LD in your email template, you can use normal Handlebars format to include merge parameters inside the structured data block.
Further reading
This document covers many commonly used Handlebars helpers.
For a full list of available functions, take a look at Handlebars repository on GitHub.
For more examples of Handlebars logic, read Conditional Logic with Handlebars.
Comments
0 comments
Please sign in to leave a comment.