Using Data Feeds in Snippets

You can pass data feed fields to snippets, which create reusable content blocks that display dynamic and/or personalized data from external sources. This is useful for things like product recommendation cards, article previews from a blog feed, or promotional banners that rotate through content from a marketing feed. This is an advanced use case that allows you to create more dynamic and personalized content in your templates with reusable content blocks.

# In this article

# How it works

Using data feeds in snippets involves multiple pieces working together:

• A data feed that contains the data you want to display.
• A snippet that accepts data feed fields as variables, forming a reusable content block you can use iteratively in your templates.
• A template that references the data feed and includes the snippet expression, exactly where you want the content to appear.
• A snippet expression that references the snippet and passes the data feed fields as variables to the snippet. This requires a Handlebars expression. If you're new to Handlebars, see Handlebars Overview to get started.

# Step 1: Create a data feed and add it to your project

First, you need to start with a data feed that's ready for use in Iterable. To learn about the data feed formats that Iterable supports, and some of the more technical details of how to create a data feed, see Creating a Data Feed Web Service.

Next, add the data feed to your project. To learn how, see Managing Data Feeds.

As a best practice, configure an alias for the data feed. An alias creates a unique namespace for your data feed fields so you can reference them under a prefix you choose (for example, blogFeed), which prevents field name collisions with user profile data. The examples in this guide use an alias for the data feed, though it is not required.

# Example use case — RSS blog feed

The examples in this article use an RSS blog feed as a data feed. RSS is a standard XML format commonly used for blog and news feeds, making it easy to adapt to your own content sources.

For an example of the RSS format that Iterable supports, see Creating a Data Feed Web Service — RSS data feed response format.

# Step 2: Create a snippet that accepts data feed fields

Create a snippet whose variables correspond to the data feed fields you want to display. The snippet doesn't need to know anything about the data feed itself—it just defines variables and uses them in its content. This separation is what makes the snippet reusable: the same snippet can work across different templates and different data feeds, as long as the variable names match.

To learn how to create a snippet, see Creating and Managing Snippets.

When you create your snippet, you'll need to decide which data feed fields you want to display, and then add them as variables to the snippet. To learn how, see Customizing Snippets with Variables.

# Example snippet for an RSS feed

Here is example content for a snippet named blogPost.

It contains three variables: title, description, and link.

This snippet represents what displays as a single blog post within the RSS feed. In the template, you'll reference this snippet for each item in the feed.

<div class="blog-post" style="padding: 16px; border: 1px solid #ddd; margin-bottom: 12px; border-radius: 6px;">
  <h3 style="font-family: Georgia, 'Times New Roman', serif; font-size: 20px; margin: 0 0 6px; color: #1a1a1a;">{{title}}</h3>
  <p style="font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif; font-size: 14px; color: #666; margin: 0 0 12px; line-height: 1.5;">{{description}}</p>
  <a href="{{link}}" style="font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif; font-size: 14px; color: #612C6A; text-decoration: none; font-weight: bold;">Read more &rarr;</a>
</div>

# Step 3: Configure the template to use the data feed

Some template settings are important to pay attention to when using data feeds in snippets because they directly impact the syntax for your snippets and the way you pass data feed fields to the snippet.

These settings are:

• Use Data Feed Alias - If using an alias for the data feed, enable this setting. Make sure your data feed has an alias set up first. To learn more, see Managing Data Feeds.

  Using a data feed alias is highly recommended when:

  • The template also uses the Merge the Data Feed and User Contexts setting.
  • The template uses multiple data feeds.

For full details on these settings and how to add a data feed to a template, see Using Data Feeds in Templates.

# Step 4: Create a snippet expression and add it to the template

Once your snippet is ready and the template is configured to use the data feed, create a snippet expression that references the snippet and passes the data feed fields as variables to the snippet.

How you build the expression depends on a few factors:

• Data feed alias: If the data feed alias is enabled, remember to prefix each data feed field path with the alias name.

