Introduction

Merge field helpers extend the capabilities of standard merge fields, enabling more dynamic and complex logic using advanced helper syntax. With helpers, you can apply conditional logic to your templates and iterate over and display lists within channel based nodes.

Merge field helpers are currently only supported in channel based nodes for templating.

This guide will walk you through using merge field helpers, outlining supported syntax, use cases, examples, and important considerations.

What are merge field helpers?

Merge field helpers are additional Handlebars-based tools that let you perform more advanced data manipulations within merge fields. These helpers allow for conditional rendering, looping through data, and using context-aware variables like @index or @first.

Example:

Instead of sending a generic message, you can loop through a list of names and format them with commas, omitting the comma after the last name:

{{#each people}}
  {{this.name}}{{#unless @last}}, {{/unless}}
{{/each}}

If the list is ["Alice", "Bob", "Charlie"], the output would be:

Alice, Bob, Charlie

Supported helpers:

Supported data variables (Within #each loops):

Partial support:

• Nested helpers:

  You can nest helpers (e.g., {{#each}} inside {{#if}}), but complex nesting may reduce readability and increase the risk of errors.

  {{#each users}}
    {{#if this.active}}
      {{this.name}}
    {{/if}}
  {{/each}}
  

Key considerations

Validation & errors:

• Field-specific support:

  Merge field helpers are only supported in designated fields in channel nodes (like email or message bodies). Other fields will reject helper syntax and will display an error, ‘Helpers are not supported in this input field.’

• Limited validation:

  • Unvalidated paths in helpers: Using this.some.path is not validated once helpers are used.
  • No deep syntax validation: Complex helper structures (e.g., nested loops with aliases) aren’t fully validated.
  • Closing tags: Ensure helpers like {{/if}} are properly closed. Pendula’s validation system won’t enforce it.

Iterable errors:

• The #each helper requires the referenced merge field to be an array or object. Using a non-iterable value triggers an “iterable” type error.

Best practices for using merge field helpers

1. Keep templates simple:

   Simpler templates are easier to maintain and debug. You can use the Criteria filter, and Criteria split, to split cohorts using the flow builder; resulting in simpler email templates. Learn more here

2. Test complex logic:

   Run tests on flows using nested helpers to confirm expected behaviour.

3. Avoid over-nesting:

   Though possible, deeply nested helpers can become hard to manage. Break complex logic into smaller steps where feasible.

4. Use default fallbacks:

   Prevent blank values by using {{#if}} and {{else}} blocks:

   {{#if firstName}}
     Hi {{firstName}}
   {{else}}
     Hi there!
   {{/if}}
   

Troubleshooting common issues