Articles in this section

Handlebars overview

Handlebars is a templating language that lets you insert dynamic values into text by embedding expressions in double curly braces. In integrator.io, you use Handlebars to map fields, transform data, and perform calculations during flow execution.

Before using Handlebars, familiarize yourself with Work with JSON data in integrator.io.

Expressions

A Handlebars expression is a named function wrapped in double curly braces:

{{expression}}

When a flow runs, integrator.io evaluates each expression against an input JSON object (called the context) and replaces it with the corresponding value.

You can use Handlebars expressions to:

  • Map fields between export and import steps.
  • Perform arithmetic calculations on exported values.
  • Encode and decode data dynamically during integration.

For typographical conventions and syntax rules, see Handlebars syntax.

Contexts

Contexts in integrator.io are JSON objects. JSON follows these conventions:

  • Data is stored as name/value pairs:
    "fieldName": "value"
  • Curly braces hold objects, with name/value pairs separated by commas:
    { "items": "products", "people": "persons", "price": "8000" }
  • Square brackets hold arrays:
    { "inventory": { "items1": "[1, 2, 3]", "items2": "[4, 5, 6]", "items3": "[7, 8, 9]" } }

Templates

A Handlebars template is a string containing one or more expressions. Every template runs against a context — a JSON object that supplies the values for each expression.

Template Context Output
{{first}} {{last}} {"first": "Carol", "last": "Ebsen"} Carol Ebsen

Use dot notation to access nested properties:

Template Context Output
{{person.first}}{{person.last}} {"person": {"first": "Carol", "last": "Ebsen"}} Carol Ebsen

The placement of expressions directly affects the output structure. For example:

Template Context Output
Our office is located at:{{address.streetAddress}},{{address.city}}, {{address.state}} {{address.zip}} {"address": {"streetAddress": "123 Anywhere Street", "city": "Anytown", "state": "US", "zip": "55555"}} Our office is located at: 123 Anywhere Street, Anytown, US 55555

Inline helpers and nested expressions

You can nest helpers inside expressions using parentheses:

Template Context Output
{{uppercase (replace customer.name "a" "-xyz-")}} {"customer": {"name": "aeiou"}} -XYZ-EIOU

Block helpers

Block helpers wrap sections of a template and support conditional logic. They always begin with {{#helperName}} and close with {{/helperName}}.

You don't need to enter the # prefix manually — start typing the helper name between double curly braces and integrator.io will populate the default syntax for you.

#contains syntax:

{{#contains collection field}} expr {{else}} expr {{/contains}}

#compare syntax:

{{#compare field operator field}} expr {{else}} expr {{/compare}}

Example:

Template Context Output
{{#compare data.customer "==" "Harry"}}Truman {{else}}"Not a match"{{/compare}}{{#compare data.customer1 "==" "Harry"}}Truman {{else}}"Not a match"{{/compare}} {"data": {"customer": "Harry", "customer1": "Thomas"}} Truman "Not a match"

Open the handlebars editor

You can find the handlebars editor when you create an export.

  1. Create a new export or open an existing export (see Create an export).
  2. Expand the Advanced section.
  3. Next to Data URI template or Override trace key template, select Open handlebars editor { }.