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
- Step 1: Create a data feed and add it to your project
- Step 2: Create a snippet that accepts data feed fields
- Step 3: Configure the template to use the data feed
- Step 4: Create a snippet expression and add it to the template
- Snippet expressions for data feed fields
- Example final email template with RSS blog feed
- Troubleshooting
- Want to learn more?
# 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 →</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:
-
Merge the Data Feed and User Contexts — Combines data feed fields and user profile data into a single rendering context. This lets you reference both data sources with standard curly brace Handlebars syntax (
{{...}}), which simplifies the process of passing data feed fields to snippets.When the merge contexts setting is disabled, Iterable renders data feed fields and user profile fields in separate passes, requiring square bracket notation (
[[...]]) for data feed fields and different techniques to pass them to snippets. To learn more about alternative techniques, see Using data feeds in snippets without the merge contexts setting below.
-
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:
-
Merge contexts setting:
- Merge contexts setting enabled: Use the standard curly brace Handlebars syntax
(
{{...}}) to reference the data feed fields. - Merge contexts setting disabled: Use square bracket notation (
[[...]]) to reference the data feed fields. This also requires special techniques to pass data feed values to snippets. To learn more about how this works with snippets specifically, see Using data feeds in snippets without the merge contexts setting, below.
- Merge contexts setting enabled: Use the standard curly brace Handlebars syntax
(
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
#eachhelper to display all items, or a limited number of items. To learn more, see Approach 2: The#eachhelper 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
urlsub-property in amedia:contentelement. To access the image URL, you need to access themedia:contentproperty and then theurlsub-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
itemarray:title,description,link - Indexed expressions:
blogFeed.item.[0],blogFeed.item.[1],blogFeed.item.[2]
# 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:
# 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.
# 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.
# 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
#eachiterates over the items in the array, and repeats the inner loop for each item. - The inner
#eachiterates over the fields of the current item, and for each field uses#ifto check if the@keyismedia:contentand#assignto capture theurlsub-property into a variable.
Once captured, the variable is passed to the snippet alongside the other fields.
Here's how each layer works:
-
{{#each blogFeed.item}}— Loops over the array of feed items. Inside this outer loop,thisrefers to the current item object and@indexis its position in the array. -
{{#lt @index 3}}— Limits output to the first three items (indexes 0, 1, and 2). -
{{#each this}}— Loops over the fields of the current item. Inside this inner loop,@keyis the field name (such astitle,link, ormedia:content) andthisis the field's value. -
{{#if (eq @key "media:content")}}— Finds the namespaced field by checking its name. -
{{#assign "imageUrl"}}{{this.url}}{{/assign}}— Captures theurlsub-property into a variable. Inside the inner loop,thisis themedia:contentobject, sothis.urlresolves correctly. - After the inner
{{/each}}closes, context returns to the outer loop, sothis.title,this.description, andthis.linkonce again refer to the current item's fields.
NOTE
This technique works for any namespaced field with sub-properties, not just
media:content. Common examples in RSS feeds include media:thumbnail, media:group,
and other namespace-prefixed elements that contain attributes.
# 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:
-
First pass — Square bracket notation (
[[...]]) resolves data feed fields. -
Second pass — Curly brace notation (
{{...}}) resolves user profile fields and snippet expressions.
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
#assignhelper 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.
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.
IMPORTANT
A snippet using [[...]] syntax cannot reference user profile fields
and cannot be shared with templates that use the merge contexts setting. Only use
this approach if you specifically need #each loops without enabling the merge
contexts setting.
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>
Call the snippet using [[{snippet ...}]] notation. The curly brace
inside the square brackets indicates unescaped HTML output (similar to
triple curly braces {{{...}}} in standard Handlebars):
CAUTION
Do not use triple square brackets ([[[snippet ...]]]). This syntax
does not exist and produces an error like:
could not find helper: '[snippet'. Use [[{snippet ...}]] instead.
# 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 →</a> </div>
Example snippet expression that captures the image URL and displays the first 3 items:
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.
For general snippet brace behavior ({{ ... }} vs {{{ ... }}}), see
Adding a Snippet to a Template
The items below are specific to using data feeds with snippets.
# Snippet variables not resolving
Problem: Passing [[field]] directly to a snippet call does not
resolve the data feed value.
Solution: Use #assign to capture the value first, then pass the
variable name to the snippet:
# Special characters in data feed field references
Problem: Passing a data feed field with special characters (such
as content:encoded) to a snippet causes an error.
Solution: Wrap the field name in square brackets and quotes. For full details, see Referencing fields with special characters.
# 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:
The curly brace inside the square brackets indicates unescaped HTML
output, similar to using triple curly braces ({{{...}}}) in standard
Handlebars. The outer square brackets enable data feed rendering without the merge
contexts setting.
# 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