• Displaying multiple items from an array: Decide on a method for displaying multiple items that's best for your use case.

  • Use indexed expressions to display a specific number of items, one at a time. To learn more, see Approach 1: Indexed expressions below.
  • Use the #each helper to display all items, or a limited number of items. To learn more, see Approach 2: The #each helper below.

• Namespaced fields or special characters: If any data feed field names contain special characters or are namespaced fields, make sure you know how to escape the characters correctly. See Referencing fields with special characters for instructions.

• Namespaced fields with sub-properties: Some properties, especially in RSS feeds, are nested within other properties. For example, an RSS feed might include a featured image for each post as a url sub-property in a media:content element. To access the image URL, you need to access the media:content property and then the url sub-property. To learn how to do this, see Passing sub-properties of namespaced fields to snippets below.

# Snippet expressions for data feed fields

When you create a snippet expression that references the snippet and passes the data feed fields as variables to the snippet, you need to use the appropriate syntax for the data feed fields.

The syntax for the data feed fields depends on the template settings and the data feed fields themselves. The following sections describe the different approaches you can take to display multiple items from a data feed.

# Displaying multiple items with indexed expressions

Indexed expressions allow for precise control over the position of each specific item in the template and a precise number of items to display.

To learn more about this approach to display multiple items for data feed arrays, see Using Data Feeds in Templates - Approach 1: Indexed expressions.

This example displays the first 3 items from the item array in the data feed using indexed expressions.

• Snippet name: blogPost
• Data feed alias: blogFeed
• Data feed fields in the item array: title, description, link
• Indexed expressions: blogFeed.item.[0], blogFeed.item.[1], blogFeed.item.[2]

{{{snippet "blogPost" blogFeed.item.[0].title blogFeed.item.[0].description blogFeed.item.[0].link}}}
{{{snippet "blogPost" blogFeed.item.[1].title blogFeed.item.[1].description blogFeed.item.[1].link}}}
{{{snippet "blogPost" blogFeed.item.[2].title blogFeed.item.[2].description blogFeed.item.[2].link}}}

# Displaying multiple items with the #each helper

Another way to display multiple items is by looping over the items in the data feed. To do this, you can use the #each helper to loop over the items in the data feed.

To learn more about the #each helper approach for displaying multiple items for data feed arrays, see Using Data Feeds in Templates - Approach 2: The #each helper.

You can use the #each helper to display all items, or a limited number of items.

# Example #each loop for all items

To loop over all items in the data feed, use the #each helper:

