Skip to main content

Handlebars helper reference

Tom Santiago
  • Updated
Follow

Handlebars helpers can be used to implement functionality that is not part of the handlebars language itself. The following list of helpers is supported by integrator.io:

Custom helpers Block helpers @Data variables

For a downloadable guide, see Handlebars helper reference (PDF format).

Custom helpers

add

Adds all of the specified variables. This helper adds JSON variables, “hard-coded” values, or a combination thereof. Absolute values do not require context JSON variables. The example below only shows integers, but it also works with floats and decimals.

{{add field field}}
Template Context Output 
{{add item1 item2 item3}}
 
{
  "item1": "33",
  "item2": "11",
  "item3": "100"
}
 
144
 
{{add "2" "5" "2"}}
 
9
 
{{add item1 "2" "3" item3}}
 
 138

avg

Computes the average of the specified values. This helper will average variables, “hard-coded” values, or a combination thereof. Absolute values do not require Context JSON variables. 

{{avg field}}
Template Context Output 
{{avg item1 item2 item3}}
 
{
  "item1": "33",
  "item2": "11",
  "item3": "100"
}
 
48
 
{{avg "2" "5" "2"}}
 
3
 
{{avg item1 "2" "3" item3}}
 
34.5

base64Decode

Decodes any Base64 string to the specified encoding format.

base64String

The first argument (required) is a Base64 string.

decodeFormat

The second argument (optional) is the encoding format to which the string will be decoded. If the second argument is not provided, the string decodes in UTF8 format. This argument supports the following formats:

  • "ascii"
  • "base64"
  • "hex"
  • "ucs2" or "ucs-2"
  • "utf16le" or "utf-16le"
  • "utf8" or "utf-8" – default
  • "binary"
  • "latin1"
{{base64Decode base64String decodeFormat}}
Template Context Output 
{{base64Decode str}}
 
 str = 'SGVsbG8gV29ybGQhIQ=='
 
Hello World!!
 
{{base64Decode str "utf8"}}
 
{{base64Decode null}}
 
' '
 
{{base64Decode undefined}}
 
{{base64Decode str "ascii"}}
 
Hello World!!
 
{{base64Decode str "binary"}}
 
{{base64Decode str "hex"}}
 
48656c6c6f20576f726c642121
 
{{base64Decode str str "utf8"}}
 
Error: handlebars Helper {{base64Decode}} expects maximum 2 arguments only.
 
{{base64Decode str 
"wrongEncodingFormat"}}
 
Error: wrongEncodingFormat encoding format is not supported.

base64Encode

Concatenates and encodes all the passed arguments to the Base64 encoding format.

Note: Use triple-curly braces for this expression.

{{{base64Encode field}}}
Template Context Output 
{{{base64Encode userName}}}
 
{
  "connection": {},
  "userName": "username",
  "pwd": "password"
}
 
dXNlcm5hbWU=
 
{{{base64Encode userName pwd}}}
 
dXNlcm5hbWVwYXNzd29yZA==
 
{{{base64Encode userName ":" pwd}}}
 
dXNlcm5hbWU6cGFzc3dvcmQ=

capitalize

Capitalizes the first letter of the first word in a string.

{{capitalize field}}
Template Context Output 
The {{capitalize type}} is a 
member of the {{animal}}
species.
 
{
  "animal":"canine",
  "type": "dog"
}
 
The Dog is a 
member of the canine
species.
 
{{capitalize day}}
 
{
  "hour": "minutes away",
  "minute": "seconds away",
  "day": "this is the day!"
}
 
This is the day!

capitalizeAll

Capitalizes the first letter of all the words in a string.

{{capitalizeAll field}}
Template 
On this day, the {{capitalizeAll type}} . . .
Context 
{
  "animal":"canine",
  "type": "dog, wolf, extant grey wolf"
}
Output 
On this day, the Dog, Wolf, Extant Grey Wolf . . .

ceil

Returns the smallest integral value that is greater than or equal to the specified value. In short, ceil rounds the value up to the nearest whole number.

{{ceil field}}
Template Context Output 
{{ceil item1}}
{{ceil item2}}
{{ceil item3}}
 
{
  "item1": "45.75",
  "item2": "62.92",
  "item3": "45.02"
}
 
46
63
46

dateAdd

Adds or subtracts the specified offset value from the specified date and returns the result in the specified time zone.

{{dateAdd dateField offsetField timeZoneField}}

Each of these fields is discussed in further detail below.

Note: not all of the fields in the default expression need to be present, as shown in the some of the examples. See also: dateFormat and timestamp.

In this example, the timeZoneField is set to New York and the offsetField is shifted one day ahead (in milliseconds.) This will render the date one day ahead of what is in the Context. New York is -5:00 UTC, as shown in the output.

Template 
{{dateAdd dateOrders "107280000" "America/New_York"}}
Context 
{
  "dateOrders": "12/14/2019"
}
Output 
2019-12-15T00:48:00-05:00

dateField

{{dateAdd dateField offsetField timeZoneField}}

In the first example below, the offset and timeZone fields have been removed and only the referenced object name:value pair in the Context file will be passed to the output. The Second example shows the offsetField set to one day behind, and is reflected in the output. The third example shows the timeZone Field entered with no offset entered. The fourth example shows a complete expression with the date set to one day ahead.

Template Context Output 
{{dateAdd dateOrders}}
 
{
  "dateOrders":
  "11/5/2019 3:25 PM"
}
 
2019-11-05T15:25:00.000Z
 
{{dateAdd dateOrders "-86400000"}}
 
2019-11-04T15:25:00.000Z
 
{{dateAdd dateOrders "" "America/Los_Angeles"}}
 
2019-11-05T07:25:00-08:00
 
{{dateAdd dateOrders "" "America/Los_Angeles"}}
 
2019-11-05T07:25:00-08:00
 
2019-11-05T07:25:00-08:00

You can also enter a fixed date value in quotes:

{{dateAdd "Mon Nov 21 2019 20:08:40 GMT+0000"}}

Or you can add a standard date and the system will automatically format the output to ISO specification:

{{dateAdd "Nov 21, 2019"}} will output: 2019-11-21T00:00:00.000Z

offsetField

This field allows the date to be set to a hard-coded string. 

{{dateAdd dateField offsetField timeZoneField}}

Time values are expressed in milliseconds

  • “86400000” = one day ahead (86,400,000 ms);
  • "107280000"= two days ahead (107,280,000 ms);
  • “-86400000” = one day behind (-86,400,000);
  • Calculate milliseconds here
  • Scientific notation may also be used: “1E6” = 1M (10^6 or 1,000,000 ms).
Template Context Output 
{{dateAdd dateOrders "86400000"}}
 
{
  "dateOrders": "12/14/2019"
}
 
2019-12-15T00:00:00.000Z
 
{{dateAdd dateOrders "172800000"}}
 
2019-12-16T00:00:00.000Z
 
{{dateAdd dateOrders "-86400000"}}
 
2019-12-13T00:00:00.000Z
 
