Articles in this section

Customizing Snippets with Variables

Variables are dynamic fields added to a snippet's definition. They allow individual templates to customize the snippet's output as needed, while still taking advantage of the content reuse that snippets provide.

For example, imagine a snippet whose content includes a Sign Up Now button. You might use this button in any campaign that's attempting to drive sign-ups. To take this further, you can also change the button's label, and reuse it in other scenarios. For example, maybe you need the same button, but with a Show Me! label. Snippet variables make this possible.

You can use variables to dynamically affect things like text, URLs, CSS style attributes, conditional logic, and more.

IMPORTANT

When creating or editing a snippet, it's important to remove unwanted whitespace characters to avoid rendering issues. To learn more, see Removing Whitespace.

# In this article

# How snippet variables work

Using snippet variables involves three parts that work together:

  • Define variables in the snippet. When you create or edit a snippet, use the Add variable button to add named variables. Each variable becomes a placeholder that the snippet's content can reference.
    • Example: A snippet defines a variable named color that the snippet's content can reference.
  • Use variables in the snippet's content. In the snippet's content, reference each variable by name using a Handlebars expression. The snippet evaluates each variable's value at send time to determine what to display.
    • Example: Reference the color variable in snippet content using {{color}} where you want to output its value.
  • Pass values in the snippet expression. When you include the snippet in a template, pass a value for each variable in the snippet expression. You can pass values positionally—in the order variables are defined—or by name using named parameters. Then, when the snippet is rendered, those values are applied.
    • Example: Pass a value for the color variable using the snippet expression {{{ snippet "mySnippet" "#FF0000" }}}. When the snippet is rendered, the color variable resolves to #FF0000.

# Defining variables for a snippet

To add variables to a snippet, go to Content > Snippets, open or create a snippet, and use the Add variable button to add variables by name.

You can add as many variables as a snippet needs. Keep in mind that every template using the snippet must provide a value for each variable—too many variables can make a snippet difficult to use.

# Using variables in snippet content

Every variable you define should be used somewhere in the snippet's content— otherwise, there's no reason for it to exist.

To use a variable in the snippet's content, reference it by name using a Handlebars expression. For example, if you defined a variable named color, use {{color}} in the snippet's content to output its value.

You can add conditional logic in the snippet's content to control what it displays based on the values of the variables. This conditional logic lives in the snippet's content, not in the snippet expression. The expression passes values for variables; the snippet's content evaluates those values to determine what to render. This means that a reader looking at a template sees only {{{ snippet "login_switcher" "sign_up" "#FF0000" }}}, while the branching logic ({{#if (eq login_type "sign_up")}}...) stays inside the snippet definition.

TIP

For more information about creating dynamic content with Handlebars, see Handlebars Overview.

# Passing values to snippet variables

When you include a snippet in a template, you need to provide values for any variables it defines. Keep the following in mind regardless of how you pass values:

  • All variables are required. Provide values for all of a snippet's variables, not just some of them.
  • Data types. Provide values compatible with what the snippet expects. The supported value types are described in the sections below.

You can pass values in two ways:

  • Positional parameters (default) — Pass variables in the same order the variables are defined in the snippet.
  • Named parameters — Explicitly specify which field each variable receives, so order doesn't matter.

# Syntax for passing different data types to snippet variables

The following value types can be passed to snippet variables. The syntax for each type is the same whether you use positional or named parameters.

# Pass in a string

To pass in a string, use the string value surrounded by straight double quotes, for example, "Fall Sale":

{{{ snippet "mySnippet" "Fall Sale" }}}

# Pass in a hex color

Passing a hex color to a snippet is the same as passing a string:

{{{ snippet "mySnippet" "#FF0000" }}}

# Pass in a number

Numbers can be passed in as either integers or floating-point numbers, without additional quotes:

  • For integers, such as 3:

    {{{ snippet "mySnippet" 3 }}}

  • For floating-point numbers, such as 3.14:

    {{{ snippet "mySnippet" 3.14 }}}

# Pass in a boolean

To pass in a boolean, use true or false without additional quotes:

{{{ snippet "mySnippet" true }}}

# Pass in a user profile field

To pass in a user profile field, use the field name:

{{{ snippet "mySnippet" favoriteColor }}}

