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.

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

{% 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.

Related articles you may find helpful

• How to access a specific array element?
• Is it possible to conditionally hide a page in the document?
• Text Component

Updated on: 11/04/2025