Functions
Number functions
The Text component must have the Format set to Number.
Format number
Format a number with grouped thousands and optionally decimal digits.
{% number_format([float number], [decimal_places], [decimal_separator], [thousands_separator]) %}
Round
Round the float number based on the precision from the second parameter.
{% round([float number], [integer precision]) %}
Ceil
Rounds to the nearest integer up. E.g. 2.1 => 3.
{% ceil ([float number]) %}
Floor
Rounds to the nearest integer down. E.g. 2.8 => 2.
{% floor ([float number]) %}
Pow
Number in power of.
{% pow([float base value], [integer|float power of]) %}
Sqrt
Square root of a number.
{% sqrt ([float base value])%}
String functions
Uppercase
To display data field value in uppercase, use following expression.
{% uppercase({dataFieldName}) %}
Lowercase
To display data field value in lowercase, use following expression.
{% lowercase({dataFieldName}) %}
Capitalize
Uppercase the first character of each word in a string.
{% capitalize({dataFieldName}) %}
Split
The split(delimiter, string) function allows to split string into an array.
{% split("_", "Some_string") %} => ["Some", "string"]
Replace
The str_replace([string: search], [string: replace], [string: the original string]) function replaces all occurrences of a substring within a string.
{% str_replace("dog", "cat", "this is dog") %}
This expression output is: this is catThe first two parameters can also be arrays that specify search and replace values e.g. {% str_replace(["dog", " is"], ["cat", " is not"], "this is dog") %} => this is not cat
Substring
The substr ( string $string , int $offset , int|null $length = null ) returns the portion of string specified by the offset and length parameters.
{% substr("This is test", 0, 2) %} // Result: Th
{% substr("This is test", 1, 2) %} // Result: hi
{% substr("This is test", -2) %} // Result: st
Count
The count({stringData}) returns the length of the string
{% count("abcd") %} // Result: 4
Date functions
Date
Format date value. NB! You need to use the Date formatter.
{% date({dateString}, {timezone}, {addDays}, {outputFormat}, {inputFormat}) %}
Examples of the function "Date":
Display current time
{% date('now') %}
Specify timezone
{% date({dateValue}, 'UTC') %}
Specify output format
{% date({dateValue}, 'UTC', 0, 'd/m/Y') %}
Specify output and input format
{% date({dateValue}, 'UTC', 0, 'd/m/Y', 'm/d/Y') %}
Datetime
Format datetime value. NB! You need to use the Date formatter.
{% datetime({datetimeString}, {timezone}, {addDays}, {outputFormat}, {inputFormat}) %}
Examples of the function "Datetime":
Display current time
{% datetime('now') %}
Specify timezone
{% datetime({dateValue}, 'UTC') %}
Specify output format
{% datetime({dateValue}, 'UTC', 0, 'd/m/Y H:i:s') %}
Specify output and input format
{% datetime({dateValue}, 'UTC', 0, 'd/m/Y H:i:', 'm/d/Y H:i:') %}
When using the T separator in a date format you need to escape it like this
Y-m-d\THH:mm:ss
Date difference
The date_diff function calculates a difference between two dates. You can also specify the {inputFormat} to hint date format. If date strings use known format then it is handled automatically..
{% date_diff({datetimeString}, {datetimeString}, {inputFormat}) %}
You can use date('now') function as the date value to find difference between today and another date.
{% date_diff(date('now'), '2021-09-15', 'Y-m-d') %}
The {inputFormat} parameter in the date_diff function is by default 'Y-m-d H:i:s'
List (array) functions
The Text component must have the Format set to Number.
Count
It is possible to count number of items in list.
{% count({line_items}) > 3 ? 'More than three' : 'Less than three' %}
Max
Returns maximum value of list of elements or separate field values.
{% max({line_items::quantity}) %}
or
{% max({dataField1}, {dataField2}, ..., {dataFieldN}) %}
Min
Returns minimum value of list of elements or separate field values.
{% min({line_items::quantity}) %}
or
{% min({dataField1}, {dataField2}, ..., {dataFieldN}) %}
Sum
It is possible to calculate sum of table column using following code.
{% sum({line_items::amount}) %}
Sumproduct
The sumproduct function multiplies the corresponding items in the arrays and returns the sum of the results.
{% sumproduct({line_items::amount},{line_items::price}, {line_items::anotherColumn}) %}
Average
It is possible to calculate average of table column using following code.
{% avg({line_items::amount}) %}
Use "Number" formatting when creating calculations or using sum, average, sumproduct functions.
Join
The join(delimiter, array) function concatenates field values with specified separator. Last argument is always used as the separator.
{% join(";", {field1}, {field2}, {field3}, ..., {fieldN}) %}
{% join(";", [{field1}, {field2}, {field3}, ..., {fieldN}]) %}
Iterate list of elements (array map)
Iterates over list of elements and executes expression for each element. Returns new list.
{% iterate({line_items}, 'quantity*price') %}
{% map({line_items}, 'quantity*price') %}
Filter list of elements
Filters a list of elements by executing the given expression for each element. Returns new list.
{% filter({line_items}, 'price > 10.1') %}
Collect unique values from list
Collects unique values from and counts them. Returns new list with following structure:
[{"value": "Value", "count": 3, "raw_value": "Value"}, {"value": "Value 2", "count": 1, "raw_value": "Value 2"}]
{% collect_unique_values({array}, {array_of_values_to_exclude}, {expression_to_execute_for_each_item}) %}
Example use case:
This is the JSON example dataset to demonstrate the functionality of collect_unique_values function.
[{"array_of_names":[{"name":"marian"},{"name":"bruno"},{"name":"erik"},{"name":"tanel"},{"name":"michal"},{"name":"erik"},{"name":"erik"}]}]
Lets say we want to make a list of unique values from the "array_of_names" data field, but exclude the names "tanel" and "michal".
The expression to do that would look like this:
{% join(", ", iterate((collect_unique_values({array_of_names}, ["michal","tanel"], "name")), "value")) %}
Flatten list
Flattens list.
{% flatten(iterate({orders}, "{line_items}")) %}
Sort list
The function sort([array], [expression], [direction])) allows you to sort list of elements by the key value. The direction can be either ASC or DESC. The function returns new array with sorted items.
{% sort({line_items}, "quantity", "DESC") %}
{% sort({line_items}, "quantity*price", "ASC") %}
{% sort({line_items}, "quantity > 10 ? 1 : 0", "ASC") %}
Utility functions
Empty
The empty(value) checks if the variable exists and if the value is not “falsy”. Returns true if var does not exist or has a value that is empty or equal to zero, aka falsely. Otherwise, it returns false.
{% empty({dataField}) ? 'No value' : 'Field has value' %}
What qualifies as "falsy"?
Anything that returns false if cast to boolean
Empty array
Zero as number
Zero as string
Empty string
null
false
undefined
JSON decode
Decode JSON string to use in an expression.
{% json_decode('{"key": "value"}', true) %}
Example datafield:
{
"json_field": "{\"name\":\"value\"}"
}
Example expressions for JSON decode
{% json_decode({json_field}).name %}
{% json_decode({json_field}, true)['name'] %}
Updated on: 28/10/2024
Thank you!