This document answers common questions about how to work with Handlebars when creating an Iterable template.
In this article
- How do I capitalize the first letter of a word?
- How do I reference the first letter of someone's name?
- How do I check if a field is set?
- How do I display a default value if a field is not set?
- How do I use conditional logic with strings?
- Why does my Handlebars give me an error?
- The value of a field contains an apostrophe. Why doesn't it render correctly?
- Why does my merge parameter not render properly?
- How do I create a CTA button from a URL parameter?
- Why does data from my data feed not render correctly?
- When do I comment out Handlebars?
- How do I format a URL dynamically?
- How do I output every item in an array?
- How do I output some (but not all) of an array's items?
- How do I limit the number of items in an #each array?
- How do I check an array for a particular value?
- How do I check the size of an array?
- How do I use the now helper to format the current time?
- How can I display the number of days since a user signed up?
- How do I output the current month/year/day of week?
- How do I reference items in a nested object?
- Want to learn more?
How do I capitalize the first letter of a word?
Use the capitalize
helper. For example:
How do I reference the first letter of someone's name?
Use the substring
helper. For example:
substring
requires three parameters:
- The string from which to pull the substring
- The starting index of the substring
- The last index of the substring, plus one
How do I check if a field is set?
Use the #if
block helper. For example:
In this example, {{#if activeUser}}
evaluates to false if activeUser
is not set on the current user's Iterable profile.
This type of check works for numbers, strings, arrays, and objects.
How do I display a default value if a field is not set?
Use the defaultIfEmpty
helper. For example:
If firstName
is not set, this example outputs, "Hi there". Otherwise, it
outputs something like "Hi John" (with the current user's firstName
).
How do I use conditional logic with strings?
Use the #eq
, #lt
, #lte
, #gt
, and #gte
methods. For example:
Why does my Handlebars give me an error?
Make sure that you balance each opening and closing expressions for Handlebars block helpers.
For example, the following Handlebars has two opening #if
expressions,
but only one closing /if
expression:
Each time you open a Handlebars block helper, you must also close it. The above code should look like this:
The value of a field contains an apostrophe. Why doesn't it render correctly?
When using a Handlebars expression to render a field, Iterable renders an
apostrophe using an HTML character encoding: '
.
For example, for a phrase
field with a value of "It's ok to be different",
an Iterable template would render {{phrase}}
as:
It's ok to be different
To prevent this from happening, use triple curly braces in the Handlebars expression:
Why does my merge parameter not render properly?
To render a field whose name contains a space, surround the field name with square brackets inside the Handlebars expression's double curly braces:
For example:
Or, in a conditional:
How do I create a CTA button from a URL parameter?
To add a URL parameter to a CTA button, use this syntax:
For example, this expression will display a "Shop now!" button that contains a
link to the user's shoppingCart_url
:
Why does data from my data feed not render correctly?
To render a value from a data feed, use square brackets. For example:
However, with a template's Merge the Data Feed and User Contexts checkbox enabled, you can use curly braces to reference data feed data as well.
When do I comment out Handlebars?
Sometimes the template editor might try to render a Handlebars expression as HTML. To prevent this, wrap the Handlebars expression in a comment:
<!-- {{ ... }} -->
For example:
<!--{{#if [First Name]}}--> Hi {{[First Name]}}! <!--{{/if}}-->
In this example, the comments prevent the template from trying to render the
#if
block. However, the greeting outputs as expected if the First Name
field is set.
TIPS
- Do not comment out any line of Handlebars that outputs a value. If you do so, it will be commented out in the resulting HTML and won't render in the template.
- For more details, read Using Handlebars in HTML source
- Do not comment out Handlebars expressions in the subject line.
How do I format a URL dynamically?
To append the value of a field to the end of a URL, use a Handlebars expression such as:
In this case, userPath
might contain a value such as "/lastSavedSearch",
and the full URL value would render as:
https://www.yoursite.com/lastSavedSearch
How do I output every item in an array?
Use the #each
block helper to iterate over each item in an array.
For example, consider a user profile that contains a petNames
array with
two strings:
{ ... "petNames": ["Bella", "Fido"] ... }
The following code will output both pet names, since the this
keyword
accesses the value of the current item in the array:
If the array contains objects, you can access each field in the object
while iterating through the array. For example, consider a shoppingCart
array that contains two objects:
shoppingCart: [ { id: 0, name: "bottle", price: 10.00 }, { id: 1, name: "chips", price: 2.50 } ]
To display the information associated with each item in the array, use code similar to the following:
This code would putput:
<div>Item name: bottle</div> <div>Item price: 10.00</div> <div>Item name: chips</div> <div>Item price: 2.50</div>
How do I output some (but not all) of an array's items?
Consider a user profile with the following articles
array:
{ "articles": [{ "name": "5 Great Cat Stories", "url": "/5-great-cat-stores", "id": "123-A", "category": "cats", "tags": ["stories", "cats", "listicle"] }, { "name": "5 Amazing Dog Rescues", "url": "/5-amazing-dog-rescues", "id": "129-A", "category": "dogs", "tags": ["rescue", "dogs", "listicle"] }, { "name": "10 Birds Worth Watching", "url": "/10-birds-worth-watching", "id": "133-A", "category": "birds", "tags": ["birds", "bird watching", "listicle"] }] }
To display details for the articles about cats, use #each
to loop over the array and #ifMatchesRegexStr
to check each article's category
:
This outputs:
5 Great Cat Stories<br /> <a href="https://www.example.com/5-great-cat-stories">Read More</a><br /><br />
You can use this same approach with other Handlebars helpers, too. For example,
to display articles with the listicle
tag, you might use this code:
This outputs:
5 Great Cat Stories<br /> <a href="https://www.example.com/5-great-cat-stories">Read More</a><br /><br /> 5 Amazing Dog Rescues<br /> <a href="https://www.example.com/5-amazing-dog-rescues">Read More</a><br /><br /> 10 Birds Worth Watching<br /> <a href="https://www.example.com/10-birds-worth-watching">Read More</a><br /><br />
#each
array?
How do I limit the number of items in an To limit how many items the #each
helper displays, use a comparison helper.
For example, this array will only list three products from a user's profile:
How do I check an array for a particular value?
To determine if an array contains a particular value, use the #ifContains
block helper.
For example, consider a user profile that contains a petNames
array with
two strings:
{ ... "petNames": ["Bella", "Fido"] ... }
The following code checks the array for "Bella" and outputs some text:
Since the array contains "Bella", this code will output:
Bella is a good girl!
If the array doesn't contain "Bella", the code would output:
Bella isn't here right now.
How do I check the size of an array?
Use the size
method to get the size of an array, and then use conditional
logic as necessary.
For example, this code checks to see if there is one item in the
shoppingCartItems
array:
now
helper to format the current time?
How do I use the now
represents the current time, and accepts a format
string. For
example:
How can I display the number of days since a user signed up?
To calculate how long ago a user signed up, you can use a Handlebars expression like this:
NOTE
This logic doesn't account for leap years.
How do I output the current month/year/day of week?
Month
-
Month for a particular date
The following code:
Outputs:
June
-
Month for the current date
The following code:
Outputs (if run in July):
July
Year
-
Year for a particular date
The following code:
Outputs:
2018
-
Year for the current date
The following code:
Outputs (if run in 2019):
2019
Day of the week
-
Day of the week for a particular date
The following code:
Outputs:
Monday
-
Current day of the week
The following code:
Outputs (if run on a Wednesday):
Wednesday
TIPS
- For the full name for the month, use four or more
M
characters. For the abbreviated version of the month, use threeM
characters or less. - For more information about working with dates, read Working with dates.
How do I reference items in a nested object?
Consider the following data:
{ "property": { "items": [ { "id": "2", "sku": "4", "name": "Iterable T-shirt", "description": "100% cotton shirt. Show how much you love your favorite marketing automation platform!", "categories": [ "clothing", "swag" ], "price": 20.50, "quantity": 1, "imageUrl": "https://static.iterable.com/iterable/15-10-03-iterableshirt.png", "url": "iterable.com" }, { "id": "3", "sku": "5", "name": "Macadamia Nuts", "description": "Full of healthy fats! Made in Hawaii.", "categories": [ "food" ], "price": 5.50, "quantity": 2, "imageUrl": "https://nuts.com/images/auto/510x340/assets/4d57de389a2f6d59.jpg", "url": "iterable.com" } ] } }
-
Referencing the
categories
array in the first itemThe following code:
Outputs:
["clothing", "swag"]
-
Referencing the
categories
array in the second itemThe following code:
Outputs:
["food"]
-
Displaying the
categories
array from each itemThe following code:
Outputs:
["clothing", "swag"] ["food"]
-
Using custom HTML to display each item in each
categories
arrayThe following code:
Outputs:
I am purchasing clothing. I am purchasing swag. I am purchasing food.
Want to learn more?
For more information about some of the topics in this article, check out these resources. Iterable Academy is open to everyone — you don't need to be an Iterable customer!
Iterable Academy
Support docs