/
What are Handlebar Helpers?

What are Handlebar Helpers?

Owned by Jack Friend
Last updated: Sept 01, 2022 by Rebecca Kornblum
10 min read

This document covers the addition of new custom Handlebar Helpers as well as existing ones built into the Handlebar itself. These helpers can be used within inTouch email templates to build in custom logic based on application data.

 

Arithmetic

All arithmetic helpers will be in the form of:

  • {{ HelperName Value1 Value2 #OfDecimalPlaces }}

    • HelperName (Required) is the arithmetic helper name: add, subtract, multiply, divide

    • Value1 (Required) can either be an explicit value or a token that represents a number/decimal field in our system.

    • Value2 (Required) can either be an explicit value or a token that represents a number/decimal field in our system.

    • #OfDecimalPlaces  (Optional) number of decimal places result will have if the result is a decimal.

      • Default number of decimal places is 0.

      • Maximum number of decimal places is 5. If a number greater than 5 is entered, the system will default to 5.

 

Addition

  • Special cases: (see examples below)

    • A number is being added with a percentage (e.g., {{ add “2%” 2 }})

      • Will get the sum of the number with its percentage (see examples below)

    • A number is being added with a currency  (e.g., {{ add 2 “$12” }}

      • Will get the sum of the two values and return a currency

  • Examples

    • Two constants

      • {{ add 1 2 }} => 3

      • {{ add 1.3 2.5 }} => 4

      • {{ add 1.3 2 2 }} => 3.30

      • {{ add “2%” 2 2 }} => 2.04

      • {{ add 4 “$12.56” 2}} => $16.56

    • inTouch Token

      • [Purchase Amount] = $100, [Sell Amount] = $200, [APR] = 5%

      • {{ add [Purchase Amount] 200 }} => $300

      • {{ add 100 [Sell Amount] }} => $300

      • {{ add [Purchase Amount] [Sell Amount] }} => $300

      • {{ add [Sell Amount] [APR] }} => $210

      • {{ add [APR] 3 2}} => 3.15

      • {{ add [APR] [APR] }} => 6%

 

Subtraction

  • Special cases

    • A number is being subtracted by a percentage (e.g., {{ subtract “2%” 2 }})

      • Will get the difference of the number with its percentage (see examples below)

    • A number is being subtracted with a currency  (e.g., {{ add 2 “$12” }}

      • Will get the difference of the two values and return a currency

  • Examples

    • Two constants

      • {{ subtract 2 1 }} => 1

      • {{ subtract 2.5 1.3 }} => 1

      • {{ subtract 1.3 2 2 }} => -.70

      • {{ subtract “2%” 2 2 }} => -1.96

      • {{ subtract “$12.56” 4 2}} => $8.56

    • inTouch Token

      • [Purchase Amount] = $100, [Sell Amount] = $200, [APR] = 5%

      • {{ subtract [Purchase Amount] 50 }} => $50

      • {{ subtract 100 [Sell Amount] }} => -$100

      • {{ subtract [Purchase Amount] [Sell Amount] }} => -$100

      • {{ subtract [Sell Amount] [APR] }} => $190

      • {{ subtract [APR] 3 2}} => -2.85

      • {{ subtract [APR] [APR] }} => 0%

 

Multiplication

  • Format: {{ multiply Value1 Value2 #OfDecimalPlaces}}

  • Special cases

    • A number is being multiplied by a percentage (e.g., {{ multiply “2%” 2 }})

      • Result will be the percentage of the value being multiplied (see examples below)

  • Examples

    • Two constants

      • {{ multiply 2 1 }} => 2

      • {{ multiply 2.5 1.3 }} => 3

      • {{ multiply 1.3 2 2 }} => 2.60

      • {{ multiply “2%” 2 2 }} => .04

      • {{ multiply “$12.56” 4 2}} => $50.24

    • inTouch Token

      • [Purchase Amount] = $100, [Sell Amount] = $200, [APR] = 5%

      • {{ multiply [Purchase Amount] 50 }} => $5000

      • {{ multiply 100 [Sell Amount] }} => $20000

      • {{ multiply [Purchase Amount] [Sell Amount] }} => $20000

      • {{ multiply [Sell Amount] [APR] }} => $10

      • {{ multiply [APR] 3 2}} => .15

      • {{ multiply [APR] [APR] }} => 25%

 

Division

  • Format: {{ divide Value1 Value2 #OfDecimalPlaces}}

  • Special cases

    • A number is being multiplied by a percentage (e.g., {{ divide “2%” 2 }})

      • Result will be the (see examples below)

  • Examples

    • Two constants

      • {{ divide 2 1 }} => 2

      • {{ divide 2.5 1.3 }} => 2

      • {{ divide 1.3 2 2 }} => .65

      • {{ divide “2%” 2 2 }} => 1%

      • {{ divide “$12.56” 4 2}} => $3.14

    • inTouch Token

      • [Purchase Amount] = $100, [Sell Amount] = $200, [APR] = 5%

      • {{ divide [Purchase Amount] 50 }} => $2

      • {{ divide 100 [Sell Amount] 1 }} => $.5

      • {{ divide [Sell Amount] [Purchase Amount] }} => $2

      • {{ divide [Sell Amount] [APR] }} => $4000

      • {{ divide [APR] 3 2}} => 1.67%

      • {{ divide [APR] [APR] }} => 1%

 

Comparisons

This helper does comparisons on numeric values.

  • Usage: Create an “eq” helper

  • Format: eq(string left, string right)

  • Logic:

    • Attempt to convert each input into numeric.

    • If a string is not convertible to numeric, then ignore.

    • If any value cannot be converted to numeric then evaluation is always false.

  • Samples

    • eq(“100”, ““) => false

    • eq(null) => false

    • eq(null, ““) => false

    • eq(“100”, 100) => true

    • eq(101, “100”) => false

    • eq(100, “101”) => false

 

  • Usage: Create an “lt” helper

  • Format: lt(string left, string right)

  • Logic

    • Attempt to convert each input into numeric.

    • If a string is not convertible to numeric, then ignore.

    • If any value cannot be converted to numeric then evaluation is always false.

  • Samples

    • lt(“100”, ““) => false

    • lt(null) => false

    • lt(null, ““) => false

    • lt(“100”, 100) => false

    • lt(101, “100”) => false

    • lt(100, “101”) => true

 

  • Usage: Create an “lteq” helper

  • Format: lteq(string left, string right)

  • Logic

    • Attempt to convert each input into numeric.

    • If a string is not convertible to numeric, then ignore.

    • If any value cannot be converted to numeric then evaluation is always false.

  • Samples

    • lteq(“100”, ““) => false

    • lteq(null) => false

    • lteq(null, ““) => false

    • lteq(“100”, 100) => true

    • lteq(101, “100”) => false

    • lteq(100, “101”) => true

 

  • Usage: Create a “gt” helper

  • Format: gt(string left, string right)

  • Logic

    • Attempt to convert each input into numeric.

    • If a string is not convertible to numeric, then ignore.

    • If any value cannot be converted to numeric then evaluation is always false.

  • Samples

    • gt(“100”, ““) => false

    • gt(null) => false

    • gt(null, ““) => false

    • gt(“100”, 100) => false

    • gt(101, “100”) => true

    • gt(100, “101”) => false

 

  • Usage: Create a “gteq” helper

  • Format: gteq(string left, string right)

  • Logic

    • Attempt to convert each input into numeric.

    • If a string is not convertible to numeric, then ignore.

    • If any value cannot be converted to numeric then evaluation is always false.

  • Samples

    • gteq(“100”, ““) => false

    • gteq(null) => false

    • gteq(null, ““) => false

    • gteq(“100”, 100) => true

    • gteq(101, “100”) => true

    • gteq(100, “101”) => false

 

String

All string helpers will be in the form of:

  • {{ HelperName Value1 Value2 ComparisonBoolean }}

    • HelperName (Required) is the string-helper name: IsEqual, StringSplit

    • Value1 (Required) can either be an explicit value or a token that represents a string field in our system.

    • Value2 (Required) can either be an explicit value or a token that represents a string field in our system.

    • ComparisonBoolean (Optional) Enable or disable a certain feature with a value or token that represents a string field in our system: 

      • Default argument is true.

      • Can enter “true” or “false”.

 

IsEqual

  • Format: {{ is-equal Value1 Value2 ComparisonBoolean }}

  • Special cases

    • Comparing two strings are equal, allowing case sensitivity.

  • Examples

    • Defaults to not case-sensitive

      • {{ is-equal “foo” “foo” }} => true

      • {{ is-equal “foo” “Foo” }} => true

    • Optional explicit argument on disabling case-sensitive

      • {{ is-equal “foo” “Foo” true }} => true

      • {{ is-equal “foo” “Foo” false }} => false

    • Handling null arguments

      • {{ is-equal “foo” null true }} => false

      • {{ is-equal “foo” null false }} => false

      • {{ is-equal “foo” null }} => false

 

StringSplit

  • Format: {{ string-split Value1 Value2 }}

  • Examples

    • Splitting a string via a certain character.

      • {{ string-split ‘Who let the dogs out?’ ‘o’ }} => “Wh”

      • {{ string-split ‘Who let the dogs out?’ ‘t’ }} => “Who le”

      • {{ string-split ‘InsellerateX’ ‘X’ }} => “Insellerate”

    • Retrieving the n-th string split.

      • {{ string-split ‘InsellerateX’ ‘X’ 0 }} => “Insellerate” because indexing starts at 0.

      • {{ string-split ‘InsellerateX’ ‘X’ 1 }} => “” because there is exactly 1 instance of X.

      • {{ string-split ‘Who let the dogs out?’ ‘o’ 0 }} => “Wh”

      • {{ string-split ‘Who let the dogs out?’ ‘o’ 1 }} => “ let the d”

      • {{ string-split ‘Who let the dogs out?’ ‘o’ 2 }} => “ gs ”

 

Contains a String

  • Format: contains-string(string source, string search, bool isCaseSensitive=false)

  • Examples

    • contains-string(null, “something”) => false

    • contains-string(“something”, null) => false

    • contains-string(“something”, “something”) => true

    • contains-string({{some token}}, {{some other token}}) => if {{some other token}} exists in {{some token}} then true else false

    • contains-string(“something”, “Something”) => true

    • contains-string(“something”, “Something”, “true”) => false

 

Contains an Item

  • Format: contains-item (object item, bool is CaseSensitive, object[] collection)

  • Examples

    • contains-item(null, ‘false’, “1”, “2”, “3”) => false

    • contains-item(null, ‘false’, null) => false

    • contains-item(null 'false', “1”) => false

    • contains-item(“1”, ‘false’, “1”, “2”, “3”) => true

    • contains-item({{some token}}, 'false', [“1”, “2”, “3”], {{some token}}) => if token exists in collection then true else false

    • contains-item(“A”, ‘true’, “a“, “b“, “c“) => false since case sensitivity is set to true.

 

Lookup

All lookup helpers will be in the form of:

  • {{ HelperName Value1 Value2 DefaultValue }}

    • HelperName (Required) is the lookup-helper name: LookupHelper, MultiLookupHelper

    • Value1 (Required) The dictionary containing the key-value pairs.

    • Value2 (Required) A lookup Id that maps to system values (e.g., lookup id for loan-purpose type to loan-purpose type).

    • DefaultValue (Optional) The default value that gets returned in the case at 3 or more arguments are passed, but Value2 is an invalid lookup ID.

  • Format: {{ lookup DictionaryInstance LookupValue DefaultValue }}

  • Examples:

    • Standard lookup

      • Assume the lookup-ID key for loan-purpose type is “1234.” Then
        {{ lookup [JSON dictionary instance] “1234” }} => loan-purpose type

    • Default-value lookup

      • Assume “0000” is an invalid lookup ID. Then
        {{ lookup [JSON dictionary instance] “0000” “loan-officer name” }} => loan-officer name

 

Dates

Date Format

  • Format: {{ format-date Date FormatString TimeZoneId }}

  • Examples

    • An explicit date

      • {{ format-date “11/29/2001 20:20:20” “dd MMM HH:mm:ss” }} => 29 Nov 20:20:20

      • {{ format-date “11/29/2001 20:20:20” “dd MMM HH:mm:ss” “Pacific Standard Time” }} => 29 Nov 20:20:20

    • inTouch Token

      • [Purchase Date] = “11/29/2001 20:20:20”

      • {{ format-date [Purchase Date] “dd-MM-yy” }} => 11-29-01

      • {{ format-date [Purchase Date] “D” }} => Thursday, November 29, 2001

 

Current Date

  • Usage: {{ current-date }}

    • No parameters are required, it will return current date in UTC

  • Examples

    • {{current-date}} => “10/26/2021 3:39:16 PM” 

 

Add Date

  • Usage: {{ dateadd }} (Datetime datetime, int increment, string interval)

  • Supported Interval

    • millisecond, ms

    • second, ss, s

    • minute, mi, n, m

    • hour, hh, h,

    • day, dd, d

    • month, mm

    • year, yyyy, yy, y

 

Date Differences

This helper will calculate date differences.

  • Difference Types

    • year

    • month

    • dayofyear

    • day

    • week

    • hour

    • minute

    • second

    • millisecond

  • Edge Cases

    • For a return value out of range for int (-2,147,483,648 to +2,147,483,647), DATEDIFF returns the min value for int.

    • If only a time value is assigned to a date data type variable, DATEDIFF sets the value of the missing date part to the current date.

 

If Else Conditionals

  • Format: {{#if condition1}} resultIfCondition1 {{else}} resultOtherwise {{/if}}

    • {{#if condition1}} (Required)

    • {{/if}} (Required)

    • {{else}} (Optional)

    • If statements must start with an {{#if}} and end in {{/if}}. Multiple If else statements can be nested:

{{#if condition1 }}

result1

{{else}}

{{#if condition2}}

result2

{{/if}}

{{/if}}

Or

{{#if condition1 }} result1 {{else}} {{#if condition2}} result2 {{/if}} {{/if}}

  • Examples

    • Constants

      • {{#if true}} “Hello” {{/if}} => “Hello”

      • {{#if false}} “Hello” {{/if}} => null

      • {{#if false}} “Hello” {{else}} “GoodBye” {{/if}} => “GoodBye”

    • inTouch Token

      • [Is First Home Buyer] = true, [Custom 1] = “Congratulations First Home Buyer!”, [Custom 2] = “Congratulations!”

      • {{#if [Is First Home Buyer]}} {{[Custom 1]}} {{else}} {{[Custom 2]}} {{/if}} => “Congratulations First Home Buyer!”

 

Formatters

This formatter helper is Currency, used to format numeric values to currency with some optional parameters.

Currency

Currency helper uses the format from C# Custom numeric format strings | Microsoft Docs

  • Usage: {{ format-currency value optionalParameters}}

    • format-currency (Required) is the helper name

    • Value (Required): value string to format to currency,  Parameter must be in single or double quotes if contains spaces

    • format (Optional): format to apply, Parameter must be in single or double quotes, by default 0,0.00 reference https://docs.microsoft.com/en-us/dotnet/standard/base-types/custom-numeric-format-strings                

    • prefix: prefix to apply, Parameter must be in single or double quotes, defaults to $

    • suffix: suffix to apply, Parameter must be in single or double quotes, defaults to empty string

  • Samples

    • Value = 1518.53

    • {{ format-currency Value }} => $1,518.53

    • {{ format-currency Value '0' }} => $1519

    • {{ format-currency Value '0.0' }} => $1518.5

    • {{ format-currency Value '0.00' }} => $1518.53

    • {{ format-currency Value '0,0' }} => $1,519

    • {{ format-currency value '0,0.00'  '#' }} => #1,518.53

    • {{ format-currency value '0,0.00'  '#'  'USD' }} => #1,518.53USD

 

Percentage

This helper will format any numeric value to its percentage representation in string.

  • Format: {{ format-percent value rule }}

    • format-percent (Required): is the helper name

    • value (Required): value in string to format into percentage representation

    • rule (Optional): defines the formatting output that is going to be applied to the value. There are three main outputs depending on the following rules. Taking this as an input: 10.1993%

      1. NULL/Empty (no defined rule) => will default with two decimals rounded => 10.20%

      2. 0.#T (1 decimal truncated) => will truncate the value using one decimal => 10.1%

      3. 0.#R (1 decimal rounded) => will round the value using one decimal => 10.2%

  • The number of #s after the '0'. defines the number of decimals to use for the rounded/truncate operations. Meaning that for 10.6789%

    • with 0.###T will output => 10.678%

    • with 0.###R will output => 10.679%

  • Examples

    • value = 10.56789

    • Test Default Rule: {{format-percent value}} => 10.58%

    • Test Rounded Rule One Decimal: {{format-percent value "0.#R"}} => 10.6%

    • Test Rounded Rule Two Decimals: {{format-percent value "0.##R"}} => 10.58%

    • Test truncate Rule One Decimal: {{format-percent value "0.#T"}} => 10.5%

    • Test truncate Rule Two Decimals: {{format-percent value "0.##T"}} => 10.56%

    • Test Default Rule With Sign: {{format-percent value%}} => 10.58%

 

Concatenate Variables

Usage: Take a collection of input strings or tokens and concatenate them.

  • Sample: Token1 = 'd'

    • concat('a', ‘b') => ab

    • concat(“a”, “b”) => ab

    • concat('a ‘, Token1, Token1, ' b’) => a dd b

    • concat('a') => a

    • concat(null, 'a', Token1) => ad

 

Replace Characters

Replace common characters or strings.

  • Usage: replace ( string source, string search, string replace, boolean isCaseSensitive=false )

  • Method logic

    • If any of the required parameters are null then return the empty string
      i.e., {{ replace null, “a” “b” }} => ““

    • If there are any matches in the source from the search then replace all occurrences of the search string
      i.e., {{ replace “abcda” “a” “z” }} => “zbcdz”

    • Support nested evaluations
      i.e., {{ replace ( replace “abcda” “a” “z” ) “b”, “d” }} => “zdcdz”

    • Get token binding to work where ever it is defined
      i.e., see tokenBindingTestTemplate.png and tokenBindingTestEmail.png

 

Sentence Case Structure

Properly format the casing of words.

  • Usage: take a string where the first letter of each word is capitalized following the rule of “Title Casing”

  • Sample

    • title-case(today IS a GOOD dAy) => Today is a Good Day

    • title-case(the goat and the goose) => The Goat and the Goose

    • title-case(a pumpkin and a carrot) => A Pumpkin and a Carrot)

    • title-case({{some token}} => {{some token}} is title case form

 

 

Related content