Articles in this section

Using Collections in Messages

Avatar
Brad
  • Updated
Follow

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:

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

  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 (docs@iterable.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 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:

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 Examples and Using Contact Properties, Event Properties, and Handlebars logic.

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

{{#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 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 the restaurant variable.
  • 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.

If the catalog lookup fails, a required=true attribute prevents the message from sending at all (instead of displaying an error message):

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

Further reading

Related articles

Comments

0 comments

Article is closed for comments.