1. Pendula for Enterprise
  2. Pendula user guides
  3. Engagement Hub
  4. Introduction

Get started
Working with merge field helpers

Alex Pribula
Alex Pribula
  • Updated

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:

Helper Use Case Example
{{#if}} Conditional rendering if a value exists {{#if trigger_1.firstName}}Hi {{trigger_1.firstName}}{{/if}} → Hi Alice
{{#unless}} Render if the condition is false or empty

{{#unless active}}Account inactive{{/unless}} → Account inactive

Example outcome: Unless the account has {{active}}, show message.
{{#each}} Loop over arrays or objects

{{#each names}}{{this}}{{#unless @last}}, {{/unless}}{{/each}} → Alice, Bob, Charlie

Example outcome: A comma is added for each item except for the last one.
{{this}} Refers to the current object/item in context

{{#each names}}Name:{{this}}{{/each}} → Name: Alice Name: Bob Name: Charlie

Example outcome: For each item, "Name" is added.
{{else}} Alternative block for conditionals

{{#if subscribed}}Thank you for being a subscriber!{{else}}Stay informed and subscribe now!{{/if}} → Stay informed and subscribe now!

Example outcome: If a customer is not subscribed, show the message following {{else}}.

Supported data variables (Within #each loops):

Variable Description Example
@index The current index in the loop {{#each names}}{{@index}}: {{this}}\\n{{/each}} → 0: Alice 1: Bob 2: Charlie
@key The key when looping over objects {{#each user}}{{@key}}: {{this}}\\n{{/each}} (with { name: "Alice" }) → name: Alice
@first true if the current item is the first {{#each names}}{{#if @first}}First: {{/if}}{{this}}{{/each}} → First: Alice Bob Charlie
@last true if the current item is the last {{#each names}}{{this}}{{#unless @last}}, {{/unless}}{{/each}} → Alice, Bob, Charlie

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

Error Cause Solution
Wavy red underline on merge field Invalid or unrecognised merge field in helper block Check for typos or unsupported paths
“Iterable” type error Using #each on a non-array or non-object Verify the merge field references an array/object
Blank output in message Merge field has no data or invalid path Use {{else}} or #unless to provide fallbacks