Handlebars syntax controls how expressions are evaluated and how output is encoded. This article covers the typographical conventions you need to write and troubleshoot Handlebars expressions in integrator.io.
For background on expressions and helpers, see Handlebars overview and Handlebars helper reference. For JSON basics, see Work with JSON data in integrator.io.
Typographical conventions
| Syntax | Description |
|---|---|
{{expression}} |
Standard Handlebars expression. URL-encodes characters that can be URL-encoded (such as <, >, and spaces). The braces themselves do not appear in output. Use this for HTTP URIs and similar contexts where automatic encoding is needed. For Postgres DB queries, this escapes characters per PostgreSQL string syntax. |
{{{expression}}} |
Triple-brace expression. Outputs the value without any encoding. Use this when the field value has already been URL-encoded and re-encoding would corrupt it. |
{{{{expression}}}} |
Raw block. Outputs the template content literally, without parsing any Handlebars expressions inside. |
{{name}} |
Accesses a top-level field named name. |
{{first.name}} |
Dot notation for accessing a nested field. |
\{{escaped}} |
Backslash escape. Prints the literal text {{escaped}} in output without evaluating the expression. |
[field name] |
Square brackets for field names or values that contain spaces, for example [customer name] or [Carrier Name]. |
Templates, contexts, and outputs
| Term | Description |
|---|---|
| Template | The Handlebars expressions and helpers that define how data is transformed. |
| Context | The JSON object passed to the template. In integrator.io, this is either uploaded sample data or live data from a flow run. |
| Output | The result produced after the template is evaluated against the context. |
Dot notation and quoted strings
Handlebars expressions use dot notation to access nested object properties. The examples below show three common patterns.
Accessing a nested field:
| Template | Context | Output |
|---|---|---|
{{library.title}} |
{"library": {"album": "The Sound", "title": "Danube Incident", "artist": "Lalo Schifrin"}} |
Danube Incident |
Using an expression inside a quoted JSON string:
| Template | Context | Output |
|---|---|---|
{"shipName": "{{record.name}}"} |
{"record": {"name": "FalconSat", "flight_number": 1}} |
shipName: FalconSat |
Using a helper inside a quoted string:
When a helper appears inside a double-quoted string (" "), change any double quotes inside the helper to single quotes (' '). For example:
{"rocketID":"{{getValue 'record.rocket' "defaultValue"}}"}
| Template | Context | Output |
|---|---|---|
{"rocketID":"{{getValue 'record.rocket' "defaultValue"}}"} |
{"record": {"rocket": "5e9d0d95eda69955f709d1eb"}} |
rocketID: 5e9d0d95eda69955f709d1eb |