Handlebars Helpers

Courier's custom Handlebars helpers for use in email template overrides and custom brand templates.

The default Handlebars helpers can be found here.

Courier Handlebars Helpers

Don't see a custom handlebars helper you need in the list? Share your use case.

Universal Helpers

and

Returns true if all arguments are truthy, false if one argument is falsy, and true if no arguments

Parameters

input {String|Number }

Note: Data and profile can have booleans.

Example:

{{#if (and (var "boolean") (var "another_boolean"))}}
  <strong>True</strong>
{{else}}
  <strong>False</strong>
{{/if}}
<!-- Output: dependent on variables, 'true' will render if condition returns true -->

<!-- Reference a "profile" variable -->
{{#if (and (var "profile.boolean") (var "profile.another_boolean"))}}
  <strong>True</strong>
{{else}}
  <strong>False</strong>
{{/if}}

capitalize

Returns the capitalized first character of a given string.

Parameters

input {string}

Example

{{capitalize "foo"}}
<!-- Output: Foo -->

<!-- Reference a "data" variable -->
{{capitalize (var "name")}}

<!-- Reference a "profile" variable -->
{{capitalize (var "profile.name")}}

concat

Stringifies all arguments and joins them using the provided separator. Should use null string for the separator by default and should return a null string if no arguments.

Parameters

input {String|Number}

Example

{{concat "hello" " " "world"}}
<!-- Output: hello world -->

<!-- Reference a "data" variable -->
{{concat "hello" " " (var "name")}}

<!-- Reference a "profile" variable -->
{{concat "hello" " " (var "profile.name")}}

condition

Use the if statement to specify a block of code to be executed if a condition is true. Will throw an error if the operator is unsupported.

Require two operands separated by an operator.
Run the appropriate operation on the operands.

Parameters

input {String|Number}

Note: Data and profile can have booleans.

Example:

{{#if (condition (var "eligible") "==" "yes")}}
  <strong>Hello!</strong>
{{else}}
  <strong>Bye</strong>
{{/if}}
<!-- Output: dependent on variable -->

<!-- Reference a "profile" variable -->
{{#if (condition (var "profile.name") "==" "rod")}}
  <strong>Hello {{var "profile.name"}}!</strong>
{{else}}
  <strong>Hello there</strong>
{{/if}}

<!-- Reference a boolean -->
{{#if (condition (var "profile.hungry") "==" "true")}}
  <strong>{{var "profile.name"}} is hungry!</strong>
{{else}}
  <strong>{{var "profile.name"}} is not hungry</strong>
{{/if}}

conditional

Loops through all arguments and ensures all are truthy if using the "and" logical operator.
Loops through all arguments and ensures one is truthy if using the "or" logical operator.
Returns true if the conditions passed, false otherwise (use #unless helper to hide content if condition passes).
input {String|Number}

Note: Data and profile can have booleans.

{{conditional
  (filter "data" "customer.name" "EQUALS" "josh")
  (filter "profile" "email" "CONTAINS" "@trycourier.com")
}}
<!-- Output: dependent on variable -->

default

Returns the value if it is not nullish.

Parameters

input {String|Number}

Note: Data and profile can have booleans.

Example:

{{default undefined (var "customer")}}
<!-- Output: Returns the default value -->

each

Iterates over a list. Inside the block, you can use this to reference the element being iterated over.

Parameters

input {String|Number}

Example:

"data": {
    "people": [
      {
        "name": "Rod"
      },
      {
        "name": "TK"
      },
      {
        "name": "Suhas"
      }
    ]
  }

<ul>
  {{#each people}}
    <li>{{this.name}}</li>
  {{/each}}
</ul>
<!-- Output: unordered list -->

Note

This is a modified version of this Handlebars helper.

format

Returns a formatted string given a format and set of arguments.

Parameters

input {String | Number}

Example:

{{format "%.2f" (var "number")}}
<!-- If number = 1 | Output: 1.00 -->

datetime-format

Returns a formatted date string, can be set to a user IANA Timezone This helper will throw if an invalid date is provided.

Parameters

input {String|Number}

Examples

{{datetime-format 1554145200000 "%a, %B %d %I:%M %p"}}
<!-- Output: Mon, April 01 7:00 pm-->

{{datetime-format 1554145200000 "%a, %B %d %I:%M %p" "America/Los_Angeles"}}
<!-- Output: Mon, April 01 12:00 pm-->

{{datetime-format "2019-04-01T12:00:00.000Z" "%a, %B %d %I:%M %p"}}
<!-- Output: Mon, April 01 12:00 pm-->

{{datetime-format "2019-04-01T12:00:00.000Z" "%a, %B %d %I:%M %p" "America/Los_Angeles"}}
<!-- Output: Mon, April 01 5:00 am-->

info

See full list of format options along with an additional option %p to add am, pm

inc

Increase value by 1.

Parameters

input {Number}

Example:

{{inc (var "value")}}
<!-- If value = 1 | Output: 2 -->

not

Usage:

{{#if (and (not false) true)}}

Should:

Return a boolean inverse of the value.

or

Usage:

{{#if (or true false)}}

Should:

Return true if one argument is truthy.
Return false if all argument are falsy.
Return false if no arguments.

path

Usage:

{{#if (path "customer.email")}}

Should:

Use the variable handler to resolve a JSONPath.
Return the resolved value.
Return undefined if the value was not found.

set

Usage:

{{set "name" (default first_name "valued customer")}}

Should:

Set a value on the root data using the name.
Set the value on the root of the variable handler context.
Restrict top level names (ex: data, profile, brand).

trim-left

Usage:

{{#trim-left}} test {{/trim-left}}
{{trim-left " a string "}}

Should:

Return the value trimmed (defaults to block value).

trim-one-char-right

Usage:

{{a-block (params text=(trim-one-char-right "ends with\ "))}}

Should:

Return the string with the last character removed.

info

This helper is for dealing with the following escaping issue.

trim-right

Usage:

{{#trim-right}} test {{/trim-right}}
{{trim-right " a string "}}

Should:

Return the value trimmed (defaults to block value).

trim

Usage:

{{#trim}} test {{/trim}}
{{trim " a string "}}

Should:

Return the value trimmed (defaults to block value)

truncate

Usage:

{{ truncate "some very long string" 9 }} => "some very"
{{ truncate "some very long string" 9 "..." }} => "some very..."

Should:

Truncate the string to the number of characters defined in the helper

var

Usage:

"{{var customer.fullName}}" <{{var "customer.email"}}>

Should:

Use the variable handler to resolve a JSONPath.
Return the resolved value as a string.
Not be a SafeString so the value will be encoded.

with

Usage:

{{with customers}}

Should:

Match the Handlebars built-in #with helper.
Set the @variableHandler scope when rendering the block content.

Note

modified version of this Handlebars helper.

Math

abs

Return the magnitude of a number. This helper will throw an errow if it encounters a value that is not a number.

Parameters

input {Number}

Example

{{abs -10}}
<!-- Output: 10 -->

<!-- Reference a "data" variable -->
{{abs (var "negative_number")}}

<!-- Reference a "profile" variable -->
{{abs (var "profile.negative_number")}}

add

Returns the the sum of two operands. This helper will throw an error if it encounters an input value that is not a number.

Parameters

term {Number}
term {Number}

Example

{{add 5 3}}
<!-- Output: 8 -->

{{add -1 -3}}
<!-- Output: -4 -->

<!-- Reference a "data" variable -->
{{add (var "term_1") (var "term_2")}}

<!-- Reference a "profile" variable -->
{{add (var "profile.term_1") (var "profile.term_2")}}

ceil

Returns the least integer greater than or equal to the decimal number input. This helper will throw an errow if it encounters a value that is not a number.

Parameters

input {Number}

Example

{{ceil .95}}
<!-- Output: 1 -->

{{ceil 1.01}}
<!-- Output: 2 -->

{{ceil -1.01}}
<!-- Output: -1 -->

<!-- Reference a "data" variable -->
{{ceil (var "some_number")}}

<!-- Reference a "profile" variable -->
{{ceil (var "profile.some_number")}}

divide

Returns the quotient of its operands where the left operand is the dividend and the right operand is the divisor. This helper will throw an errow if it encounters an input value that is not a number or if the divisor is 0.

Parameters

dividend {Number}
divisor {Number}

Example

{{divide 12 2}}
<!-- Output: 6 -->

{{divide 3 2}}
<!-- Output: 1.5 -->

<!-- Reference a "data" variable -->
{{divide (var "dividend") (var "divisor")}}

<!-- Reference a "profile" variable -->
{{divide (var "profile.dividend") (var "profile.divisor")}}

floor

Returns the largest integer less than or equal to a given number. This helper will throw an errow if it encounters a value that is not a number.

Parameters

input {Number}

Example

{{floor .95}}
<!-- Output: 0 -->

{{floor 1.01}}
<!-- Output: 1 -->

{{floor -1.01}}
<!-- Output: -2 -->

<!-- Reference a "data" variable -->
{{floor (var "some_number")}}

<!-- Reference a "profile" variable -->
{{floor (var "profile.some_number")}}

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 errow if it encounters an input value that is not a number or if the divisor is 0.

Parameters

dividend {Number}
divisor {Number}

Usage:

Example

{{mod 13 5}}
<!-- Output: 3 -->

{{mod -13 5}}
<!-- Output: -3 -->

{{mod 4 2}}
<!-- Output: 0 -->

<!-- Reference a "data" variable -->
{{mod (var "dividend") (var "divisor)}}

<!-- Reference a "profile" variable -->
{{mod (var "profile.dividend") (var "profile.divisor)}}

multiply

Returns the product of two operands. This helper will throw an errow if it encounters an input value that is not a number.

Parameters

multiplier {Number}
multiplicand {Number}

Example

{{multiply 12 2}}
<!-- Output: 24 -->

{{multiply -12 2}}
<!-- Output: -24 -->

<!-- Reference a "data" variable -->
{{multiply (var "multiplier") (var "multiplicand")}}

<!-- Reference a "profile" variable -->
{{multiply (var "profile.multiplier") (var "profile.multiplicand")}}

round

Returns the value of a number rounded to the nearest integer. This helper will throw an errow if it encounters an input value that is not a number.

Parameters

input {Number}

Example

{{round 1.5}}
<!-- Output: 2 -->

{{round 1.4}}
<!-- Output: 1 -->

{{round -1.4}}
<!-- Output: -1 -->

{{round -1.5}}
<!-- Output: -2 -->

<!-- Reference a "data" variable -->
{{round (var "some_variable")}}

<!-- Reference a "profile" variable -->
{{round (var "profile.some_variable")}}

subtract (sub)

Returns the difference of two operands. This helper will throw an errow if it encounters an input value that is not a number.

Parameters

term {Number}
term {Number}

Example

{{subtract 5 3}}
<!-- Output: 2 -->

{{sub 5 3}}
<!-- Output: 2 -->

{{subtract 3.5 5}}
<!-- Output: -1.5 -->

<!-- Reference a "data" variable -->
{{subtract (var "term_1") (var "term_2")}}

<!-- Reference a "profile" variable -->
{{subtract (var "profile.term_1") (var "profile.term_2")}}

SendWithUs Helpers

SendWithUs helpers are available to help ease migration from your existing Jinja templates to Courier rendered messages.

swu_datetimeformat

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

Parameters

input {String|Number}

Examples

{{swu_datetimeformat 1554145200000 "%a, %B %d"}}
<!-- Output: Mon, April 01 -->

{{swu_datetimeformat "2019-04-01T12:00:00.000Z" "%a, %B %d"}}
<!-- Output: Mon, April 01 -->

info

See full list of format options

swu_iso8601_to_time

Returns an ISO-8601 date string as epoch milliseconds. This helper will throw if an invalid date is provided.

Parameters

input {String}

Examples

{{swu_iso8601_to_time "2019-04-01T12:00:00.000Z"}}
<!-- Output: 1554145200000 -->

<!-- Reference a "data" variable -->
{{swu_iso8601_to_time (var "some_date_variable")}}

<!-- Reference a "profile" variable -->
{{swu_iso8601_to_time (var "profile.some_date_variable")}}

swu_timestamp_to_time

Returns an Unix epoch timestamp (seconds) as a millisecond epoch time value. This helper will throw if an invalid unix epoch date is not provided.

Parameters

input {Number}

Examples

{{swu_timestamp_to_time 1554145200}}
<!-- Output: 1554145200000 -->

<!-- Reference a "data" variable -->
{{swu_timestamp_to_time (var "some_timestamp")}}

<!-- Reference a "profile" variable -->
{{swu_timestamp_to_time (var "profile.some_timestamp")}}

translate

Translates a string based on the key, profile locale and .po translations you have uploaded to Courier.

Parameters

key {String}
args {String} (multiple, space separated arguments)
domain {String} (only scoped to "default" right now)
locale {String} (fetched automatically from profile right now)

Examples

{{t "Salutation"}}
<!-- Output: "Welcome" -->

<!-- Pass profile attributes as arguments -->
{{t "Salutation" profile.first_name profile.last_name}}
<!-- Output: "Welcome, John Doe" -->

Common use-cases

Conditionally rendering content

#if blocks can be used to control whether content is rendered.

Example

<!-- equal -->
{{#if (condition (var "some_variable") "==" "show")}}
  <mj-text align="center">Hello!</mj-text>
{{/if}}

<!-- strict equal -->
{{#if (condition (var "some_variable") "===" "show")}}
  <mj-text align="center">Hello!</mj-text>
{{/if}}

<!-- not equal -->
{{#if (condition (var "some_variable") "!=" "hide")}}
  <mj-text align="center">Hello!</mj-text>
{{/if}}

<!-- greater than -->
{{#if (condition (var "some_array.length") ">" 0)}}
  <mj-text align="center">Hello!</mj-text>
{{/if}}

<!-- greater than or equal -->
{{#if (condition (var "some_array.length") ">=" 0)}}
  <mj-text align="center">Hello!</mj-text>
{{/if}}

<!-- less than -->
{{#if (condition (var "some_array.length") "<" 0)}}
  <mj-text align="center">Hello!</mj-text>
{{/if}}

<!-- less than or equal -->
{{#if (condition (var "some_array.length") "<=" 0)}}
  <mj-text align="center">Hello!</mj-text>
{{/if}}

Pluralizing Text

The formatMessage helper can be used to pluralize text in rendered content. Pluralization respects the ICU format and entries follow Unicode CLDR rules.

Example

Your list contains
{{formatMessage
  "{itemCount, plural,
    =0 {no items}
    one {# item}
    other {# items}
}"
  itemCount=itemCount
}}.

Courier Handlebars Helpers​

Universal Helpers​

and​

capitalize​

concat​

condition​

conditional​

default​

each​

Note

format​

datetime-format​

info

inc​

not​

or​

path​

set​

trim-left​

trim-one-char-right​

info

trim-right​

trim​

truncate​

var​

with​

Note

Math​

abs​

add​

ceil​

divide​

floor​

mod​

multiply​

round​

subtract (sub)​

SendWithUs Helpers​

swu_datetimeformat​

info

swu_iso8601_to_time​

swu_timestamp_to_time​

translate​

Common use-cases​

Conditionally rendering content​

Pluralizing Text​

Courier Handlebars Helpers

Universal Helpers

and

capitalize

concat

condition

conditional

default

each

format

datetime-format

inc

not

or

path

set

trim-left

trim-one-char-right

trim-right

trim

truncate

var

with

Math

abs

add

ceil

divide

floor

mod

multiply

round

subtract (sub)

SendWithUs Helpers

swu_datetimeformat

swu_iso8601_to_time

swu_timestamp_to_time

translate

Common use-cases

Conditionally rendering content

Pluralizing Text