Skip to main content

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.

Note

Check out our common use cases documentation on details on how to use these functions. Don't see a custom handlebars helper you need in the list? Share your use case.

Courier Handlebars Helpers

Logic

and

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

Parameters

  • input 0

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}}

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 0

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).

Parameters

  • input 0

Note: Data and profile can have booleans.

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

not

Return false if the argument is truthy. Returns true if argument is false, undefined, null, "", 0, or []

Parameters

  • input

Example

{{not true}}
<!-- Output: false -->

{{not "string"}}
<!-- Output: false -->

{{not "" }}
<!-- Output: true -->

{{not undefined }}
<!-- Output: true -->

or

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

Parameters

  • input 0

Note: Data and profile can have booleans.

{{#if (or (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 (or (var "profile.boolean") (var "profile.another_boolean"))}}
<strong>True</strong>
{{else}}
<strong>False</strong>
{{/if}}

Data

default

Returns the value if it is not nullish.

Parameters

  • input 0

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 0

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.


path

Use the variable handler to resolve a JSONPath, and returns the resolved value, similar to var. Returns undefined if the value was not found.

Parameters

  • input

Example:

{{path "profile.doesNotExist"}}
<!-- Output: -->

{{var "profile.doesNotExist"}}
<!-- Output: {profile.doesNotExist} -->

{{#if (path "profile.doesNotExist")}}
abc123
{{/if}}
<!-- Output: -->

{{#if (var "profile.doesNotExist")}}
abc123
{{/if}}
<!-- Output: abc123 -->

set

Set the value of a variable specified by name. The top level names cannot start with brand, data, event, profile, recipient, urls

Parameters

  • name
  • input

Example:

<!-- Set and re-use a default value-->
{{set "name" (default (path "profile.firstName") "valued_customer" )}}
Dear {{name}},

<!-- Make a variable more readable -->
{{set "city" (path "profile.address.primary.city")}}
{{city}}
<!-- Output: Santa Cruz -->

{{set "month" (datetime-format 1554145200000 "%B")}}
{{month}}
<!-- Output: April-->

var

Uses the variable handler to resolve a JSONPath, and returns the resolved value, similar to path. Returns the variable reference as a string {data.doesNotExist} if the value was not found.

Parameters

  • input

Example:

{{path "profile.doesNotExist"}}
<!-- Output: -->

{{var "profile.doesNotExist"}}
<!-- Output: {profile.doesNotExist} -->

{{#if (path "profile.doesNotExist")}}
abc123
{{/if}}
<!-- Output: -->

{{#if (var "profile.doesNotExist")}}
abc123
{{/if}}
<!-- Output: abc123 -->

with

Note

This helper is a modified version of the Handlebars with helper.

Sets the variable scope when rendering the block content.

Parameters

  • input

Example:

{{#with person}}
{{firstname}} {{lastname}}
{{/with}}
<!-- Output: Marty Banks -->

when run in this context

{
person: {
firstname: "Marty",
lastname: "Banks"
}
}

String

capitalize

Returns the capitalized first character of a given string.

Parameters

  • input

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 0

Example

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

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

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

format

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

Parameters

  • input 0

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 0

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


trim-left

Removes whitespace from the beginning of a string, without modifying the original string.

Parameters

  • input

Example:

{{trim-left "  a string"}}
<!-- Output: a string -->

trim-one-char-right

info

This helper is for dealing with the following escaping issue.

Returns the string with the last character removed.

Parameters

  • input

Example:

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

trim-right

Removes whitespace from the end of a string, without modifying the original string.

Parameters

  • input

Example:

{{trim-right "a string  "}}
<!-- Output: a string -->

trim

Removes whitespace from the beginning and end of a string, without modifying the original string.

Parameters

  • input

Example:

{{trim "  a string  "}}
<!-- Output: a string -->

truncate

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

Parameters

  • input
  • length
  • (optional) suffix

Example:

{{ truncate "some very long string" 9 }}
<!-- Output: some very -->

{{ truncate "some very long string" 9 "..." }}
<!-- Output: some very... -->

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

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
  • term

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

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
  • divisor

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

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")}}

inc

Increase value by 1.

Parameters

  • input

Example:

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

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
  • divisor

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
  • multiplicand

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

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
  • term

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 0

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 -->

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

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

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
  • args (multiple, space separated arguments)
  • domain (only scoped to "default" right now)
  • locale (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" -->