Articles in this section

Handlebars overview

Handlebars is a simple templating language. Handlebars templates look like regular text with embedded handlebars expressions. You may need to learn more about working with JSON in integrator.io to effectively use handlebars.

Expressions

Expressions are functions that are named according to the function they perform. They can accept and pass arguments to other functions or expressions, modify the output, and perform a host of other functions. Handlebars helpers will modify the JavaScript Object Notation (JSON) source record or file.

A simple handlebars expression uses the following syntax:

{{expression}}

Note

For more information on handlebars expression syntax, see Handlebars syntax.

When the template is executed, these expressions are replaced with values from an input JSON object (context).

Handlebars expressions can be used to:

  • Map Export and Import application fields.

  • Perform dynamic arithmetic calculations on exported values.

  • Dynamically encode and decode data during integration.

Expressions are used to include variables or execute helpers in a "handlebars template" which may be raw handlebars {{expressions}} or HTML with the handlebars expressions inserted between opening and closing double curly braces. See Handlebars syntax for typographical conventions.

Template

Context

Output

Handlebars evaluates the template with variables and compiles it into a function.

The function passes a JavaScript Object Notation (JSON) object as an argument. The JSON object is called a "context" and contains the template variables.

Once executed, the function replaces the variables in the template and returns an output file with the values.

{{first}} {{last}}
{
    "first": "Carol",
    "last": "Ebsen"
}
Carol 
Ebsen

You can use dot-notation to gain access to nested properties, objects, or arrays.

{{person.first}} {{person.last}}
{
    "person": {
        "first": "Carol",
        "last": "Ebsen"
    }
}
Carol Ebsen

Templates

Handlebars templates may have handlebars {{expressions}} standing alone, nested, or in an inline series. Every template has a context JSON object. The context JSON object has information that is passed to the template.

HandlebarsTemplatesDiagram.png

Contexts

The files that work within the integrator.io extract-transform environment are in JSON format, which is derived from JavaScript Object Notation (JSON) syntax. JSON uses the following syntax conventions:

  • Data is in name/value pairs:

    "fieldName": "value"
  • Curly braces hold objects and each name/value pair is separated by commas, (except the last one).

    {
        "items": "products", 
        "people": "persons", 
        "price": "8000" 
     }
  • Square brackets hold arrays.

    {
       "inventory": {
           "items1": "[1, 2, 3]",
           "items2": "[4, 5, 6]",
           "items3": "[7, 8, 9]"
       }
    }

Open the Build data URI template editor

Use the following steps to get to the editor:

  1. Open an integration or navigate to Tools > Data Loader.

  2. Click Data Loader in the SOURCE section.

  3. Expand the Advanced section and and click the pencil icon next to Data URI Template. This opens the editor and populates the Available Resources field with the file you uploaded previously.

    BuildDataURITemplate.png

    The output renders as shown below in the Evaluated Result window. Note the placement of the expressions within the template – these have an impact on the output structure as shown below.

    Template

    Our office is located at:
    {{address.streetAddress}},
    {{address.city}}, {{address.state}} {{address.zip}}

    Context

    {
        "address": {
            "streetAddress": "123 Anywhere Street",
            "city": "Anytown",
            "state":"US",
            "zip": "55555"
        }
    }

    Output

    Our office is located at:
    123 Anywhere Street,
    Anytown, US 55555

Inline helpers and nested expressions

Inline helpers can be nested inside expressions using parenthetical expressions or curly braces.

Template

Context

Output

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

Expressions may be nested within block helpers where an inner context may be constructed. The hashtag # symbol is a part of the syntax which begins these methods. Note that the block helpers (whether inline or not) always begin with a hashtag {{#helper}} and must be terminated using a slash {{/blockHelper}}, the same way you would close an HTML element.

The sample syntax here includes a helper {{#helper parameter field}} and/or a {{#blockHelper parameter field}} inner expressions/output text and a closing statement {{/blockHelper}}.

#contains:

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

#compare:

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

You are not required to enter the hashtag as the system will recognize your entry when building the expression. Just begin by entering two curly braces and the name of helper and the default variable will populate the template. From here, simply modify the expressions to suit your desired output.

Template

{{#compare data.customer "==" "Harry"}}Truman{{else}}"Not a match"{{/compare}}
{{#compare data.customer1 "==" "Harry"}}Truman{{else}}"Not a match"{{/compare}}

Context

{
    "connection": {
        "name": "conn",
        "http": {}
    },
    "export": {},
    "data": {
        "customer": "Harry",
        "customer1": "Thomas",
        "other": " " 
    }
}

Output

Truman
"Not a match"

Additional resources:

Was this article helpful?
2 out of 2 found this helpful

Comments

0 comments

Please sign in to leave a comment.