NOTE
Contact your Iterable CSM to discuss adding Catalog to your plan.
Catalog stores information about your organization and projects in Iterable, making it available to campaigns to use when personalizing messages.
To display data from a catalog in a message, use Handlebars to either:
- Embed a collection
- Directly reference a catalog item by name (the name can be known ahead of time, or it can be a value stored on a user's Iterable profile).
This document describes how to do both of these things.
Table of contents
Embedding a collection in a message
One way to display catalog data in a message is to embed a collection. To do this, follow these steps:
-
When building a collection, click the Use In Template button to retrieve a Handlebars snippet that can be used to reference its data.
For example, the following Handlebars snippet embeds the
DeliveryBelowDinnerBudget
collection in a template: -
Paste the snippet into a message template. The snippet fetches the collection, which can contain zero, one, or many catalog items.
NOTE
The
#catalogCollection
Handlebars helper can only be used in message templates. Iterate over the catalog items, using Handlebars to access and display its data.
The following sections provide an example catalog, collection, and template.
Example catalog and user profile data
For the following example, assume that:
-
Your Iterable project has a
Restaurants
catalog that contains the following data (represented here as CSV):key,name,cuisine,averagePrice,delivery KateysBurgers,Katey's Burgers,Fast food,6.00,true JoesRestaurant,Joe's Restaurant,Italian,9.00,false KellysCafe,Kelly's Cafe,Ethiopian,12.00,false SalsKitchen,Sal's Kitchen,Mexican,14.00,false BobsSandwichShop,Bob's Sandwich Shop,Sandwiches,8.00,true
User profiles in the project have a
dinnerBudget
field (a double).
Example collection
Suppose you'd like to find all restaurants in the Restaurants
catalog for
which delivery is true
and averagePrice
is less than or equal to a user's
dinnerBudget
. Follow these steps to build a collection and get an
associated Handlebars snippet:
-
Using the collection builder, define a collection that searches for the appropriate data in the catalog:
This collection definition compares each restaurant's
averagePrice
to the user'sdinnerBudget
, and makes sure thatdelivery
is set totrue
. -
Preview the collection's items:
In the Preview with Sample Data from input, enter a test email address (for which the associated user profile has a
dinnerBudget
).-
Click Preview to view the catalog items in the collection.
In the screenshot above, the profile for the test user (
docs@iterable.com
) has adinnerBudget
of10.50
. For this reason, both restaurants in the collection have anaveragePrice
less than or equal to10.50
.
-
Get the Handlebars snippet that can be used to embed this collection in a template:
Click the Use In Template button and copy the Handlebars snippet:
This Handlebars expression uses the
#catalogCollection
Handlebars method to reference theDeliveryBelowDinnerBudget
collection, returning the results as a collection calledcollection
.The template can then iterate through this collection of results.
Collection failures
A collection can fail for various reasons. For example:
- An invalid collection name
- There are no valid results for the collection
- An invalid field for a dynamic search criterion (it doesn't exist on a particular user's profile)
When a collection fails to return results, one of two things can happen:
- If the Handlebars expression specifies
required=true
, then Iterable does not send the message. - Otherwise, the template does not render the Handlebars expression, but Iterable still sends the message.
Example template
The following message template fetches the DeliveryBelowDinnerBudget
collection and iterates over its results with the Handlebars #each
method.
Notice that the template refers to each item's name
, cuisine
,
averagePrice
, and delivery
fields:
NOTE
#each
However, in some cases you may want to highlight a collection's first item (or first few items) with a more vibrant visual style, and use a more subtle style for the remaining items.
To do this, reference the first item with a hard-coded index#each
, using a conditional to
exclude any items that have already been displayed:
For more information, see Conditional Logic with Handlebars
Referencing catalog items directly
Iterable templates can also use Handlebars to directly reference specific catalogs, catalog items, and their fields (instead of using a collection to run a dynamic query).
Example catalog and user profile data
For the following examples, assume that:
-
Your Iterable project has a
Restaurants
catalog that contains the following data (represented here as CSV):key,name,cuisine,averagePrice,delivery KateysBurgers,Katey's Burgers,Fast food,6.00,true JoesRestaurant,Joe's Restaurant,Italian,9.00,false KellysCafe,Kelly's Cafe,Ethiopian,12.00,false SalsKitchen,Sal's Kitchen,Mexican,14.00,false BobsSandwichShop,Bob's Sandwich Shop,Sandwiches,8.00,true
User profiles in the project have a
favoriteRestaurant
field (a string).
Accessing a catalog by name
For a message template to display the name
and averagePrice
of
JoesRestaurant
(one of the items in the Restaurants
catalog), it can use
a Handlebars expression similar to the following:
This Handlebars expression finds JoesRestaurant
in the Restaurants
catalog and makes it available as the restaurant
variable. It then displays
its averagePrice
.
NOTE
The #catalog
Handlebars helper can only be used in message templates.
Accessing catalog data by referencing a user profile or event field
To have a message template mention the name and average price of the user's favorite restaurant, use Handlebars syntax such as the following:
This Handlebars template does the following things:
- Looks at the
favoriteRestaurant
field on the current recipient's Iterable user profile (or the campaign's triggering event). - Finds the associated restaurant in the
Restaurants
catalog, making it available as therestaurant
variable. - Displays
restaurant.name
andrestaurant.averagePrice
in the message (using thenumberFormat
Handlebars helper to format the average price as a currency). - Displays "The user's favorite restaurant can't be found" if the user's
favoriteRestaurant
cannot be found in theRestaurants
catalog.
If the catalog lookup fails, a required=true
attribute prevents the
message from sending at all (instead of displaying an error message):
Comments
0 comments
Article is closed for comments.