{{dateAdd date "3.888e+9}}
 
"Wed Aug 08 2019 17:27:13 GMT+0530"
 
2019-09-22T11:57:130.000Z

Setting the date using offsetField

  • The date offset in the first template is set to “86400000” (one day) and the output reflects the date as one day ahead of the dateOrders field in the Context; doubling this number will place the date two days ahead of the date in the value;
  • The second example has the original offsetField value doubled “172800000” (two days);
  • Conversely, placing a minus sign before the numeric value “-86400000” will subtract one day from the date.
  • The fourth example uses scientific notation to increase a date value by 45 days. These offsets must be in milliseconds.

timeZoneField

This field uses standard ISO string date format where the offset value is subtracted from the specified date along with time zone. See the next section for more details on this setting.

{{dateAdd dateField offsetField timeZoneField}}

 Here, the offsetField is set to null “ ” which will output the time in Hong Kong local time which is +8 UTC.

{{dateAdd dateField "" "Asia/Hong_Kong"}}
Template 
{{dateAdd dateOrders "" "Asia/Hong_Kong"}}
Context 
{
  "dateOrders": "12/14/2019"
}
Output 
2019-12-14T08:00:00+08:00

The following examples show the conversion to UTC/GMT/Zulu time. Note that New York is -5 and Hong Kong is +8.

Template Context Output 
{{dateAdd dateOrders " "}}
 
{
  "dateOrders": "11/5/2019 3:25 PM"
}
 
2019-11-05T15:25:00.000Z
 
{{dateAdd dateOrders "" "America/New_York"}}
 
019-11-05T10:25:00-05:00
 
{{dateAdd dateOrders "" "Asia/Hong_Kong"}}
 
2019-11-05T23:25:00+08:00

dateFormat

This helper allows the adjustment and transformation of time and date fields to be output in a particular format and altered according to your needs. The date and time fields are not all required in an expression, and they can be used in a modular fashion.

{{dateFormat o/pformat date i/pformat timezone}}

For current UTC and world time zones, see Wikipedia's list of tz database time zones.

The default date conforms to ISO specification:

  • Structure: YYYY-MM-DD[T]hh:mm:ss.sss[Z]
  • Output: 2019-11-12T21:02:32+00:00
    • The date above is Nov 12, 2019, 1:02:32 PM PDT= 9:02:32 PM UTC

Time and date format codes:

  • YYYY: four-digit year
  • MM : two-digit month (01=January, etc.)
  • DD : two-digit day of month (01 through 31)
  • [T]: Time displayed as Coordinated Universal Time (UTC)
  • HH: two digit hours (00 through 23)
  • hh :  two digit hours (01 through 12) Note: Use with a (am/pm) or A (AM/PM).
  • mm: two digit minutes (00 through 59)
  • ss : two digit seconds (00 through 59)
  • SSS: one or more digits representing a decimal fraction of a second
  • [Z]: expressed in Handlebars as "Zulu Time". If Z is present at the end of the date field, the time at this point will be expressed as Zulu time: +00:00
  • a: am or pm
  • A: AM or PM

For a complete list of all available time and date format codes, see Time and date format codes.

o/pformat

This field allows you to define the time and date format in the template which will be output accordingly. This field also works in concert with the "i/p format" field, which is discussed in further detail below.

{{dateFormat o/pformat date i/pformat timezone}}

Note: All date formats are placed in double quotation marks.

  • “MM-DD-YYYY” = 01-01-2020
  • “MM/DD/YYYY” = 01/01/2020
  • “YYYY.DD.MM” = 2020.31.01
Template 
{{dateFormat "MM-DD-YYYY hh:mm" dateOrders "YYYY-DD-MM hh:mm"}}
Context 
{
  "dateOrders": "1966-25-05 10:36"
}
Output 
05-25-1966 10:36

date

This field passes the current date to the output unless specified in the context file. The following  example shows how to print the current date in the format specified in the o/pformat field in the template.

Template Context Output 
{{dateFormat "MM-DD-YYYY" date}}
 
{
}
 
02-26-2020

i/pformat

This field is the date object referenced in the Context. It can be hard-coded directly in the expression:

{{dateFormat o/pformat date i/pformat timezone}}

o/pformat vs. i/pformat:

  • Output format (o/pformat) is where you define the desired output format
  • Input format (i/pformat) is where you define the "input" format contained in the Context file

In the example below, the JSON Context format is "year/day/month" (1966/25/05). To output the date in the standard US format, define this format in the "o/pformat" field, as shown.

Template 
{{dateFormat "MM-DD-YYYY hh:mm" dateOrders "YYYY-DD-MM hh:mm"}}
Context 
{
  "dateOrders": "1966-25-05 10:36"
}
Output 
05-25-1966 10:36

timezone

This fields utilizes standard ISO string date format where the offset value is subtracted from the specified date along with time zone. 

{{dateFormat o/pformat date i/pformat timezone}}

In the example below, note the "Z" in the o/p format field? this is telling the system to output the timezone assigned in the "timezone" field and adjust the time automatically for the chosen timezone-Los Angeles. 

Template 
{{dateFormat "MM-DD-YYYY hh:mmZ" dateOrders "YYYY-DD-MM hh:mm" "America/Los_Angeles"}}
Context 
{
  "dateOrders": "1966-25-05 10:36-8:00"
}
Output 
05-25-1966 03:36-07:00

decodeURI

Decodes the specified URI. This example decodes the sample dataset from the “encodeURI” example.

{{{decodeURI field}}}

Note: This expression uses three curly braces.

Template 
{{{decodeURI orders}}}
Context 
{
  "orders": "overseas%20order%20flow"
}
Output 
overseas order flow

The URI may also be a “hard-coded” value declared in the expression.

Template 
{{{decodeURI "overseas%20order%20flow"}}}
Context 
{
}
Output 
overseas order flow

If you do not want the parameters inside the placeholder to be encoded (called escaping), use three brackets {{{ }}} - especially, when you intend to perform an encode/decode operation on the strings provided in the argument list (e.g. base64Encode or decodeURI).

HTML Encoded 
{{placeholder}}
HTML and URL Encoded 
{{encodeURI field}}
URL Encoded 
{{{encodeURI field}}}
No Encoding Applied 
{{{ placeholder }}}

divide

Returns the resultant quotient of two specified values. This helper returns the quotient of two variables, “hard-coded” values, or a combination thereof. Absolute values do not require context JSON variables.

{{divide field}}
Template Context Output 
{{divide item1 item2}}
 
{
  "item1": "33",
  "item2": "11",
  "item3": "100"
}
 
3
 
{{divide 2002 100}}
 
20.02
 
{{divide item1 3}}
 
11

encodeURI

This helper expression encodes the specified uniform resource indicator (URI), enclosed in three curly braces.

{{{encodeURI field}}}

Certain characters are used to encode and are not allowed in the source value:

, / ? : @ & = + $ #

Tip: Call decodeURI to decode a previously encoded URI.

Template 
{{{encodeURI orders}}}
Context 
{
  "orders": "overseas order flow"
}
Output 
overseas%20order%20flow

The value may also be declared as a “hard-coded” in the expression with the same output:

{{encodeURI "sample data type"}}

floor

This helper is the inverse of ceil. Floor returns the largest integral value that is less than or equal to the specified number. Floor rounds down a value to the nearest whole number.

{{floor field}}
Template Context Output 
{{floor 22.44}}
 
{
}
 
22
 
{{floor 45.25}}
 
45
 
{{floor 3.14}}
 
3

getValue

This helper returns the value from the specified field.

{{getValue field "defaultValue"}}
Template Context Output 
{{getValue "legends.unicorns" "defaultValue"}}
 
{
  "legends": {
    "unicorns": "11",
    "ponies": "22",
    "horses": "33",
    "total": " "
  }
}
 
11
 
{{getValue "legends.ponies" "defaultValue"}}
 
22 
 
{{getValue "legends.total" "defaultValue"}}
 
null 
 
{{getValue "name" defaultValue}}
{{getValue "state" defaultValue}}
 
{
  "state": "MO",
  "name": "Harry S Truman",
  "qty": "100",
  "ERP_Item": "kit"
}
 
Harry S Truman
MO

Note: The getValue helper method was introduced to retrieve the value from the complete path in the helper method's first argument. The getValue helper fails if used inside the #each block helper because getValue can't derive the complete path for the context of each data iteration.

Examples: This helper is especially helpful if you need to get the name of a field that is dynamically generated. For example:  
{
    "date": "2021-01-09",
    "2021-01-09": "3"
}

To retrieve the value for "2021-01-09" (a dynamically generated field name based on another field value), the field name is unknown until the record is processed. You can use getValue to identify that field name by looking at the value for the "date" field. 

{{getValue (getValue "date")}}

Another example would be as follows:

{
    "date": "2021-01-09",
    "hours": {
        "2021-01-09": "3"
    }
}

Since getValue is a helper method, you can nest other helper methods inside it, which opens up multiple options for dynamically generating the field name.

{{getValue (join "." "hours" (getValue "date"))}}

hash

Use this handlebar helper to cryptographically encode field values.

{{hash algorithm encoding field}}
Template Context Output 
{{{hash "md5" "base64" "name"}}}
 
{
     "id": 123,
     "name": "Bob",
     "age": 33
}
 
sGiTHMRQRCtj9bPSdupClw==
 
{{{hash "md5" "hex" "name"}}}
 
b068931cc450442b63f5b3d276ea4297

hmac

Keyed-hashing for message authentication (HMAC) is a message authentication code generated via cryptographic hash function (such as MD5, SHA-256 and many more).  This crypto key wraps the data until it is authenticated using a shared key. For a complete list of integrator.io support, see Supported encoding algorithms.

{{hmac algorithm key encoding field}}

In this example, the key would be your secret key, or private access key.

Note: Be cautious about exposing the secret key, potentially compromising your system credentials.

Connection details:

  • HTTPS should be used, where standard HTTP should be avoided wherever possible
  • All PARAMETER values must be URI encoded
  • Authorization HEADER {{hmac}} helper must use the "full URL" keyword as the input as the system will calculate the signature based on the complete URL that it receives, including PARAMETER values and the Base URI https

See Using hmacOptions for additional functionality.

join

The join helper joins variable output using the specified delimiter and can handle any number of arguments.

{{join delimiterField field1 field2}}

Delimiters:

(parentheses) {braces} [brackets] or /*

Notes:

  • If a delimiter array is specified, the specified delimiter is introduced between each array value in the result set
  • If a string is specified, the specified subsequent variables are read and the specified delimiter is introduced between them in the result set
Template Context Output 
{{join "**" "unicorns" "ponies"}}
 
{
  "legends" : {
    "unicorns": "11",
    "ponies": "22",
    "horses": "33",
    "total": " "
  }
}
 
unicorns**ponies
 
{{join " + " "unicorns" "ponies" "horses"}}
 
unicorns + ponies + horses
 
{{join "-" "unicorns" "ponies" "horses"}}
 
unicorns-horses
 
{{join "-" "legends" "[unicorns, ponies, horses]"}}
 
legends-[unicorns, ponies, horses]

jsonEncode

Encodes the specified JSON object.

{{jsonEncode field}}
Template Context Output 
{{jsonEncode total}}
 
{
  "orderId": "2468",
  "total": "99.99",
  "state": "ME"
}
 
99.99

jsonSerialize

The jsonSerialize function converts an object value into a JSON serialized string. Three curly braces are used in this expression.

{{{jsonSerialize field}}}
Template 
{{{jsonSerialize elementals}}}
Context 
{
  "elementals": {
    "gnomes": "677",
    "salamanders": "422",
    "sprites": "56",
    "faeries": "277"
  }
}
Output 
{"gnomes":"677","salamanders":"422","sprites":"56","faeries":"277"}

length

Counts the length of a given string for use in other functions.

This example counts the length of the state field. If the length is exactly two characters, integrator.io capitalizes the output. If the length is not exactly two characters, the output is "Bad state value".  

Template 
{{#compare state.length "===" 2}}{{uppercase state}}{{else}}Bad state value{{/compare}}
Context 
{
  "state": "ill"
}
{
  "state": "il"
}
Output 
Bad state value
IL

This example uses length with the compare handlebar to verify a phone number field has exactly 10 digits. If not, the output is ten zeros (0000000000).

Template 
{{#compare phone.length "===" 10}}{{else}}0000000000{{/compare}}
Context 
{
  "phone": "123456789"
}
Output 
0000000000

 lowercase

Converts all letters in a string to lowercase.

{{lowercase field}}
Template 
{{lowercase 'HERE WE GO!'}}
Context 
{
}
Output 
here we go!

multiply

Returns the multiplication of the two specified values. Variables may be referenced in context, or as “hard-coded” values.

{{multiply field}}
Template Context Output 
{{multiply unicorns "5"}}
 
{
  "unicorns": "11",
  "ponies": "22",
  "horses": "33"
}
 
55
 
{{multiply "5" "2"}}
 
10
 
{{multiply horses ponies}}
 
726
 
{{multiply Field1 -1}}
 
{
  "Field1": "-22211.4",
}
 
22211.4

random

Generates a random number with an input field for the length. The default value needs to have either “CRYPTO” or “UUID” added to the template to generate the number.

{{random "CRYPTO" length}}

or

{{random "UUID" length}}
  • "CRYPTO/UUID": the method for random number generation
  • "length": integer value for the number of places in the output
Template Context Output 
{{random "UUID" 5}}
 
{
}
 
5e3ca
 
{{random "CRYPTO" 8}}
 
4ccb3420
Example: You can use random with custom length:
  • Alphanumeric 9 character string: 
    {random "UUID" 9}
  • Numeric 9 character string: 
    {random "CRYPTO" 9}

regexMatch

Matches the input data based on the regular expression and returns the data based on index and options variables.

{{regexMatch field regex index options}}
  • field: the field name containing the variable or values to be replaced. You can reference a field or variable by typing its name without double quotes (or curly braces or parens).
  • regex: the new value which will replace the existing value.
  • index: here, index refers to a the location of the numerical range to be examined when searching for matches, which is useful for known values, e.g. [1-4][0-9][5-6].
  • options: Regex options allow you to modify the search behavior of the expression. For example, regular expressions stop at the first match in the text content by default. A "g" entered in the options position sets the expression to global (meaning that the expression will attempt to match all instances matched throughout the entirety of the text content). For more information on regex options, see regex options. 
Template Context Output 
{{regexMatch secretCode "7" "[0-9]"}}
 
{
  "secretCode": "007"
}
 
7
 
{{regexMatch secretCode "007" "[0-9]"}}
 
007
 
{{regexMatch secretCode "[0-2][0-2][5-7]"}}
 
007
 
{{regexMatch secretCode "[0-9][0-9][0-9]" 1 "g"}}
 
{
  "secretCode": "123 3456 678 celigo 32"
}
 
345

regexReplace

The regexReplace helper returns a modified string where the pattern has been replaced.

{{regexReplace field replacement regex options}}
  • field: the field name containing the variable or values to be replaced. You can reference a field or variable by typing its name without double quotes (or curly braces or parens).
  • search: the new value that will replace the matching value in regex.
  • regex: the regular expression that you’re searching for.
  • options: regex options allow you to modify the search behavior of the expression. For example, regular expressions stop at the first match in the text content by default. A "g" entered in the options position sets the expression to global (meaning that the expression will attempt to match all matching instances throughout the entirety of the text content). For more information on regex options, see regex options. 

In this example, the output has the word “Sequence” replacing the number 6 in the Context.

Template 
{{regexReplace secretCode "Sequence" "[6]"}}
Context 
{
  "secretCode": "1234567890"
}
Output 
12345Sequence7890

Alternately, you could change the price of an incorrect value by entering the number to change and assigning the value of the overwrite. Here, we have modified $249.99 to $549.99 and $9.99 to $19.99 respectively.

Template Context Output 
{{regexReplace total "5" "[2]"}}
 
{
  "items": "orders",
  "total": "$249.99",
  "tax": " "
}
 
$549.99
 
{{regexReplace total "19" "[9]"}}
 
{
  "items": "orders",
  "total": "$9.99",
  "tax": " "
}
 
$19.99

You can use the following regexReplace expression to remove leading zeros from a field value. 

Template Context Output 
{{regexReplace id "" "^0+" "g"}}
 
{
  "id": "000000157"
}
 
157

See also Regular expressions (regex).

regexSearch

The regexSearch helper uses an expression to search for a match, and returns the position of the result in the dataset, where 0=first position and 2=third position.

{{{regexSearch field regex options}}}
  • field: the field name containing the variable or values to be replaced.
  • regex: the new value which will replace the existing value.
  • options: Regex options allow you to modify the search behavior of the expression. For example, regular expressions stop at the first match in the text content by default. A "g" entered in the options position sets the expression to global (meaning that the expression will attempt to match all matching instances throughout the entirety of the text content).  
Template 
{{regexSearch total 5}}
Context 
{
  "items": "orders",
  "total": "$1499.95",
  "tax": " "
}
Output 
7
(where 5 is the eighth value (INDEX location=7) in the “total” JSON field value)

replace

Replaces all the occurrences of the specified letter in a string with another letter.

{{replace field string string}}
Template Context Output 
{{replace cases "&" "and"}}
 
{
  "cases": "these & those & some other cases"
}
 
these and those and some other cases
 
{{replace description "Shoes" "Boots"}}
 
{
  "description": "Shoes",
  "qty": 1
}
 
Boots

round

Rounds a number up or down the specified value to the nearest whole value.

{{round field}}
Template 
{{round vat}}
Context 
{
  "vat": "29.77"
}
Output 
30

sort

This helper sorts the specified values in ascending or descending order based on the value specified in the ”reverse” parameter. By default, this helper sorts the array variables in an ascending manner. If the input array contains numerical variables for sorting, set the number parameter = "true". You can also combine reverse and number option parameters in the handlebars expression.

{{sort field number="true" reverse="true"}}
Template Context Output 
{{sort items number="true"}}
 
{
  "items": ["2","1","4","5","3"]
}
 
1,2,3,4,5 
 
{{sort items reverse="true"}}
 
5,4,3,2,1
 
{{sort items}}
 
{
  "items": ["candy", "hat", "toy"]
}
 
candy,hat,toy

split

Splits a series of words separated by delimiters in the context based on an index value, where 0=first position and 2=third position.

{{split field delimiter index}}
Template Context Output 
{{split fullName "-" 0}}
 
{
  "fullName": "Hillary-Ann-Swank"
}
 
Hillary
 
{{split fullName "-" 1}}
 
Ann
 
{{split fullName "-" 2}}
 
Swank
 
{{split fullName "-" 0}}
{{split fullName "-" 1}}
{{split fullName "-" 2}}
 
Hillary
Ann
Swank

subtract

Returns the remainder of two values. 

{{subtract minuend subtrahend}}
These are just mathematical terms for:
{{subtract value value}}

You can subtract the values of two fields, integers, or strings in this handlebars expression. If you are passing fields or integers, do not use quotes. If you are using string values, make sure to use quotes.

Template Context Output 
{{subtract "6" "3"}}
 
{
  "unicorns": "11",
  "ponies": "22",
  "horses": 33,
  "total": "66"
}
 
3
 
{{subtract 6 3}}
 
3
 
{{subtract "6" ponies}}
 
-16
 
{{subtract horses "6"}}
 
27
 
{{subtract ponies unicorns}}
 
11

substring

Returns a substring of the specified string. This is useful for shortening the names of longer field names.

{{substring stringField startIndex endIndex}}
  • stringField is the actual string
  • startIndex is index of the actual at which the substring starts, where 0=first position and 2=third position
  • endIndex is the index of the actual string where the substring ends, where 0=first position and 2=third position
  • endIndex acts like JavaScript and is non-inclusive
Template Context Output 
{{substring "itemizationCode" "0" "4"}}
 
{
}
 
item
 
{{substring "inventory" "0" "3"}}
 
inv

sum

Computes the sum of all numbers present in the specified array. The example below only shows integers, but it also works with floats and decimals.

Note: this is different from the add helper function and performs additional calculations.

{{sum field1 field2 field3}}
Template Context Output 
{{sum items}}
 
{
  "items": [2,5,7,8,9]
}
 
31
 
{{sum items}}
 
{
  "items": [
    50 , 10 , 10 , 10 , 5 , 5 ,
    60 , 10 , 10 , 10 , 5 , 5 ,
    50 , 10 , 10 , 10 , 10 , 10 
  ]
}
 
290
 
{{sum (multiply 2 55)}}
 
{
}
 
110

timestamp

Returns a timestamp in the format and timezone provided. If no timezone is provided, this function uses the timezone set in your profile settings. If your profile has no timezone set, the server's configured timezone is used. 

{{timestamp format timezone}}

The first example below shows the local time in Los Angeles, which is 09:27:46 (HH:MM:SS), but is followed by the Zulu time offset (-08:00).

In the second example, the current time is displayed in Zulu time (as the server is configured).

Template Context Output 
{{timestamp HH:MM:SS "America/Los_Angeles"}}
 
{
} 
 
2021-02-05T09:27:46-08:00
 
{{timestamp HH:MM:SS}}
 
2021-02-05T17:38:20.715Z


toExponential

Returns a string representing the specified number in an exponential format. Variables may be referenced in context or as “hard-coded” values.

{{toExponential field fractionDigits}}
      • field: is the number or object value to be modified;
      • fractionDigits: an optional parameter that will display the provided number of digits after the decimal place.
Template Context Output 
{{toExponential orderId 2}}
 
{
  "orderId": "12345",
  "total": "99.99"
}
 
1.23e+4
 
{{toExponential "12345" 2}}
 
{
} 
 
1.23e+4
 
{{toExponential "3.14159265359" 6}}
 
3.141593e+0

toFixed

This will set a fixed numerical value to the output string, and format the number to a fixed number of decimal places.

{{toFixed field digits}}
  • field: the number to be modified
  • digits: number of decimal places to be displayed
{{toFixed 123.456789 0}} = 123
{{toFixed 123.456789 1}} = 123.5
{{toFixed 123.456789 2}} = 123.46
{{toFixed 123.456789 3}} = 123.457
{{toFixed 123.456789 4}} = 123.4568
{{toFixed 123.456789 5}} = 123.45679

toPrecision

This outputs scientific notation if there are more integer digits (before decimals) than the specified precision.

{{toPrecision field precision}}
  • field: the number to be modified
  • precision: number of decimal places to be displayed
{{toPrecision 123.00 0}} = 1e+2
{{toPrecision 123.00 1}} = 1e+2
{{toPrecision 123.00 2}} = 1.2e+2
{{toPrecision 123.00 3}} = 123
{{toPrecision 123456.00 5}} = 1.2346e+5
{{toPrecision 1234567.00 6}} = 123456

trim

This helper will remove (trim) any white space in a Trims whitespace characters present at the beginning and at the end of the string.

{{trim field}}

Use the trim field if you have white space that persists in your file across all values. Here, the whitespace is before the “artist” value as seen in the output like this:

handlebarHelpersSnip.png

The problem is also evident in the context below, and the example shown in the Template will resolve the white space issue in the output.

Template Context Output 
{{trim library.artist}}
 
{
  "library": {
    "album": "The Sound",
    "title": "Danube Incident",
    "artist": " Lalo Schifrin"
  }
}
 
Lalo Schifrin

uppercase

Converts all lowercase characters in the JSON field value or string to uppercase.

{{uppercase field}}
Template Context Output 
{{uppercase "library"}}
 
{
}
 
LIBRARY
 
The {{uppercase family.type}} is a member
of the {{uppercase family.animal}} family
 
{
  "family": {
    "animal":"canine",
    "type": "dog"
  }
}
 
The DOG is a member
of the CANINE family

Block Helpers

Block helpers have a hash symbol at the beginning. 

#and

The #and block helper renders the expression if both of the specified parameters are true (according to JavaScript rules). If the result is false, the {{else}} expression prints in the output. If the field is undefined, null, or an empty string, it will evaluate as false, otherwise it will be true. The integer value of 0 will evaluate to false; however, the STRING value of "0" evaluates to true, as all non-empty strings are true:

{{#and field field}} expr {{else}} expr {{/and}}
Template Context Output 
1. {{#and Contact.homeAddress Contact.offAddress}}true{{else}}false{{/and}}
2. {{#and Contact.homeAddress emptyString}}true{{else}}false{{/and}}
3. {{#and Contact.homeAddress nullField}}true{{else}}false{{/and}}
4. {{#and Contact.homeAddress zeroValue}}true{{else}}false{{/and}}
5. {{#and Contact.homeAddress zeroString}}true{{else}}false{{/and}}
6. {{#and Contact.homeAddress zeroInteger}}true{{else}}false{{/and}}
 
{
  "Contact": {
    "homeAddress": "123 Anywhere",
    "offAddress": "789 Somewhere" 
  },
  "emptyString": "",
  "nullfield": null,
  "zeroString": "0",
  "zeroInteger": 0 
}
 
1. true
2. false
3. false
4. false
5. true
6. false
 
{{#and legends.unicorns
legends.horses}}
{{legends.unicorns}} -
{{legends.horses}}
{{else}} Not found
{{/and}}
 
{
  "legends": {
    "unicorns": "11",
    "ponies": "22",
    "horses": "33",
    "total": "66"
  }
}
 
11-33
 
{{#and firstName lastName}}
{{firstName}}
{{middleName}}
{{lastName}}
{{else}}Not found
{{/and}}
 
{
  "fullName": "Hillary Ann Swank",
  "firstName": "Hillary",
  "middleName": "Ann",
  "lastName": "Swank"
}
 
Hillary Ann
Swank

#compare

The #compare block helper compares two variables using a logical operator.

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

The compare helper compares data variables against each other using logical operators. The "else" statement is used to output text if the argument returns a false condition.

Template 
{{#compare details.fromState "===" "NE"}}+{{details.qty}}
{{else}}{{details.qty}}{{/compare}}
{{#compare details.fromState "===" "AK"}}TRUE: {{details.qty}}
{{else}}FALSE{{/compare}}
Context 
{
  "export": {},
  "details": {
    "fromState": "NE",
    "customerName": "Thomas",
    "customerId": "22222",
    "qty": "3",
    "other": " " 
  }
}
Output 
+3

FALSE

The second argument is the arithmetic operator to be used for comparing the two arguments. Optionally, you can also specify the {{else}} expression to render the value when #compare returns FALSE.

In the following example, reversing the operator will change the output to “false.”

Template 
{{#compare sample1 ">" sample2}} true {{else}} false {{/compare}}
Context 
{
  "sample1": "50",
  "sample2": "100",
  "sample3": "200"
}
Output 
true

This example shows a comparison of the quantity on hand against the quantity ordered, and logical output.

Template 
{{#compare qty ">=" ordered}}Please ship {{qty}} units
{{else}} do-not-ship{{/compare}}
Context 
{
  "state": "VA",
  "name": "Thomas Jefferson",
  "part": "R1",
  "qty": "100",
  "ordered": "100",
  "inventoryOnOrder": "1000",
  "ERP_Item": "kit"
}
Output 
Please ship 100 units

This example uses compare to verify a phone number field has exactly 10 digits. If not, the output is ten zeros (0000000000).

Template 
{{#compare phone.length "===" 10}}{{else}}0000000000{{/compare}}
Context 
{
  "phone": "123456789"
}
Output 
0000000000

Logical Operators for #compare

Operator Description
<  Less than (a < b)
>  Greater than (a > b)
<=  Less than or equal to (a <= b)
>=  Greater than or equal to (a >= b)
==  Equal to (a == b)
===  Strict equal to (a === b)
!=  Not equal to (a != b)
!==  Strict not equal to (a !== b)

Note: You can reference literal strings in compare statements by surrounding the literal string in double quotation marks. For example: {{#compare record.Domain "==" "eu.integrator.io"}}

Compare with else

This example shows the #compare block helper with a nested compare expression. The sample compares the quantity order with current inventory levels. It then compares the current inventory levels with items on order. If the order can be successfully filled, the expressions return “Match”. If not, the output returns “Inventory levels too low”.

Template 
{{#compare ordered "<=" stockLevel}}Match{{else compare stockLevel "<"
inventoryOnOrder}}Match{{else}}Inventory levels too low{{/compare}}
Context 
{
  "state": "NE",
  "name": "Thomas",
  "qty": "100",
  "ordered": "100",
  "stockLevel": "10",
  "inventoryOnOrder": "1000",
  "ERP_Item": "kit"
}
Output 
Match

#contains

The #contains block helper parses the name:value specified in the block to check for the presence of a given value. If the value specified is not present, then it prints the {{else}} expression.

{{#contains fieldArray field}} optionalTextIfTrue {{else}} optionalTextIfFalse {{/contains}}

The fieldArray value can be an array name, arrayname.keyname, or a string that will be interpreted as an array.

In the first example, the order.item value is “12345”. The specified value in the #contains block is “5”. Since 5 is a number present in the value, the first expression statement will be displayed. The second example is looking for a “6”. Since 6 is not present, the else statement it output. 

Template Context Output 
{{#contains order.item "5"}}
Sales ID Found!
{{else}}Sales ID Missing!
{{/contains}}
 
{
  "order": {
    "item": "12345"
  }
}
 
Sales ID Found!
 
{{#contains order.item "6"}}
Sales ID Found!
{{else}}Sales ID Missing!
{{/contains}}
 
{
  "order": {
    "item": "12345"
  }
}
 
Sales ID Missing!
 
{{#contains order.sales "2"}}
Sales ID Found!
{{else}}Sales ID Missing!
{{/contains}}
 
{
  "order": {
    "sales": ["2","3","59","4","9","10","7"]
  }
}
 
Sales ID Found!

The example below shows an if/then argument against the product and whether or not a product warranty was purchased via an if_else argument against the context fields specified.

Template 
{{#contains ERP_Item "kit"}}+1{{else}}None found{{/contains}}
{{#contains warranty "yes"}}Warranty included{{/contains}}
Context 
{
  "state": "NE",
  "name": "Thomas",
  "id": "22222",
  "qty": "100",
  "ordered": "100",
  "stockLevel": "100",
  "returned": "100",
  "other": " ",
  "ERP_Item": "kit",
  "warranty": "yes"
}
Output 
+1
Warranty included

#each

This helper allows you to iterate over a list. Inside the #each block, you can reference the element to be iterated over.

{{#each field}}{{this}}{{/each}}

This example shows a simple record with names. The {{each}} expression will reference the context while the {{this}} expression will iterate over the array of items in the [people] array.

For the example below, in integrator.io, the [people] array must be referenced as absolute path in the  Resource path field. If the context was an object (name:value pair), then the path would not need to be set.

BlockHelperEach.png

Also in this example, the semicolon and space between the expressions will allow spacing and punctuation between the variables on output.

Template 
{{#each people}}{{this}}; {{/each}}
Context 
{
  "people": [
    "Bertram Gilfoyle",
    "Erlich Bachman",
    "Jin Yang"
  ]
}
Output 
Bertram Gilfoyle; Erlich Bachman; Jin Yang;

This example shows the system iterating over the array in the "field.names" variables.

Template 
{{#each fields.names}}{{#each this}} Employee {{@key}}: {{this}}
{{/each}}{{/each}}
Context 
{
  "fields": {
    "field": "sample",
    "field2": "row2",
    "rights": [
      "system",
      "admin",
      "editor",
      "contributor",
      "viewer",
      "vendor"
    ],
    "names": [
      {"name1":"Stacy"},
      {"name2":"Lance"},
      {"name3": "Bernice"}
    ]
  }
}
Output 
Employee name1: Stacy
Employee name2: Lance
Employee name3: Bernice

When looping through items in {{#each}}, you can also reference the current loop index.

Template 
System privilege levels: {{@index}}
{{#each fields.rights}}
{{@index}}: {{this}}
{{/each}}
Context 
{
  "fields": {
    "field": "sample",
    "field2": "row2",
    "rights": [
      "system", 
      "admin", 
      "editor", 
      "contributor", 
      "viewer", 
      "vendor"
    ],
    "names": [
      {"name1":"Stacy"},
      {"name2":"Lance"},
      {"name3": "Bernice"}
    ]
  }
}
Output 
System privilege levels:
0: system
1: admin
2: editor
3: contributor
4: viewer
5: vendor

Additionally for iterating over objects, {{@key}} will reference the current key name. @key will
provide the current index location in an array or the key names in the Context.

Template 
{{#each fields.rights}}
  {{@key}}:{{this}};
{{/each}}
Context 
{
  "fields": {
    "field": "sample",
    "field2": "row2",
    "rights": [
      "system",
      "admin",
      "editor",
      "contributor",
      "viewer", 
      "vendor"
    ],
    "names": [
      {"name1":"Stacy"},
      {"name2":"Lance"},
      {"name3": "Bernice"}
    ]
  }
}
Output 
0:system; 1:admin; 2:editor; 3:contributor; 4:viewer; 5:vendor;

The first and last steps of iteration are noted via the @first and @last variables when iterating over an array. When iterating over an object only the @first is available. Nested each blocks may access the iteration variables via depth based paths. To access the parent index, for example, {{@../index}} can be used.

The each helper also supports block parameters, allowing for named references anywhere in
the block.

Template 
{{#each fields.rights}}
  {{@key}}:{{this}};
{{/each}}
Context 
{
  "fields": {
    "field": "sample",
    "field2": "row2",
    "rights": [
      "system",
      "admin",
      "editor",
      "contributor",
      "viewer",
      "vendor"
    ],
    "names": [
      {"name1":"Stacy"},
      {"name2":"Lance"},
      {"name3": "Bernice"}
    ]
  }
}
Output 
0:system; 1:admin; 2:editor; 3:contributor; 4:viewer; 5:vendor;

To create a list or convert data based on index location in a record, you can declare an |item| using vertical bars (pipe character), then entering the characters by their respective index locations (where 0=first character).

Template 
{{#each inventoryItems as |item|}}
  {{item.[0]}}: {{item.[10]}}
{{/each}}
Context 
{
  "inventoryItems": {
    "X": "1001 text a",
    "Y": "2002 text b",
    "Z": "3003 text c"
  }
}
Output 
1: a
2: b
3: c

#if_else

The #if _else helper allows an if/then argument.

{{#if field}} expr {{else}} expr {{/if}}

If the argument in the {{#if field}} is true, then it prints the value from the context. If the argument is false (either undefined, null, " ", 0, or [ ] ), then the block prints the else condition. In the first example below, the contact.phone number is present in the context file (true), so according the argument the phone value prints to output. In the second example, the phone name:value pair is absent (false), so the block prints the else statement value (1-800-555-1212).

If Else logical operators

The following logical operators may be used for building an argument or placing arguments inside expressions. 

if

If a specified condition is true, this specifies a block of code to be executed

If the condition is false, another block of code can be executed.

{{#if data.name}}{{data.name}}{{/if}}
if_else

This statement is a part of JavaScript's "Conditional" Statements, which are used to perform different actions based on different conditions, and will execute a block of code if a specified condition is true.

{{#if Name}}{{Name}}{{else}}{{/if}}
else Specifies a block of code to be executed if the same condition is false.
else_if Specifies a new condition to test if the first condition is false.
compare

Compares two values using logical operators.

{{#compare field operator field}} expr {{else}} expr {{/compare}}
each 
{{#each data.identity-profiles}} {{vid}} {{/each}}
if_compare 
{{#if data.name}}{{#compare data.name "!="
""}}{{data.name}}{{else}}{{/compare}}{{/if}}

#ifEven

This argument checks to see if a given value is an even number.

{{#ifEven field}} expr {{else}} expr {{/ifEven}}

If the argument results in an even number (true), the value prints to output. If the argument results in an odd number (false), the {{else}} expression displays. A blank expr field prints the value unless text is specified, as shown below.

Template Context Output 
{{#ifEven orders.item1}}
  {{orders.item1}}
{{else}}
  Odd Value
{{/ifEven}}
 
{
  "orders": {
    "item1": "2",
    "item2": "5",
    "item3": "8"
  }
}  
 
2
 
{{#ifEven orders.item2}}
  The even number value is {{orders.item2}}
{{else}}
  Odd number value
{{/ifEven}}
 
Odd number value
 
{{#ifEven orders.item3}}
  The even number value is {{orders.item3}}
{{else}}
    Odd number value
{{/ifEven}}
 
The even number value is 8

#neither

This helper is used for building true/false arguments.

{{#neither field field}} expr {{else}} expr {{/neither}}
  • If both parameters are equal to false, the first expression displays.
  • If one or both are equal to true, the {{else}} expression statement displays.

In this example, both the values in the Context are blank /null (which makes the argument true), so the first expression is printed to output.

Template 
{{#neither item1 item2}}
  Values are absent for the specified parameters.
{{else}}
  Only one of the parameters has a value.
{{/neither}}
Context 
{
  "item1": "",
  "item2": ""
}
Output 
Values are absent for the specified parameters.

In this example, only one of the Context variables is blank, so the argument will pass the {{else}} statement to the output.

Template 
{{#neither item1 item2}}
  Values are absent for at least one of the specified parameters.
{{else}}
  Only one of the parameters has a value.
{{/neither}}
Context 
{
  "item1": "",
  "item2": "5"
}
Output 
Only one of the parameters has a value.

#or

This helper creates an all-or-nothing argument. It prints the first expression if the argument is true, and the {{else}} expression if the argument is false.

{{#or field field}} expr {{else}} expr {{/or}}
Template Context Output 
{{#or item1 item2}}
  One or both fields have a data value
{{else}}
  Neither field has a data value
{{/or}} 
 
{
  "item1": "100",
  "item2": "15000"
}
 
One or both fields have a data value.
 
{
  "item1": "",
  "item2": ""
}
 
Neither field has a data value.

#unless

The #unless helper is the inverse argument of the #if block helper. The #unless block renders if the #unless expression returns a false value.

{{#unless field}} expr {{else}} expr {{/unless}}
Template Context Output 
{{#unless contact.phone}}
  Phone number missing
{{else}}
  Contact phone number
{{contact.phone}}
{{/unless}} 
 
{
  "contact": {
    "phone": "310-555-1234",
    "street": "streetName",
    "address": "streetAddress"
  }
}
 
Contact phone number is:
310-555-1234
 
{
  "contact": {
    "street": "streetName",
    "address": "streetAddress"
  }
}
 
Phone number missing

#with

The #with helper demonstrates how to pass a parameter to your helper. When a parameter calls a helper, it is invoked with whatever context the template passed in. This allows access to nested objects in the context without having to repeatedly type the parent name in each expression. 

Template 
{{#with library}}{{title}} on "{{album}}" by {{artist}} {{/with}}
Context 
{
  "library": {
    "album": "The Sound",
    "title": "Danube Incident",
    "artist": "Lalo Schifrin"
  }
}
Output 
Danube Incident on "The Sound" by Lalo Schifrin

The with helper passes a parameter to a helper.

{{#with field}} {{field1}} {{field2}} {{/with}}

When a parameter calls the helper, it invokes the context from the template.

Template 
The author{{#with author}} {{firstName}} {{lastName}}{{/with}}
Context 
{
  "title": "A Tale of Two Cities",
  "author": {
    "firstName": "Charles",
    "lastName": "Dickens"
  }
}
Output 
Output The author Charles Dickens

Nesting Block Helpers

The following expressions describe the expression format and samples for block helpers. Variables and “hard-coded” values may be nested and referenced. 

Template 
{{#if contact.phone}}{{contact.phone}}
{{else}} Phone number not found
{{/if}}
Context 
{
  "contact": {
    "name": "Jack Parsons Laboratory",
    "phone": "310-555-1234"
  }
}
Output 
310-555-1234

Block Helpers may also be nested as shown below.

Template 
{{#compare customer1 "==" "2"}}
{{#compare customer2 "==" "5"}}
  True
{{else}}
  False
{{/compare}}{{else}}
  False
{{/compare}}
Context 
{
  "customer1": "2",
  "customer2": "5"
}
Output 
True

Raw blocks

Raw blocks are virtually the same as block helpers; however, child content is treated as a literal string.

Template Context Output 
{{{{name}}}}
  {{Samantha}}
{{{{/name}}}}
 
{

}
 
{{Samantha}}

@Data Variables

@root

You can use the @root data variable to access the root element properties while you iterate in the context of any nested or child elements. The following sample JSON and Template scenarios explain more about @root.

Template Context Output 
{{@root.title}}
 
{
  "title": "My New Post",
  "body": "This is my first post!",
  "array": [1,2,3,4],
  "message": "This is the message."
}
 
My New Post
 
{{#each array}}{{@root.title}}
{{/each}}
 
{
  "title": "My New Post",
  "body": "This is my first post!",
  "array": [1,2,3,4],
  "message": "This is the message."
}
 
My New Post
My New Post
My New Post
My New Post
 
 {{@root.child.childTitle}}
 
{
  "title": "My New Post",
  "body": "This is my first post!",
  "array": [1,2,3,4],
  "message": "This is the message.",
  "child": {
    "childTitle": "Child Title",
    "childBody": "Child Body"
  }
}
 
Child Title

@key

This data variable provides the current index location in an array or the key names in the context. The key is the index value of the array. When iterating through values in an array (such as the array object here), the output would always start with 0. This is because arrays are zero-indexed.

Template Context Output 
{{#each array}}
{{@key}}
{{/each}}
 
{
  "title": "My New Post",
  "body": "This is my first post!",
  "array": [1,2,3,4],
  "message": "This is the message.",
  "child": {
    "childTitle": "Child Title",
    "childBody": "Child Body"
  }
}
 
0 1 2 3
{{#each array}}
{{@key}}
{{/each}}		 {
"title": "My New Post",
"body": "This is my first post!",
"array": ["one","two","three","four"],
"message": "This is the message.",
"child": {
"childTitle": "Child Title",
"childBody": "Child Body"
}
}		 0 1 2 3 
{{#each @root.child}}
{{@key}}
{{/each}}
 
{
  "title": "My New Post",
  "body": "This is my first post!",
  "array": [1,2,3,4],
  "message": "This is the message.",
  "child": {
    "childTitle": "Child Title",
    "childBody": "Child Body"
  }
}
 
childTitle
childBody

 
{{#each @root}}
{{@key}}
{{/each}}
 
{
  "title": "My New Post",
  "body": "This is my first post!",
  "array": [1,2,3,4],
  "message": "This is the message.",
  "child": {
    "childTitle": "Child Title",
    "childBody": "Child Body"
  }
}
 
title body array
message child

@index

This data variable gives you the current index in an array iteration or in a JSON iteration in the context of #each.

Template Context Output 
{{#each @root.child}}
{{@index}}
{{/each}}
 
{
  "title": "My New Post",
  "body": "This is my first post!",
  "array": [1,2,3,4],
  "message": "This is the message.",
  "child": {
    "childTitle": "Child Title",
    "childBody": "Child Body"
  }
}
 
0 1
 
{{#each @root.people}}
{{@index}}
{{/each}}
 
{
  "people": [
    "Bertram Gilfoyle",
    "Erlich Bachman",
    "Jin Yang"
  ]
}
 
0 1 2

@first

This data variable returns true for the first element of an array or an object. When iterating through values in an array (such as the array object here), the output would always start with 0. This is because arrays are zero-indexed.

Template Context Output 
{{#each @root.child}}
{{#if @first}}
{{@key}}
{{/if}}
{{/each}}
 
{
  "title": "My New Post",
  "body": "This is my first post!",
  "array": [1,2,3,4],
  "message": "This is the message.",
  "child": {
    "childTitle": "Child Title",
    "childBody": "Child Body"
  }
}
 
childTitle
 
{{#each array}}
{{#if @first}}
{{@key}}
{{/if}}
{{/each}}
 
{
  "title": "My New Post",
  "body": "This is my first post!",
  "array": [1,2,3,4],
  "message": "This is the message.",
  "child": {
    "childTitle": "Child Title",
    "childBody": "Child Body"
  }
}
 
0
{{#each array}}
{{#if @first}}
{{@key}}
{{/if}}
{{/each}}		 {
"title": "My New Post",
"body": "This is my first post!",
"array": ["apple","orange","pear","banana"],
"message": "This is the message.",
"child": {
"childTitle": "Child Title",
"childBody": "Child Body"
}
}		 0

@last

This data variable returns true for the last element of an array or an object. When iterating through values in an array (such as the array object here), the output would always start with 0. This is because arrays are zero-indexed.

Template Context Output 
{{#each @root.child}}
{{#if @last}}
{{@key}}
{{/if}}
{{/each}}
 
{
  "title": "My New Post",
  "body": "This is my first post!",
  "array": [1,2,3,4],
  "message": "This is the message.",
  "child": {
    "childTitle": "Child Title",
    "childBody": "Child Body"
  }
}
 
childBody
 
{{#each array}}
{{#if @last}}
{{@key}}
{{/if}}
{{/each}}
 
{
  "title": "My New Post",
  "body": "This is my first post!",
  "array": [1,2,3,4],
  "message": "This is the message.",
  "child": {
    "childTitle": "Child Title",
    "childBody": "Child Body"
  }
}
 
3
 
{{#each array}}
{{#if @last}}
{{@key}}
{{/if}}
{{/each}}
 
{
  "title": "My New Post",
  "body": "This is my first post!",
  "array": [
    "apple",
    "orange",
    "pear",
    "banana"
  ],
  "message": "This is the message.",
  "child": {
    "childTitle": "Child Title",
    "childBody": "Child Body"
  }
}
 
3

 

Related articles

Comments

28 comments

Date Votes
  • Tony Zuko

    Thank you for the reference! Where can I find a list of options for the "options" parameter for regexMatch?

    0
    Comment actions Permalink
  • Tom Santiago

    Hi Tony, I've updated the article to link to this resource for regex options: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions. I hope that helps. Thanks for the feedback.

    1
    Comment actions Permalink
  • Jeff Dollard

    Is there an example for the #switch syntax?  It's the only block logical operator that doesn't have any hint as to the syntax.

     

    0
    Comment actions Permalink
  • Courtney Jordan

    Hi Jeff Dollard,

    Thanks for providing this feedback! We're looking into this for you.

    0
    Comment actions Permalink
  • David Gollom

    The substring description for the end index doesn't match the behavior.  The end index acts like javascript and it's non-inclusive.  That should be noted above.  This was baffling me for a bit.  How did this {{substring "itemizationCode" 0 4}} return "item" ?? 

     

    0
    Comment actions Permalink
  • Courtney Jordan

    Hi David Gollom,

    Thanks for letting us know - I updated the article with this note. Is there anything else we should add based on your findings? Thank you so much for your help!

    0
    Comment actions Permalink
  • Courtney Jordan

    Hi Jeff Dollard,

    We haven't found any information on the switch handlebars. Have you had any luck?

    0
    Comment actions Permalink
  • Jeff Dollard

    Hi Courtney - no luck with the switch syntax, I sort of gave up on guessing at it ¯\_(ツ)_/¯

     

    I found another way to structure my logic, so it didn't keep me from moving forward.

    0
    Comment actions Permalink
  • Courtney Jordan

    Awesome, glad to hear it, Jeff Dollard! Any cool tips you can share that we could add to the docs?

    0
    Comment actions Permalink
  • APC DSR

    Shouldn't the output be "123 Anywhere789 Somewhere"? Both have values.

    0
    Comment actions Permalink
  • Tom Santiago

    Hi APC DSR, 

    This image describes why the expression evaluates to false:

    We've revised the example for clarity.

    0
    Comment actions Permalink
  • Courtney Jordan

    Thank you so much for letting us know how we could improve the article, APC DSR! Please let us know if there are other things we can add! We've also added more examples to the #and section. Hope they're helpful!

    0
    Comment actions Permalink
  • viliandy leonardo

    Jeff Dollard 

    I want to let you know that the "Switch" syntax is not supported. We are updating this KB. Thanks for bringing it to our attention!

    0
    Comment actions Permalink
  • Jeff Dollard

    Do sum and add helpers only work with integers or can they be used with decimals/float values?

    0
    Comment actions Permalink
  • Courtney Jordan

    Hi Jeff Dollard,

    That's a great question and we'll update our article accordingly. I just tested this and decimals and floats seem to work fine for both add and sum. Let us know if you run into any issues!

    0
    Comment actions Permalink
  • Steve Klett

    I'm trying, but I don't understand the purpose of getValue,- why not just reference the field directly?

    {{field}}

    Apparently there is a second parameter with "default value" used in the example, but I don't how it's used.

    Why does the following example return null? I would expect either an empty string or... "default Value"

    {{getValue "legends.total" "defaultValue"}}

    Anyway, I was reading this page (again) and stopped on getValue to learn about it and after failing to do so I thought I'd leave this comment.

     

     

    0
    Comment actions Permalink
  • David Gollom

    The regexReplace section seems to be missing something in the template.  It should read {{regexReplace field replacement regex options}}. I'm not sure about the index bit.  There's reference to an index parameter but I wasn't able to get that to work.   Thanks! 

    0
    Comment actions Permalink
  • Stephen Brandt

    Hi, Steve Klett. That's a great question. After conferring a bit, we realized that this description indeed needs clarification, and there are some scenarios where {{getValue}} is your "helper" after all. 

    getValue comes in handy when the name of a field is dynamically generated. For example, consider this sample data:

    {
      "date": "2021-01-09",
      "2021-01-09": "3"
    }

    Let's say that we need to retrieve the value for 2021-01-09, and that field name was dynamically generated in the data.

    We would not be aware of that name ahead of time. Instead, we can identify that field by looking at the value for the date field, as follows:

    {{getValue (getValue "date")}}

    Since "getValue" is a helper method, we can nest other helper methods inside it, which also opens up multiple options for dynamically generating the field name.

    0
    Comment actions Permalink
  • Steve Klett

    Not sure what level of feedback is actually wanted by the Celigo team, this may be considered petty - if so, tell me offline.

    The subtract documentation states:

    Note: This helper does not require quotation marks for JSON variables.

    This is inaccurate, you can use Number types rather than strings.

    {{subtract 10 6}} == 4

    The description also shows the syntax as

    {{subtract field field}}

    seems like

    {{subtract value value}}

    would be more general.

    0
    Comment actions Permalink
  • Stephen Brandt

    David Gollom, your post is consistent with the examples and every regexReplace usage/result that I've seen. 

    I suspect that that was a copy-paste error from {{substring}}, waiting many months for your careful read. We'll review and update. Thanks much!

     

    0
    Comment actions Permalink
  • Courtney Jordan

    Hi Steve Klett,

    Never would we turn down your valuable help! We really appreciate you sharing this with us. I've made updates to the subtract section. Please let us know if you notice anything else we should change. Thank you so much for your help!

    0
    Comment actions Permalink
  • Stephen Brandt

    Thanks, Steve Klett, for the non-petty feedback. This is the right place, for other readers, as well. 

    Your uses of {{subtract}} are correct, and the examples in the article would benefit from demonstrating additional data types, which we'll add. 

    A couple points of clarification: 

    • I suspect that this helper has become more "forgiving" with allowed values since this article was written.
    • The note about "quotation marks for JSON variables" is confusing and should be removed. However, I don't think that it was added to make any distinction between passing strings vs. integers. It was probably to avoid having new customers type {{subtract "product.qty" "sold"}} as opposed to {{subtract product.qty sold}}.
    0
    Comment actions Permalink
  • Stephen Lemp

    The behavior of @last with objects seems to be the negative of @first. I.e. An object with 3 keys will return true for @last for the 2nd and 3rd key. Is that expected?

    0
    Comment actions Permalink
  • Stephen Lemp

    Hi Stephen, I missed an important note in the documentation: "The first and last steps of iteration are noted via the @first and @last variables when iterating over an array. When iterating over an object only the @first is available."

    The behavior I was seeing was when iterating over an object.

    0
    Comment actions Permalink
  • Courtney Jordan

    Hi Stephen Lemp,

    Thanks for calling our attention to this area for potential confusion. We've added an example and added information on the zero-indexing of arrays to the @first, @last sections. Please let us know if there are other ways we could improve this documentation! 

    0
    Comment actions Permalink
  • Stephen Brandt

    Thanks for the clarification, Stephen Lemp. I was able to reproduce that problem with this simple object, and indeed @last evaluated to true on every inner loop after the first. 

    {
      "tickets": [
        { 
          "charge": "40 mph in a 30 mph zone",
          "fine": "$100",
          "disposition": "guilty"
        }
      ]
    }

    Poking around at handlebars resources online, it seems that iterating through nested objects is not roundly and fully supported. Assuming that you're trying to check @last in order to properly format the JSON in a template, I appealed to a support lead here, who came up with a clever solution: add the comma before printing the array based on the value of @first instead. 

    Your use case is doubtless more complex, but let me know if that's not what you need or if we should look into the problem further. 

    0
    Comment actions Permalink
  • Stephen Lemp

    Stephen Brandt Thank you so much - that's exactly what I needed! I had resorted to getting the number of keys (number_of_keys) with JavaScript and printing the comma if @index != number_of_keys. Your solution is much cleaner and I can get rid of the convoluted JavaScript logic :D. Thanks again! The use case here is actually taking an object and creating a SQL INSERT INTO statement. SQL is picky about the commas, just like JSON though, so essentially the same.

    0
    Comment actions Permalink
  • Dominik Antalík
    • Edited

    Hello Celigo,

    is there a way how to register new custom Handlebars helper?

    I've came to the handlebars engine limitation when I cannot use if helper inside multiply helper.

    I've found workaround for that with custom helper, however I do not know how to register it.

     

    My case:

    when I want to do sum of tax rates but only when tax amount is greater than zero... For instance, you can have four different tax rates in US, however for shipping only two-three of them are applied, but in the payload all four are available so I want to filter out rates with zero amount.

    origin handlebar without conditions:

    {{#if shipping_lines_1.price}}
{{multiply 
(sum shipping_lines_1.tax_lines.[0].rate 
shipping_lines_1.tax_lines.[1].rate 
shipping_lines_1.tax_lines.[2].rate 
shipping_lines_1.tax_lines.[3].rate)
100}}
{{/if}}

     

    part of the payload regarding "shipping_lines":

    {"shipping_lines_1":
{"id": 1111111111,"carrier_identifier": null,"code": "Standard Shipping","delivery_category": null,"discounted_price": "8.90","discounted_price_set": {"shop_money": {"amount": "8.90","currency_code": "USD"},"presentment_money": {"amount": "8.90","currency_code": "USD"}},"phone": null,"price": "8.90","price_set": {"shop_money": {"amount": "8.90","currency_code": "USD"},"presentment_money": {"amount": "8.90","currency_code": "USD"}},"requested_fulfillment_service_id": null,"source": "shopify","title": "Standard Shipping",
    "tax_lines": [
    {"price": 0.09,
    "price_set": {"shop_money": {"amount": "0.09","currency_code": "USD"},"presentment_money": {"amount": "0.09","currency_code": "USD"}},
    "rate": 0.0625,
    "title": "IL STATE TAX"},
    {"price": 0.00,
    "price_set": {"shop_money": {"amount": "0.00","currency_code": "USD"},"presentment_money": {"amount": "0.00","currency_code": "USD"}},
    "rate": 0,
    "title": "IL COUNTY TAX"},
    {"price": 0.00,
    "price_set": {"shop_money": {"amount": "0.00","currency_code": "USD"},"presentment_money": {"amount": "0.00","currency_code": "USD"}},
    "rate": 0.01,
    "title": "IL CITY TAX"},
    {"price": 0.07,
    "price_set": {"shop_money": {"amount": 0.07,"currency_code": "USD"},"presentment_money": {"amount": "0.07","currency_code": "USD"}},
    "rate": 0.0075,
    "title": "IL SPECIAL TAX"}],
    "discount_allocations": []
    }}

     

     

    as you can see the tax code with a name "IL CITY TAX" has rate 0.01 however amount is zero, which leads into miscalculation in the accounting system when imported shipping tax rate is 8% instead of 7%

    So I've added conditions to check tax amount/price at the first place and then do sum of rates when tax amount is greater than zero:

    {{#if shipping_lines_1.price}}
    {{multiply 
    (sum
    ({{#if shipping_lines_1.tax_lines.[0].price}}{{shipping_lines_1.tax_lines.[0].rate}}{{else}}0{{/if}})
     ({{#if shipping_lines_1.tax_lines.[1].price}}{{shipping_lines_1.tax_lines.[1].rate}}{{else}}0{{/if}})
     ({{#if shipping_lines_1.tax_lines.[2].price}}{{shipping_lines_1.tax_lines.[2].rate}}{{else}}0{{/if}})
     ({{#if shipping_lines_1.tax_lines.[3].price}}{{shipping_lines_1.tax_lines.[3].rate}}{{else}}0{{/if}})
    )100
    }}
    {{else}}0{{/if}}

    Unfortunately, I always get an error: " Could not compile handle bar ... Parse error on line 4 ... Expecting 'ID', 'STRING', 'NUMBER', 'BOOLEAN', 'UNDEFINED', 'NULL', 'DATA', got 'OPEN_BLOCK'"

    So I've created custom helper which is easy to use on the page tryhandlebarsjs.com or jsfiddle.com, but not able to use in celigo mapping:

    Handlebars.registerHelper("ifThenElse", function (condition, ifTrue, ifFalse) {
    return condition ? ifTrue : ifFalse;
});

    You would then use the helper in your template as a Handlebars Subexpression, which allows you to nest helpers:

    {{#if shipping_lines_1.price}}
  {{multiply 
    (sum 
      (ifThenElse shipping_lines_1.tax_lines.[0].price shipping_lines_1.tax_lines.[0].rate 0)
      (ifThenElse shipping_lines_1.tax_lines.[1].price shipping_lines_1.tax_lines.[1].rate 0)
      (ifThenElse shipping_lines_1.tax_lines.[2].price shipping_lines_1.tax_lines.[2].rate 0)
      (ifThenElse shipping_lines_1.tax_lines.[3].price shipping_lines_1.tax_lines.[3].rate 0)
    )
    100
  }}
{{/if}}
    0
    Comment actions Permalink

Please sign in to leave a comment.