Personalizing Templates with Handlebars

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

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:

{{#if activeUser}}
    <div>Hi active user!</div>
{{else}}
    <div>Hi inactive user</div>
{{/if}}

Instead, enter the following:

<!--{{#if activeUser}}-->
    <div>Hi active user!</div>
<!--{{else}}-->
    <div>Hi inactive user</div>
<!--{{/if}}-->

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:

{{email}}

# 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:

{{[first name]}}
{{[1stName]}}
{{[User Signed Up].[First Name]}}

# 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:

{{{customHTMLparameter}}}

[[{customHTMLparameter}]]

# 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.

{{capitalize "war and peace"}}
{{capitalize favoriteBook}}

# Helpers

A Handlebars helper is a function that takes zero or more parameters and returns a value. For example:

{{capitalizeFirst firstName}}

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 :

{{capitalizeFirst (lower firstName)}}

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:

{{#each shoppingCartItems}}
    <div>Item name: {{name}}</div>
    <div>Item price: {{price}}</div>
{{/each}}

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:

{{#ifMatchesRegexStr gender "male"}}
    <div>Buy this tie!</div>
{{/ifMatchesRegexStr}}

Match a substring:

{{#ifMatchesRegexStr catName ".*[Bb]ojangles.*"}}
    <div>Is your cat's name Mr. Bojangles?</div>
{{/ifMatchesRegexStr}}

# Contains a substring (#ifContainsStr)

Search a string for a particular substring. If the substring is found, render the block's content. For example:

{{#ifContainsStr haystack "needle"}}
    <div>Haystack contains needle!</div>
{{/ifContainsStr}}

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

For example:

• To check whether "cat" comes before "dog" in alphabetical order:

  {{#lt "cat" "dog"}}
      cat comes before dog!
  {{else}}
      dog comes before cat!
  {{/lt}}
  

  This expression renders "cat comes before dog!"

• To check whether "dog" comes after "cat" in alphabetical order:

  {{#gt "dog" "cat"}}
      dog comes after cat!
  {{else}}
      dog comes before cat!
  {{/lt}}
  

  This expression renders "dog comes after cat!"

• To perform a string comparison in a boolean expression, use the non-block versions of these helpers:

  {{#if (gt "dog" "cat")}}
      dog comes after cat!
  {{else}}
      dog comes before cat!
  {{/if}}
  

• 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:

{{myMergeParam.length}}

# Capitalize first letter of a string (capitalizeFirst)

Use the capitalizeFirst helper to capitalize the first letter of a string. For example:

{{capitalizeFirst myMergeParam}}

# 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 myMergeParam}}

# Capitalize entire string (upper)

Use the upper helper to capitalize every letter in a string. For example:

{{upper myMergeParam}}

# Lowercase entire string (lower)

Use the lower method to lowercase every letter in a string. For example:

{{lower myMergeParam}}

# 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:

{{defaultIfEmpty myMergeParam "defaultValue"}}

# Render HTML contained within a field

To render HTML contained in a field, wrap the field in triple curly braces. For example:

{{{myMergeParam}}}

# 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:

{{cut myMergeParam " "}}

# 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:

{{replace myMergeParam " " "-"}}

# 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):

{{substring myMergeParam 0 2}}

# 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:

{{abbreviate myMergeParam 7}}

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":

{{slugify myMergeParam}}

# Replace newlines (#breaklines)

To replace "\n" or "\r\n" with "<br/>", use the #breaklines block helper. For example:

{{#breaklines}}{{myMergeParam}}{{/breaklines}}

# URL encoding (#urlEncode)

To URL encode a string, use the #urlEncode block helper. For example:

{{#urlEncode}}{{myMergeParam}}{{/urlEncode}}

# Write the provided argument as a JSON string (toJson)

Output the parameter in its JSON representation. For example:

{{toJson myMergeParam}}

# Write the provided argument as a URL encoded JSON string (toUrlEncodedJson)

Output the parameter in its URL-encoded JSON representation. For example:

{{toUrlEncodedJson myMergeParam}}

# Base64 encode a merge parameter (#base64)

Base64 encode the parameter. Use to Base64 encode email addresses in URLs. For example:

{{#base64}}{{myMergeParam}}{{/base64}}

# 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:

{{hmacSHA1 field1 field2 myMergeParam}}

# 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:

  {{sha1 field1}}
  

  If field1 were set to docs@iterable.com, this example would output e364ed2661a7b922e5bf670f2a0946977bf63ae7.

• Alternatively, use the #sha1 block helper. For example:

  {{sha1}}{{userName}}@{{host}}{{/sha1}}
  

  If userName were set to docs and host were set to iterable.com, this example would output the SHA1 hash for docs@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:

  {{md5 field1}}
  

  If userName were set to docs and host were set to iterable.com, this example would output the SHA1 hash for docs@iterable.com: 0e13848b1c7e27eb5d88c5d35b70783e.

• Alternatively, use the #md5 block helper. For example:

  {{#md5}}{{userName}}@{{host}}{{/md5}}
  

  If userName were set to docs and host were set to iterable.com, this example would output the MD5 hash for docs@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:

  {{sha256 field1}}
  

  If field1 were set to docs@iterable.com, this example would output 3a86c6f084291fda367f24e885c74d2f1d50419eb4028d2b1bb2060d8f45ce0b.

• Alternatively, use the #sha256 block helper. For example:

  {{#sha256}}{{userName}}@{{host}}{{/sha256}}
  

  If userName were set to docs and host were set to iterable.com, this example would output the SHA256 hash for docs@iterable.com: 3a86c6f084291fda367f24e885c74d2f1d50419eb4028d2b1bb2060d8f45ce0b.

# Pad a parameter (center)

For example, wrap the value of myMergeParam in "-" characters, until the total length is 20. For example:

{{center myMergeParam size=20 pad="-"}}

# 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:

1. 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".

     {{#ifEq age 21}}
         <div>Equals</div>
     {{else}}
         <div>Not equals</div>
     {{/ifEq}}
     

     The {{else}} block is optional.

2. 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".

     {{#or (eq 1 numberOfPurchases) (eq 3 numberOfVisits)}}
         Found a match
     {{else}}
         No matches
     {{/or}}
     

   • 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 for yes and no. For example:

     {{eq 1 numberOfPurchases yes="Equal" no="Not equal"}}
     

   • 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:

1. 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".

     {{#ifGt age 21}}
         <div>Greater than</div>
     {{else}}
         <div>Not greater than</div>
     {{/ifGt}}
     

     The {{else}} block is optional.

2. 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".

     {{#and (gt 5 numberOfPurchases) (gt 3 numberOfVisits)}}
         Both are greater than
     {{else}}
         At least one is not greater than
     {{/and}}
     

   • 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 for yes and no. For example:

     {{gt 1 numberOfPurchases yes="Greater than" no="Not greater than"}}
     

   • 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:

1. 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".

     {{#ifGte age 21}}
         <div>Greater than or equal</div>
     {{else}}
         <div>Not greater than or equal</div>
     {{/ifGte}}
     

     The {{else}} block is optional.

2. 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".

     {{#if (gte 5 numberOfPurchases)}}
         Greater than or equal
     {{else}}
         Not greater than or equal
     {{/if}}
     

   • 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 for yes and no. For example:

     {{gte 1 numberOfPurchases yes="Greater than or equal" no="Not greater than or equal"}}
     

   • 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:

1. 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".

     {{#ifLt age 21}}
         <div>Less than</div>
     {{else}}
         <div>Not less than</div>
     {{/ifLt}}
     

     The {{else}} block is optional.

2. 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."

     {{#and (lt 5 numberOfPurchases) (lt 3 numberOfVisits)}}
         Both are less than
     {{else}}
         At least one is not less than
     {{/and}}
     

   • 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 for yes and no. For example:

     {{lt 1 numberOfPurchases yes="Less than" no="Not less than"}}
     

   • 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:

1. 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".

     {{#ifLte age 21}}
         <div>Less than or equal</div>
     {{else}}
         <div>Not less than or equal</div>
     {{/ifLte}}
     

     The {{else}} block is optional.

2. 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".

     {{#if (lte 5 numberOfPurchases)}}
         Less than or equal
     {{else}}
         Not less than or equal
     {{/if}}
     

   • 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 for yes and no. For example:

     {{lte 1 numberOfPurchases yes="Less than or equal" no="Not less than or equal"}}
     

   • 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.

{{#ifModEq age 21 0}}
    <div>Age % 21 == 0 (age is a multiple of 21)</div>
{{/ifModEq}}

# 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):

# 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.

<div>Item name: {{shoppingCartItems.[1].name}}</div

# Iterating over all values (#each)

This example iterates through the shoppingCartItems array, displaying the name and price for each item.

{{#each shoppingCartItems}}
    <div>Item name: {{name}}</div>
    <div>Item price: {{price}}</div>
{{/each}}

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.

{{#each shoppingCartItems}}
    <div>Item {{math @index '+' 1}} name: {{name}}</div>
{{/each}}

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.

{{join myMergeParam ", " prefix="Start - " suffix=" - End"}}

# Check for an item (#ifContains)

This example iterates over the shoppingCartItems array, determining whether it contains both, either, or neither "chips" and "dip".

{{#ifContains shoppingCartItems '{"productName":"chips"}'}}
   {{#ifContains shoppingCartItems '{"productName":"dip"}'}}
      <div>You have chips and dip in your cart!</div>
   {{else}}
      <div>You just have chips in your cart!</div>
   {{/ifContains}}
{{else}}
   {{#ifContains shoppingCartItems '{"productName":"dip"}'}}
      <div>You just have dip in your cart</div>
   {{else}}
      <div>You have neither chips nor dip in your cart!</div>
   {{/ifContains}}
{{/ifContains}}

# Minimum value in list (#minInList)

This example finds the least expensive item in the shoppingCartItems array, based on the price field of each item:

{{#minInList shoppingCartItems "price"}}
    <div>The least expensive item in your cart is: {{price}}</div>
{{/minInList}}

# Maximum value in list (#maxInList)

This example finds the most expensive item in the shoppingCartItems array, based on the price field of each item.

{{#maxInList shoppingCartItems "price"}}
    <div>The most expensive item in your cart is: {{price}}</div>
{{/maxInList}}

# Size (size)

This example finds the sizes of the shoppingCartItems array.

{{shoppingCartItems.size}}

# 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":

  {{#eq array1 array2}}
      The arrays are equal
  {{else}}
      The arrays are not equal
  {{/eq}}
  

• The following example outputs "The arrays are not equal":

  {{#eq array1 array3}}
      The arrays are equal
  {{else}}
      The arrays are not equal
  {{/eq}}
  
  

• 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":

  {{#and (gt array1.size 2) (eq array1 array2)}}
      The arrays are equal and contain more than two items
  {{else}}
      The arrays are not equal, or they don't contain more than two items.
  {{/and}}
  

• 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.

{{#each shoppingCartItems}}
    {{#if @first}}
        <div>The first item is {{name}}</div>
    {{/if}}
    {{#if @last}}
        <div>The last item is {{name}}</div>
    {{/if}}
{{/each}}

# 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 objects, 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":

  {{#eq obj1 obj2}}
      The objects are equal
  {{else}}
      The objects are not equal
  {{/eq}}
  

• The following example outputs "The objects are not equal":

  {{#eq obj1 obj3}}
      The objects are equal
  {{else}}
      The objects are not equal
  {{/eq}}
  
  

• 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":

  {{#and (eq obj1 obj2) (eq obj1.b 2)}}
      The objects are equal and b is 2
  {{else}}
      The objects are not equal or b is not 2
  {{/and}}
  

• 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:

{{#ifGte (dateFormat signupDate format="yyyyMMddHHmmss" tz="UTC") (dateMath "now" "-1M" format="yyyyMMddHHmmss" tz="UTC")}}
    <div>signupDate is within the last month</div>
{{else}}
    <div>signupDate was before the last month</div>
{{/ifGte}}

Example using #ifLt:

{{#ifLt (dateFormat signupDate format="yyyyMMddHHmmss" tz="UTC") "20170630000000"}}
    <div>signupDate is before 6/30/17</div>
{{else}}
    <div>signupDate after or on 6/30/17</div>
{{/ifLt}}

# Date formatting (dateFormat)

dateFormat outputs a given date in the provided format.

# Usage (dateFormat)

{{dateFormat inputDate format="formatString" tz="timeZoneString"}}

For example:

{{dateFormat "2018-06-22 14:00:00 +07:00" format="yyyy-MM-dd HH:mm:ss Z" tz="America/Denver"}}

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"
    • yyyy-MM-dd HH:mm:ss
    • Input formats accepted by dateOptionalTimeParser

• 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):

    {{dateFormat date format="u"}}
    

  • 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:

    {{dateFormat "2018-01-01 00:00:00" tz="America/New_York"}}
    

  • Alternatively, use tz=timeZone to select the timeZone defined on the user's profile (if applicable).

{{dateFormat inputDate formatString localeString}}

{{dateFormat "2018-06-01 00:00:00" "full" "es_ES"}}

# full (dateFormat)

{{dateFormat myDateField format="full"}}

Example output: Tuesday, June 19, 2017

# long (dateFormat)

{{dateFormat myDateField format="long"}}

Example output: June 19, 2017

# medium (dateFormat)

{{dateFormat myDateField format="medium"}}

Example output: Jun 19, 2017

# short (dateFormat)

{{dateFormat myDateField format="short"}}

Example output: 6/19/17

# Format with locale (dateFormat)

{{dateFormat myDateField "long" "de_DE"}}

Example output: 21. Juni 2017

# Format with time zone (dateFormat)

{{dateFormat myDateField tz="America/Los_Angeles"}}

# Date math (dateMath)

dateMath takes a given date and applies date math to it, as specified by a provided mathematical expression.

# Usage (dateMath)

{{dateMath inputDate dateMathExpression format="formatString" tz="timeZoneString"}}

For example:

{{dateMath dateParameter "-5h" format="yyyy-MM-dd HH:mm:ss Z" tz="America/New_York" locale="es_ES"}}

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"
    • 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)
    • "midnight"
    • Midnight for the current day (for the time zone defined by the tz parameter, if available)

• 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 or H: Hours
    • m: Minutes
    • s: Seconds
  • Example:

    {{dateMath dateParameter "+1y-1M+1w-1d+1h-1m+1s"}}
    

  • 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.

• 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:

    {{dateMath date "-5h" format="e"}}
    

  • 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:

    {{dateMath "2018-01-01 00:00:00" "-1h" tz="America/New_York}}
    

  • Use tz=timeZone to select the timeZone 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 and countryCode 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:

    {{dateMath "2018-01-01 00:00:00" "+2h" format="long" locale="es_ES"}}``
    

    Output: "1 de enero de 2018"

# Date math from a given date (dateMath)

{{dateMath myDateField "+1y-1M+3w-17d+7h+1m-50s"}}

# Date math from now (dateMath)

{{dateMath "now" "-24h" format="yyyyMMddHHmmss"}}

# Number of days away from a given date (dateMath)

{{dateMath myDateField (now format="-y'y'+1'y'-M'M'+1'M'-d'd'+1'd'-H'H'-m'm'-s's'" tz="UTC") format="D"}}

# Calculate a person's age (dateMath)

{{dateMath birthDateField (now format="-y'y'+1'y'-M'M'+1'M'-d'd'+1'd'-H'H'-m'm'-s's'" tz="UTC") format="yy"}}

# Current date and time (now)

now outputs the current date and time in the provided format.

# Usage (now)

{{now format="formatString"}}

For example:

{{now format="yyyy"}}

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:

    {{now format="u"}}
    

  • Additional formats include "short","medium", "long", and "full"

# Current year (now)

{{now format="yyyy"}}

# Name of the current day of the week (now)

{{now format="EEEE"}}

# 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).

{{timestamp}}

# 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 activeUser}}
    <div>Hi active user!</div>
{{else}}
    <div>Hi inactive user</div>
{{/if}}

#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:

{{#if likesCats}}
    <div>You like pets!</div>
{{else}}
    {{#if likesDogs}}
        <div>You like pets!</div>
    {{/if}}
{{/if}}

# 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 likesCats likesDogs}}
      <div>You like cats and dogs!</div>
  {{else}}
      <div>There are some pets you don't like!</div>
  {{/and}}
  

• #and expressions can make use of other Handlebars helpers:

  {{#and likesCats (gte age 18)}}
      You're an adult who likes cats!
  {{else}}
      You're not an adult, or you don't like cats, or both!
  {{/and}}
  

• 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:

  {{#or likesCats (and likesDogs (gte age 18))}}
      Either you like cats or you're an adult who likes dogs!
  {{/or}}
  

• and can output a value based on its evaluation. For example:

  {{and likesCats likesDogs likesHamsters yes="Likes all the pets" no="Does not like all the pets"}}
  

# 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 likesCats likesDogs}}
      <div>You like cats or dogs!</div>
  {{else}}
      <div>You do not like cats, and you do not like dogs!</div>
  {{/or}}
  

• #or expressions can make use of other Handlebars helpers:

  {{#or likesCats (gte age 18)}}
      You like cats, or you're an adult!
  {{else}}
      You don't like cats and you're not an adult!
  {{/or}}
  

• 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:

  {{#and likesCats (or likesDogs (gte age 18))}}
      You like cats, and you either like dogs or you're an adult.
  {{/and}}
  

• or can output a value based on its evaluation. For example:

  {{or likesCats likesDogs likesHamsters yes="You like at least one kind of pet" no="You are not a pet person"}}
  

# 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 a likesCatsvalue of true, the following will return "The user does like cats!"

  {{#not likesCats}}
      The user does not like cats!
  {{else}}
      The user does like cats!
  {{/not}}
  

• #not expressions can make use of other Handlebars helpers:

  {{#not (gte age 18)}}
      You are not an adult.
  {{else}}
      You are an adult!
  {{/not}}
  

• 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:

  {{#and likesCats (not (gte age 18))}}
      You like cats and you are not an adult.
  {{/and}}
  

• not can output a value based on its evaluation. For example:

  {{not likesCats yes="You do not like cats" no="You do like cats"}}
  

# 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).

{{#unless activeUser}}
    <div>Hey inactive user, come on back!</div>
{{/unless}}

# 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".

{{#each translations}}
    {{#ifContainsStr @key "es"}}
        <div>The translation for {{@key}} is {{this}}</div>
    {{/ifContainsStr}}
{{/each}}

# 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:

{{#lookup greetings language as |lang|}}{{lang.greeting_1}}{{/lookup}}
{{#lookup greetings language as |lang|}}{{lang.greeting_2}}{{/lookup}}

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.

{{#lookup greetings email resolveKey=false as |df_email|}}

# Assigning a variable (#assign)

You can use #assign to set a variable that can be used at later points in a template.

{{#assign "myVar"}}Iterable{{/assign}}
Greetings from {{myVar}}

The above example would render "Greetings from Iterable!"

# Inserting fields into snippets

You can pass fields from your template into your snippet. To do so please follow this format:

{{snippet "snippetname" arg0=x arg1=y ...}}

# 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.