Handlebars Helpers

This document covers supported handlebars helpers that can be used in a template

SuprSend template editor uses handlebars templating language to add variables and support conditional content rendering in a template. You can find the list of inbuilt handlebars helpers here.

Apart from the inbuilt helper functions, we have also created some custom helper functions which you can use in template editors.

📘

Not supported in SMS and Whatsapp

Since, SMS (in India) and Whatsapp require pre-approved templates to send messages, we can't support conditional content rendering in SMS and Whatsapp templates. You can use handlebars helpers if you are sending SMS in US with vendors like Twilio and Messagebird.


SuprSend Handlebars Helpers

1. default

Can be used to add a default value if the variable values are "", null, undefined

Syntax:
{{default variable "default_value" }}

Example:
{{default name "user" }}

Returns:

  • Variable value if the variable value is present. For instance, the above example with data {"name":"Joe"} will return Joe
  • Default value if variable value is in "", null, undefined. For instance, the above example with data {"name":""}, {"name":null} or {"city":"Bangalore"} will return user

2. compare

Can be used to show some content in the template based on a condition. For email, you can use display condition to show or hide a particular content block

Syntax:

{{#compare name '==' "Mike"}}
true_block
{{else}}
false_block
{{/compare}}

Example:

Example-1: with else statement
{{#compare candidate_count '==' 1}}
is
{{else}}
are
{{/compare}}


Example-2: without else statement
{{#compare candidate_count '==' 1}}
is
{{/compare}}

Returns:

  • Returns true_block if the condition inside compare statement returns truthy value. For instance, the above example with data {"candidate_count":1} will return is
  • Returns false_block (in case else statement is present) if the condition inside compare statement returns falsy value. For instance, Example-1 with data {"candidate_count":3} will return are
  • or Returns no value if the else statement is not present. For instance, Example-2 with data {"candidate_count":3} will not return anything

Supported Conditional operators in compare statement:

OperatorReturns truthy whenSample Statement
'=='LHS equals RHS1 '==' "1"
'==='LHS value as well as data type matches with RHS1 '===' 1
'>'LHS is greater than RHS2 '>' 1
'<'LHS is less than RHS1 '<' 2
'>='LHS is greater than equals to RHS2 '>=' 2 or 3 '>=' 2
'<='LHS is less than equal to RHS2 '<=' 2 or 1 '<=' 2
'!='LHS is not equal RHS3 '!=' 1
'!=='LHS value or data type does not equal RHS1 '!==' "1"

🚧

Handling nested objects in handlebars

Builtin helpers and custom helpers in handlebars can only work with nested objects if the value of parent key is present. For example, {{default place.city "San Francisco"}} will return "San Francisco" only if place key is present, i.e., {"place":[]}

However, you can use the nested if condition to check if the parent is present and if so, then render nested objects value. Refer below example

{{#if place}}
  {{default place.city "San Francisco"}}
{{else}}
  San Francisco
{{/if}}


{{#if person.address}}
  {{#if person.address.current}}
    {{{default person.address.current.city "Los Angeles"}}
  {{/if}}
{{/if}}

3. each

You can iterate over a static or dynamic length list using each helper. Inside the block, you add the array object key which you want to iterate over.

Syntax:

{{#each array_object}}
{{variable_key}}
{{/each}}

Example:

{{#each admins}}
{{name}} 
{{/each}}

Returns:
Above example for below mock data will return steve Olivia

{
  "admins":[
    {
      "name":"steve",
      "id":"1",
      "city":"Palo Alto"
    },
    {
      "name":"Olivia",
      "id":2,
      "city":"Houston"
    }
  ]
}

4. datetime-format

Returns a formatted date string. This helper will throw error if an invalid date is provided.

Syntax:
{{datetime-format variable "format string" "timezone"}}

parameterObligationdescription
variablemandatoryshould be a date or timestamp. It will throw an error for invalid date format.
format stringmandatorydate string defining the format in which date should be printed. See all formatting options here. For example "dddd, MMMM Do YYYY, h:mm:ss a" will return datetime as "Sunday, February 14th 2010, 3:25:50 pm"
timezoneoptionalyou can add timezone as a third parameter to convert time in a given timezone. See the list of all possible timezones here

Examples:

ExampleOutput
{{datetime-format date "ddd, MMM Do YYYY, h:mm:ss a"}}Tue, Sep 26th 2023, 12:00:00 am
{{datetime-format date "[Today is] dddd"}}Today is Tuesday
{{datetime-format date "Do MMMM, YYYY" "America/Chicago"}}25th September, 2023
{
  "date":"2023-09-26T00:00:00Z"
}


5. jsonStringify

Coverts any type of JSON input to a string. Can be used to print JSON and array directly in templates without having to convert it into individual strings. One of the common usecase is to pass complete JSON in Inbox template -> custom JSON field to generate custom UI.

Syntax:
{{jsonStringify variable}}

variable should be a valid JSON input.

Examples:

ExampleOutput
{{jsonStringify this}}'{"likes":3,"comments":4,"users":["Olivia","Steve"]}'
{{jsonStringify users}}'["Olivia","Steve"]'
{
  "likes":3,
  "comments":4,
  "users":["Olivia","Steve"]
}

Math Operators

6. add

Returns the sum of two operands. Both input values should be numbers, else it will throw an error.

Syntax:
{{add number1 number2}}

Examples:

ExampleOutput
{{add 9 4}}13
{{add likes comments}}7
{
  "likes":3,
  "comments":4
}

7. subtract

Returns the difference between two operands. Both input values should be numbers, else it will throw an error.

Syntax:
{{subtract number1 number2}}

Examples:

ExampleOutput
{{subtract 9 4}}5
{{subtract likes 1}}2
{
  "likes":3,
  "comments":4
}

8. multiply

Returns the product of two operands. Both input values should be numbers, else it will throw an error.

Syntax:
{{multiply number1 number2}}

Examples:

ExampleOutput
{{multiply 9 4}}36
{{multiply ARR billing_months}}3600
{
  "ARR":300,
  "billing_months":12
}

9. divide

Returns the quotient of the left operand divided by the right operand. Both input values should be numbers; else it will throw an error.

Syntax:
{{divide dividend divisor}}

Examples:

ExampleOutput
{{divide 14 4}}3.5
{{divide total_bill billing_months}}300
{
  "total_bill":3600,
  "billing_months":12
}

10. round

Returns the value of a number rounded to the nearest integer. The input value should be a number; else it will throw an error.

Syntax:
{{round number}}

Examples:

ExampleOutput
{{round 12.5}}13
{{round (divide 15 4)}}4

11. mod

Returns the remainder left over when one operand is divided by a second operand. It always takes the sign of the dividend. This helper will throw an error if it encounters an input value that is not a number or if the divisor is 0.

Syntax:
{{mod dividend divisor}}

Examples:

ExampleOutput
{{mod 14 4}}2
{{mod total_bill billing_months}}0
{
  "total_bill":3600,
  "billing_months":12
}

Array Operators

12. unique

Returns unique items in an array

Syntax:
{{unique variable "key_string" }}

parameterdescription
variableshould be an array. If not helper function will throw an error.
key_stringmandatory only if items in the array are objects. If a unique operation needs to be performed on nested objects, then object notation (a.b or a['b']) can be used.

Examples:

ExampleOutput
{{unique email }}[email protected], [email protected]
{{unique array "city" }}San Francisco, Austin
{{unique personal_details "name.first_name" }}john, mike
{
  "array": [
    {
      "city": "San Francisco",
      "name": "Mike"
    },
    {
      "city": "Austin",
      "name": "Juliana"
    },
    {
      "city": "Austin",
      "name": "Nova"
    }
  ],
  "personal_details": [
    {
      "name": {
        "first_name": "john",
        "last_name": "doe"
      }
    },
    {
      "name": {
        "first_name": "mike",
        "last_name": "waz"
      }
    }
  ],
  "email": [
    "[email protected]",
    "[email protected]",
    "[email protected]"
  ]
}

13. itemAt

Returns item at a particular index in the array. It can be useful in scenarios where you want to display a message like liked by Mike and 3 others.

Syntax:
{{itemAt variable index }}

ParameterDescription
variableshould be an array else the helper function will throw an error.
indexshould be an integer else the helper function will throw an error.

Examples:

ExampleOutput
{{itemAt email 1}}[email protected]
{
  "array": [
    {
      "city": "San Francisco",
      "name": "Mike"
    },
    {
      "city": "Austin",
      "name": "Juliana"
    },
    {
      "city": "Austin",
      "name": "Nova"
    }
  ],
  "email":["[email protected]","[email protected]","[email protected]"]
}

Note:

This helper only works with an array of primitive data types like string, boolean, etc. If you have an array with objects in it, you can combine it with a unique helper to return the indexed value of a particular key inside the object. For instance, {{itemAt (unique array "city") 0}} in above mock will return San Francisco.


14. join

Concatenates all the values in an array, using a specified separator string between each value.

Syntax:
{{join variable "separator"}}

ParameterDescription
variableshould be an array and items in the array should be of primitive data types like string, number, etc, else the helper function will throw an error.
separatorshould be string else by default separator , will be used. If not provided , is used.

Examples:

{
  "array": [
    {
      "city": "San Francisco",
      "name": "Mike"
    },
    {
      "city": "Austin",
      "name": "Juliana"
    },
    {
      "city": "Austin",
      "name": "Nova"
    }
  ],
  "email":["[email protected]","[email protected]","[email protected]"]
}

Note:

This helper only works with an array of primitive data types like string, boolean, etc. If you have an array with objects in it, you can combine them with a unique helper to join the value of a particular key inside the object. For instance, {{join (unique array "city")}} in above mock will return San Francisco, Austin


15. length

Can be used to get the number of items in an array or the character length of a string. It can be useful in scenarios where you want to display a message like your post has got 100 likes.

Syntax:
{{length variable}}

PropertyDescription
variableshould be an array or string to get the actual count of items in the variable provided, else it returns 0.

Examples:

ExampleOutput
{{length array}}3
{{length name}}6
{{length active}}0
{
  "array": [
    {
      "city": "San Francisco",
      "name": "Mike"
    },
    {
      "city": "Austin",
      "name": "Juliana"
    },
    {
      "city": "Austin",
      "name": "Nova"
    }
  ],
  "email":["[email protected]","[email protected]","[email protected]"],
  "name":"Justin",
  "active":true
}

We are adding further helpers to this list. If you have a use case that is not covered, ping us on slack