Articles in this section

Using Catalogs & Collections in Messages

NOTE

To add Catalog to your Iterable account, talk to your customer success manager.

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.

In this article

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:

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

    {{#catalogCollection "DeliveryBelowDinnerBudget" as |collection|}}
<!-- Your HTML goes here -->
{{/catalogCollection}}

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

  3. 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 comma-separated values):

    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:

  1. Using the Collection Builder, define a collection that searches for the appropriate data in the catalog:

    Example collection definition

    This collection definition compares each restaurant's averagePrice to the user's dinnerBudget, and makes sure that delivery is set to true.

  2. 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 (user@example.com) has a dinnerBudget of 10.50. For this reason, both restaurants in the collection have an averagePrice less than or equal to 10.50.

  3. 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:

    Handlebars snippet to embed the collection

    This Handlebars expression uses the #catalogCollection Handlebars method to reference the DeliveryBelowDinnerBudget collection, returning the results as a collection called collection.

    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 criteria (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:

Example template with collection reference

NOTE

#each iterates through all the items in a collection, allowing you to access and display each item's information in turn.

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. Then, loop through the remaining items with #each, using a conditional to exclude any items that have already been displayed:

{{#catalogCollection "DeliveryBelowDinnerBudget" as |collection|}}
<strong>{{collection.[0].name}}: {{collection.[0].averagePrice}}</strong>
{{#each collection}}
    {{#ifGt @index 0}}
        {{name}}: {{averagePrice}}
    {{/ifGt}}
{{/each}}
{{/catalogCollection}}

For more information, see Conditional Logic with Handlebars and Personalizing Templates 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:

{{#catalog "Restaurants" "JoesRestaurant" as |restaurant|}}
    The restaurant's average price is: {{numberFormat restaurant.averagePrice "currency"}}
{{/catalog}}

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 a single catalog item by name

To have a message template display the name and average price of the user's favorite restaurant, as stored in a string field, use Handlebars syntax such as the following:

{{#catalog "Restaurants" favoriteRestaurant as |restaurant|}}
    The average price at {{restaurant.name}} is {{numberFormat restaurant.averagePrice "currency"}}
{{else}}
    The user's favorite restaurant can't be found.
{{/catalog}}

This Handlebars template:

  • Looks at the favoriteRestaurant field on the current recipient's Iterable user profile (or the campaign's triggering API call). For example, this field might be set to JoesRestaurant.
  • Looks up this restaurant in the Restaurants catalog, making it available as the restaurant variable (an object).
  • Displays restaurant.name and restaurant.averagePrice in the message (using the numberFormat 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 the Restaurants catalog.

NOTE

If the #catalog helper can't locate a field with the passed-in name, or if it can't locate a catalog item associated with the string stored in that field, it returns nothing (or, if there's an {{else}} block, it executes that instead).

To throw an error instead, use the required=true attribute:

{{#catalog "Restaurants" favoriteRestaurant required=true as |restaurant|}}
    The average price at {{restaurant.name}} is {{numberFormat restaurant.averagePrice "currency"}}
{{/catalog}}

When specifying required=true, there's no need for the {{else}} block.

Accessing multiple catalog items by name

To have a message template display the name and average price of each of the user's favorite restaurants, as stored in an array of strings, use Handlebars syntax such as the following:

{{#catalogKeys "Restaurants" favoriteRestaurants as |restaurants|}}
   {{#each restaurants}}
      The average price at {{this.name}} is {{numberFormat this.averagePrice "currency"}}
	 {{/each}}
{{/catalogKeys}}

This Handlebars template:

  • Looks at the favoriteRestaurants field on the current recipient's Iterable user profile (or the campaign's triggering API call). For example, this field might be set to ["JoesRestaurant","KellysCafe"].
  • Looks up these restaurants in the Restaurants catalog, making them available in the restaurants variable (an array).
  • Displays each restaurant's name and average price (using the numberFormat Handlebars helper to format the average price as a currency).

NOTE

If the #catalogKeys helper can't find a user profile or event field with the passed-in name, it throws an error. If it can't find a catalog items corresponding to one of the strings in the passed-in array, it returns nothing for that string (if it can't find a catalog item for any of the strings in the array, the #each helper will have nothing to do).

Further reading

Related articles