# Pass in an assigned value (using the #assign helper)

You can use the #assign helper to capture the value of any Handlebars expression and pass it to a snippet as a variable.

{{#assign "savingsThisYear"}}{{math totalSpend '-' totalAfterDiscounts}}{{/assign}}
{{{ snippet "mySnippet" savingsThisYear }}}

# Pass in a data feed field

Passing a data feed field to a snippet requires the template to use a data feed. To learn how, see Using Data Feeds in Snippets.

To pass in a data feed field, use the data feed field name:

{{{ snippet "mySnippet" dataFeedField }}}

# Positional parameters (default)

With positional parameters, variables are assigned based on their position in the snippet expression. The first value maps to the first variable defined in the snippet, the second value to the second variable, and so on. To pass values in any order instead, use named parameters.

# Named parameters (alternative)

If you prefer not to rely on variable order, you can use named parameters instead. Named parameters explicitly specify which variable receives each value, so order doesn't matter.

Named parameters use key=value syntax—the variable name, an equals sign (no spaces), and the value. Whether the value needs double quotes depends on its type:

  • String literal — Wrap the value in double quotes. Without quotes, a bare word is treated as a variable reference, not a string. For example, login_type=sign_up looks up a field or variable named sign_up rather than passing the text sign_up.

    {{{ snippet "login_switcher" login_type="sign_up" color="#FF0000" }}}

  • Boolean or number — Pass the value without quotes.

    {{{ snippet "mySnippet" required=true count=3 }}}

  • User profile field or Handlebars variable — Pass the identifier without quotes. Iterable resolves it as a reference at render time.

    {{{ snippet "mySnippet" color=favoriteColor }}}

With named parameters, both of these produce the same result regardless of the order:

{{{ snippet "login_switcher" color="#FF0000" login_type="sign_up" }}}

IMPORTANT

Named parameters use =, not :. For example, login_type="sign_up" is correct; login_type: "sign_up" is not valid syntax and causes an error.

# Example: login switcher snippet

This example walks through the full workflow using a snippet named login_switcher. The snippet displays one of three links based on a login_type variable, and uses a color variable to set the link color:

  • Sign up now!
  • Take me to my account!
  • Check out the website!

Here's what the finished snippet looks like in Iterable:

Snippet with two variables

# Step 1: Define variables

Go to Content > Snippets, click New Snippet, and use the Add variable button to add two variables: login_type and color.

# Step 2: Use variables in the snippet's content

Here's the content for the login_switcher snippet:

{{#if (eq login_type "sign_up")}}
  <a style="color: {{color}}" href="https://www.example.com/signup">Sign up now!</a> 
{{else}}
  {{#if (eq login_type "sign_in")}}
    <a style="color: {{color}}" href="https://www.example.com/login">Take me to my account!</a>
  {{else}}
    <a style="color: {{color}}" href="https://www.example.com">Check out our website!</a>
  {{/if}} 
{{/if}}

This content examines the login_type variable to determine which link to display:

  • If login_type is "sign_up", the snippet displays the Sign up now! link.
  • If login_type is "sign_in", the snippet displays the Take me to my account! link.
  • In all other cases, the snippet displays a generic Check out our website! link.

Additionally, this snippet uses its color variable to set the color of its link. The {{color}} merge tag outputs the value stored in the color variable as the value of the CSS style attribute.

# Step 3: Pass values in the template

Let's pass different values to the variables in our example snippet, to see the different links and colors that it will render:

{{{ snippet "login_switcher" "sign_up" "#FF0000" }}}
{{{ snippet "login_switcher" "sign_in" "orange" }}}
{{{ snippet "login_switcher" "other" "purple" }}}

In these examples, "sign_up" is assigned to login_type (first variable) and "#FF0000" is assigned to color (second variable), because that's the order the variables are defined in the snippet.

A template that's testing a snippet with variables

Using Preview with Data, we can see how these different snippet expressions all render:

Preview with data showing the results of a test template

Each snippet expression results in a different link/color combination, based on values included in the snippet expression.

# Want to learn more?

For more information about some of the topics in this article, check out this Iterable Academy course. Iterable Academy is open to everyone — you don't need to be an Iterable customer!

Iterable Academy

Support docs

Related articles