Formatting Functions

Formatting functions are used to display data in your preferred output or to correct values e.g displaying dates in a particular format or removing whitespaces.

Date Formatting

To format dates on CrossEngage, you should use the computeDate function. The syntax of this function is:

{{computeDate '{
"dateTrait": [User attribute],
"timePhrase": [Time phrase],
"outputFormat": [Output format]
}'
}}

Note that despite the fact that the computeDate function can alter how dates are displayed, the format in which dates are sent to CrossEngage must remain the same. For further information, check our documentation: https://docs.crossengage.io/user-management/v1

Property

Type

Description

dateTrait

string

Optional. The user attribute containing the value that is used for date formatting and calculations. If omitted, the value now is used. In this context now represents the date and time when the message is rendered and dispatched e.g. user.[traits.birthday].

timePhrase

string

Required. The operation that is executed on the dateTrait e.g. +1 hour, +2 days. This attribute is required even if you wish to display the current date: to do so, simply set the time phrase equal to 0.

outputFormat

string

Required. The format the function should output. All common date formats are supported e.g. yyyy-MM-dd, dd/MM/yy.

Use Cases

Displaying the date 10 days from now

For this example, we output the date 10 days from now(omitting the dateTrait property). We use 2018-06-10 for the example calculation below.

{{computeDate '{
"timePhrase": "+ 10 days",
"outputFormat": "yyyy-MM-dd"
}'
}}

Once the function is evaluated, it displays the date 2018-06-20 in the section where it is used in the message.

Note that the inclusion of a time-phrase is necessary, even if we wish to output the current date. Thus, to display the current date, simply set the time phrase equal to "+ 0 days."

Displaying a user's birthday

For this example, we output a user's birthdate, using the dateTrait property with the attributeuser.[traits.birthday]. We use 1993-01-20 for the example calculation below.

{{computeDate '{
"dateTrait": "user.[traits.birthday]",
"outputFormat": "yyyy/MM/dd"
}'
}}

Once the function is evaluated, it displays the date 1993/01/20 in the section where it is used in the message.

Displaying the date 10 days from a user's birthday

For this example, we output the date 10 days after a user's birthday, using the dateTrait property with the attributeuser.[traits.birthday] and the timePhrase property with the value +10 days. We use 1993-01-20 for the example calculation below.

{{computeDate '{
"dateTrait": "user.[traits.birthday]",
"timePhrase": "+ 10 days",
"outputFormat": "dd/MM/yyyy"
}'
}}

Once the function is evaluated, it displays the date 30/01/1993 in the section where it is used in the message.

Number Formatting

To format numbers on CrossEngage, you should use the formatDigits function. The syntax of this formatting function is:

{{formatDigits '{
"propertyName": [Value that should be formatted],
"numberDecimals": [Decimals number],
"decimalSeparator": [Decimal separator],
"thousandsSeparator": [Thousand separator],
"percentage": [Percentage option]
}'
}}

Property

Type

Description

propertyName

string

Required. The attribute containing the value that is used for formatting. e.g. [properties.price]

numberDecimals

integer

Required. The number of decimals that is displayed. e.g. 2

decimalSeparator

string

Optional. The string that is used to separate decimals e.g. ,

thousandsSeparator

string

Optional. The string that is used to separate thousands e.g. .

percentage

boolean

Optional. This option specifies whether the value should be formatted as a percentage or not. e.g. true

Please note that the number formatting helper function only works when used with either the #includeProducts or #findProduct helper function.

Use Cases

Formatting the price of a product extracted from the product feed

Using the helper function #findProduct, we search for a particular sku and format the result's [properties.price] attribute. We use 2000 as the value of the product's price for the example below.

{{formatDigits '{
"propertyName": "[properties.price]",
"numberDecimals": 2,
"decimalSeparator": ",",
"thousandsSeparator": ".",
"percentage": "false"
}'
}}

Once the function is evaluated, it displays 2.000,00 in the section where it is used in the message.

Sending a voucher with a discount as a percentage

Using the helper function #findProduct, we search for a particular sku and format the result's [properties.discount] attribute. We use 15 as the value of the product's price for the example below.

{{formatDigits '{
"propertyName": "[properties.discount]",
"numberDecimals": 0,
"percentage": "true"
}'
}}

Once the function is evaluated, it displays 15% in the section where it is used in the message.

String Formatting

CrossEngage offers two string formatting functions:

  1. trim - used to remove whitespace around a string

  2. substring - used to display a substring of an existing string

Trimming a String

To display content from a text field that could contain whitespace around the string, you can use the trim function. The syntax of this formatting function is:

{{#trim}}{{[attribute]}}{{/trim}}

Property

Description

attribute

Any user or event attribute or any information extracted through any of the helper functions. e.g. {{user.[traits.email}}

Use Cases

Removing the white space around an email attribute

For the example below, we use john.doe@crossengage.io as the value of the user's email attribute.

{{#trim}}{{user.[traits.email]}}{{/trim}}

Once the function is evaluated, it displays john.doe@crossengage.io in the section where it is used in the message.

Removing the white space around a product name field

Using the helper function #findProduct, we search for a particular sku and format the result's [properties.name] attribute. For the example below, we use iPhone 8 Plus as the value of the product's name.

{{#trim}}{{[properties.name]}}{{/trim}}

Once the function is evaluated, it displays iPhone 8 Plus in the section where it is used in the message.

Extracting a Substring

To display content from a text field that could contain whitespace around the string, you can use the trim function. The syntax of this formatting function is:

{{substring '{
"propertyName": [Attribute],
"start": [Substring start],
"length": [Substring length]
}'
}}

Property

Description

propertyName

Required. Any user or event attribute or any information extracted through any of the helper functions.

start

Required. The index of the character in the original string where the substring starts. e.g. 1 refers to the first character in the string, 3 to the third character.

length

Required. The number of characters the substring extracts from the original string. e.g. 10

Use Cases

Creating a preview from a product description

Using the helper function #findProduct, we search for a particular sku and format the result's [properties.description] attribute. For the example below, we use the following value for the product description attribute:

DESCRIPTION: iPhone 8 introduces an all‑new glass design. The world’s most popular camera, now even better. The most powerful and smartest chip ever in a smartphone.

To display only the first sentence of the description, also removing the DESCRIPTION: part of the text, we use the following function and parameters:

{{substring '{
"propertyName": "[properties.description]",
"start": 13,
"length": 44
}'
}}

Once the function is evaluated, it displays iPhone 8 introduces an all‑new glass design. in the section where it is used in the message.