Articles on: Expression language

Common use-cases of the Expression language


Using Filter and Iterate function


Let's say you have an array of line items, where items can be of different type (e.g. "Food", "Drinks", etc...) and you need to get a SUM of a specific type. Then you can do it using a combination of filter and iterate function:


{% sum(iterate(filter({line_items}, 'type == "Drinks"'),'total_price')) %}


Example JSON dataset:

[
{
"line_items": [
{
"name": "Cola",
"price": 2,
"qty": 2,
"total_price": 4,
"type": "Drinks"
},
{
"name": "Fanta",
"price": 2,
"qty": 1,
"total_price": 2,
"type": "Drinks"
},
{
"name": "Burger",
"price": 4,
"qty": 2,
"total_price": 8,
"type": "Food"
}
]
}
]


The result of our expression would be 6.


Tip: Use the Number Component or apply "Number" formatting within tables, when creating calculations or using functions like sum, average and sumproduct.


Working with sub-items in the Array/Objects


In expression language, the sub-items are accessed with brackets.


Example JSON dataset:

[
{
"cars": [
{
"name": "Ford",
"model": {
"name": "Mustang",
"year": "1967"
},
"options": {
"color": "Red"
}
},
{
"name": "Chevrolet",
"model": {
"name": "El Camino",
"year": "1987"
},
"options": {
"color": "Black"
}
}
]
}
]


For example, you need to get the count of cars where a model name is "Mustang". The expression would look like this:


{% count(filter({cars}, 'model["name"] == "Mustang"')) %}


The result in this case would be 1.


Using Join function to get values from an array in a Text component


In this example we have an array of cars with objects - options and model. We would like to get the car name, model name and color for each car from the array and get the output in one text component.


{% join(', ', iterate({cars}, 'name ~ " " ~ model["name"] ~ "(" ~ options["color"] ~ ")"')) %}


Example JSON dataset:

[
{
"cars": [
{
"name": "Ford",
"model": {
"name": "Mustang",
"year": "1967"
},
"options": {
"color": "Red"
}
},
{
"name": "Chevrolet",
"model": {
"name": "El Camino",
"year": "1987"
},
"options": {
"color": "Black"
}
}
]
}
]


The output of this particular example would be: "Ford Mustang(Red), Chevrolet El Camino(Black)"


Changing the timezone of a date


Dates are usually pulled to the document editor with the original timezone from the e-commerce platform and you need to use the DateTime expression function with timezone to convert the times in the editor.{% datetime({dateValue}, 'UTC') %}
The expression function needs timezone in PHP format, which you can find here: https://www.php.net/manual/en/timezones.php


For example:


{% datetime({TestDateTime}, 'Europe/London') %}


Function str_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 cat


Tip: If you have a long string of e.g. options, where each option is separated with "/" and you would like to show each option on a separate line, you can use the function str_replace.


{% str_replace('/','<br>',{options_text}) %}


Handling Unknown or Missing variables


When working with expression language, you may encounter situations where a variable is either missing or undefined. In such cases, using the ?? allows you to specify a default value to prevent errors or unexpected behavior. This is particularly useful when you want to ensure that your expressions always have a fallback value, even when certain variables are unavailable.


unknownVariable ?? 'default value'


If unknownVariable is not defined (or is null or undefined), the expression will return "default value". This approach ensures that your calculations or logic do not fail due to missing variables.


For example:


{% (unknownVariable1 ?? 1) + (unknownVariable2 ?? 2) %} // => 3


In this case, if both unknownVariable1 and unknownVariable2 are missing, their respective default values (1 and 2) are used, resulting in a total of 3.



Updated on: 11/04/2025

Was this article helpful?

Share your feedback

Cancel

Thank you!