{{#each blogFeed.item}}
  {{{snippet "blogPost" this.title this.description this.link}}}
{{/each}}

# Example #each loop with a limit using the #lt helper

To limit the number of items displayed, use the #lt helper to check the index.

To learn more about the #lt helper, see Check whether one number is less than another.

In this example, the template only displays the items with an index value less than 3 (indexes 0, 1, and 2), and stops looping when the index is greater than or equal to 3. In other words, it displays the first 3 items and stops.

{{#each blogFeed.item}}
  {{#lt @index 3}}
    {{#if this.title}}
      {{{snippet "blogPost" this.title this.description this.link}}}
    {{/if}}
  {{/lt}}
{{/each}}

# Passing sub-properties of namespaced fields to snippets

RSS and XML feeds often include namespaced fields like media:content or media:thumbnail that contain objects with sub-properties such as url, width, and height.

For example, an RSS blog feed might include a featured image for each post in a media:content element.

An example media:content element might look like this:

<media:content url="https://example.com/image.jpg" width="600" height="400" />

You might want to use the url sub-property to grab the image's URL for display in the template.

You might expect to access the image URL with a path like blogFeed.item.[0].["media:content"].url, but this doesn't resolve. Sub-properties of namespaced fields can't be accessed with standard Handlebars dot notation, lookup, or #with.

Instead, you can use #each to iterate over the item's fields, check using the @key helper to find the namespaced field, then use #assign to capture the sub-property into a variable you can pass to the snippet.

For a full explanation of why direct access fails and how this alternative technique works, see Referencing sub-properties of namespaced fields.

First, add a variable to your snippet that accepts the captured value. Update the snippet to add a new variable name, and update the snippet content to include the new variable and some HTML to display the image.

Below is an example of the updated blogPost snippet content from the example above to include a new variable and some HTML to display the image. The updated snippet content includes an imageUrl variable placed in an <img> tag to display the image:

<div class="blog-post" style="padding: 16px; border: 1px solid #ddd; margin-bottom: 12px;">
  <img src="{{imageUrl}}" alt="{{title}}" style="width: 100%; max-width: 600px; height: auto; display: block; margin-bottom: 12px;" />
  <h3 style="margin: 0 0 4px;">{{title}}</h3>
  <p style="color: #666; margin: 0 0 8px;">{{description}}</p>
  <a href="{{link}}" style="color: #612C6A; text-decoration: none;">Read more</a>
</div>

Notice that the snippet content itself isn't aware of the media:content element that contains the image URL coming from the data feed. Instead, it expects the image URL to be passed in the imageUrl variable—either via a named variable or as a positional parameter.

Next, capture the image URL from the data feed and pass it as a snippet variable. There are two ways to do this when working with an array: indexed expressions, or a nested #each loop. Each technique has an example below showing how to do this.

# Example of a captured sub-property using indexed expressions

You can use an indexed expression to capture the image URL from the data feed, by using an #each expression just before the snippet expression to loop over the properties of the first item in the array, then use #if to check if the @key is media:content and #assign to capture the url sub-property into a variable.

Finally, pass the variable to the snippet alongside the other fields.

{{#each blogFeed.item.[0]}}
  {{#if (eq @key "media:content")}}
    {{#assign "img0"}}{{this.url}}{{/assign}}
  {{/if}}
{{/each}}
{{{snippet "blogPost" img0 blogFeed.item.[0].title blogFeed.item.[0].description blogFeed.item.[0].link}}}

# Example of a captured sub-property using a nested #each loop

If you are looping over the array with #each instead of using indexed expressions, you can use the same technique — but it requires a nested loop:

• The outer #each iterates over the items in the array, and repeats the inner loop for each item.
• The inner #each iterates over the fields of the current item, and for each field uses #if to check if the @key is media:content and #assign to capture the url sub-property into a variable.

Once captured, the variable is passed to the snippet alongside the other fields.

{{#each blogFeed.item}}
  {{#lt @index 3}}
    {{#if this.title}}
      {{#each this}}
        {{#if (eq @key "media:content")}}
          {{#assign "imageUrl"}}{{this.url}}{{/assign}}
        {{/if}}
      {{/each}}
      {{{snippet "blogPost" imageUrl this.title this.description this.link}}}
    {{/if}}
  {{/lt}}
{{/each}}

Here's how each layer works:

# Using data feeds in snippets without the merge contexts setting

In most cases, enabling Merge the Data Feed and User Contexts with an alias is the recommended approach. However, if you need strict separation between data feed and user profile fields—for example, due to legacy template configurations or organizational policy—you can disable Merge the Data Feed and User Contexts and use one of the approaches described in this section.

When the merge contexts setting is disabled, Iterable renders the template in two passes:

This two-pass rendering requires special techniques to pass data feed values to snippets.

Notably, when you call a snippet and need it to accept data feed fields, you can do this in two ways:

• Use the #assign helper to capture the data feed values into variables and pass the variables to the snippet.
• Use square bracket notation ([[...]]) to reference the snippet that accepts the data feed fields.

# Using the #assign helper to pass data feed fields to a snippet

The #assign helper captures data feed values from the first rendering pass and stores them in variables for the second pass. This lets you reuse the same curly brace snippet expression shown in the example above.

A limitation of this approach is that you must use indexed expressions, #each is not supported. If you need #each loops without the merge contexts setting, use the square bracket approach instead.

This example shows how to capture the data feed values for three fields: title, description, and link. Then it passes the captured values as positional parameters to the blogPost snippet.

{{#assign "title"}}[[item.[0].title]]{{/assign}}
{{#assign "description"}}[[item.[0].description]]{{/assign}}
{{#assign "link"}}[[item.[0].link]]{{/assign}}
{{{snippet "blogPost" title description link}}}

If Use Data Feed Alias is enabled, include the alias in the square bracket paths (for example, [[blogFeed.item.[0].title]]).

# Using square bracket snippet notation to pass data feed fields to a snippet

If you need #each loops with the merge contexts setting disabled, you can call the snippet during the data feed rendering pass using square bracket notation. This approach requires a separate snippet that uses [[...]] syntax internally.

Create a snippet (for example, blogPost_datafeed) that uses square bracket notation for its variables:

<div class="blog-post" style="padding: 16px; border: 1px solid #ddd; margin-bottom: 12px;">
  <h3 style="margin: 0 0 4px;">[[title]]</h3>
  <p style="color: #666; margin: 0 0 8px;">[[description]]</p>
  <a href="[[link]]" style="color: #1a73e8; text-decoration: none;">Read more</a>
</div>

[[#each blogFeed.item]]
  [[{snippet "blogPost_datafeed" this.title this.description this.link}]]
[[/each]]

# Example final email template with RSS blog feed

Below is the final email template that uses the blogPost snippet to display the first 3 items from the RSS blog feed.

Example snippet content:

<div class="blog-post" style="padding: 16px; border: 1px solid #ddd; margin-bottom: 12px; border-radius: 6px;">
  <img src="{{imageUrl}}" alt="{{title}}" style="width: 100%; max-width: 500px; height: auto; display: block; margin-bottom: 12px; border-radius: 4px;" />
  <h3 style="font-family: Georgia, 'Times New Roman', serif; font-size: 20px; margin: 0 0 6px; color: #1a1a1a;">{{title}}</h3>
  <p style="font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif; font-size: 14px; color: #666; margin: 0 0 12px; line-height: 1.5;">{{description}}</p>
  <a href="{{link}}" style="font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif; font-size: 14px; color: #612C6A; text-decoration: none; font-weight: bold;">Read more &rarr;</a>
</div>

Example snippet expression that captures the image URL and displays the first 3 items:

{{#each blogFeed.item}}
  {{#lt @index 3}}
    {{#if this.title}}
      {{#each this}}
        {{#if (eq @key "media:content")}}
          {{#assign "imageUrl"}}{{this.url}}{{/assign}}
        {{/if}}
      {{/each}}
      {{{snippet "blogPost" imageUrl this.title this.description this.link}}}
    {{/if}}
  {{/lt}}
{{/each}}

Here is what the template looks like with the snippet expression in place:

And here is what it looks like when the final email campaign is sent:

# Troubleshooting

For general data feed troubleshooting—such as field name collisions, alias issues, bracket types, and special characters—see Using Data Feeds in Templates.

The items below are specific to using data feeds with snippets.

# Snippet variables not resolving

Solution: Use #assign to capture the value first, then pass the variable name to the snippet:

{{#assign "myVar"}}[[field]]{{/assign}}
{{{snippet "mySnippet" myVar}}}

# Special characters in data feed field references

Solution: Wrap the field name in square brackets and quotes. For full details, see Referencing fields with special characters.

{{{snippet "blogPost" blogFeed.item.[0].title blogFeed.item.[0].["content:encoded"]}}}

# HTML displays as text

Problem: Using [[[ snippet "mySnippet" ...]]] or [[snippet "mySnippet" ...]] (square brackets) causes the snippet's HTML to display as escaped text instead of rendering.

Solution: Add a curly brace before snippet "mySnippet" for unescaped output:

[[{snippet "mySnippet" ...}]]

# 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

• Product Bite: Data Feeds
• Product Bite: Creating and Applying Snippets

Support docs

• Data Feeds Overview
• Creating a Data Feed Web Service
• Using Data Feeds in Templates
• Snippets Overview
• Customizing Snippets with Variables
• Handlebars Overview