Expressions

Expressions allow you to manipulate, format, and parameterize data throughout SquaredUp using Mustache-style placeholders {{ }} combined with JavaScript.

While expressions all use the same syntax, they serve different use cases depending on the area of SquaredUp you’re configuring.

Where expressions can be used

There are several main areas in SquaredUp that allow you to use expressions:

  • Columns
    Use expressions to alter how values are displayed.
  • Custom columns
    Use expressions to create new values by manipulating existing data, and optionally format how those
  • Data stream parameters
    Use expressions to parameterize requests with dynamic values such as timeframes and variables.

Expressions in columns

When editing a column, you can use format expressions to manipulate how a value is displayed on screen.

This is purely cosmetic and the actual value remains unchanged, meaning that any sorting or aggregation you perform on that column will still use that original value.

Examples

Perform calculations on values

{{ $['myColumn'] / 1000 }}

Combine text and/or multiple columns

Progress: {{ $['myColumn'] }} out of {{ $['myColumnTwo'] }}

Manipulate a string to remove/replace part of it

{{ $['myColumn'].substring(0, 20) }}

Expressions in custom columns

When creating a custom column, you can use value expressions to create completely new values by manipulating the available data.

Value expressions are used to define the actual value of the column. You can then apply a format expression to control how that value is displayed.

Examples

Create URL columns

https://example.com?ticketId={{ $['id'] }}

Map values to create state or boolean columns

{{ $['value'] / 100 ? 'success' : 'error' }}
{{ $['log'].includes('ERROR') }}

Expressions in data stream parameters

When configuring a data stream on the Parameters tab of the tile editor, you can use implement dynamic configuration by injecting variables (such as timeframes or user-defined values) directly into fields.

These parameter expressions allows a single configuration to adapt automatically based on context, rather than relying on hard-coded values. Fields which allow parameter expressions are denoted by the Insert expression

button.

Clicking Insert expression

opens the expression picker, where you can quickly insert common expressions. For example, {{timeframe}}, {{variable1}}, etc.

Writing expressions

Expressions uses Mustache-style placeholders ({{ }}) that contain JavaScript. Within a placeholder, you can use JavaScript to access the current row of data as well as other variables like the array of all rows, or current index.

A single expression may contain multiple placeholders as well as literal text. For example:

Progress: {{ $['myColumn'] }} out of {{ $['myColumnTwo'] }}

This would display:

Progress: 10 out of 20.

Accessing data

You can access data and context using the following variables:

Variable
Description
Example
$
The current row object. Column names containing . or reserved characters must be accessed via a string using bracket notation.
The properties return the value property of the data. Raw values can be accessed by referencing $columns (see below).
{{ $.myColumn }}
{{ $['complexColumn.name'] }}
$rowIndex
The index of the current row. Often used with the $rows variable to get the previous or next row.
{{ $rows[$rowIndex + 1].value }}
$rows
An array of all the rows in the dataset. Useful for aggregates (e.g. calculating the sum of all values to get the percentage that each row contributes).
{{ $rows.length }}
$columns
An array of all the columns in the data. Can be used to find columns if their names are not known ahead of time.
{{ $columns.find(c ⇒ c.name == 'myColumn') }}
$context
A single shared object instance that persists across evaluations. Useful for caching expensive calculations, accumulating values across rows, and grouping values.
{{ // total is only calculated once for the entire data set $context.total ??= $rows.reduce((sum, r) => sum + r.value, 0); ${($.value / $context.total) * 100}%; }}

IntelliSense

The editor used for inputting an expression provides IntelliSense support, making suggestions and showing which commands / properties are available. IntelliSense is automatically triggered as you type, or can be manually triggered using Ctrl+Space.

Error handling and troubleshooting

If a placeholder throws an error or contains invalid JavaScript syntax, the error message is captured and used as the output of the placeholder for debugging purposes.

Format expression
Issue
Error output
${{ $.vlue.toLocaleString() }} suffix
There is a typo: vlue is not the correct column name
${{ Expression Failed: Cannot read properties of undefined (reading 'toLocaleString') }} suffix
${{ $.value &^ }} suffix
Invalid JavaScript provided
${{ Expression Failed: Unexpected token '^' }} suffix

How to use expressions with columns

  1. From the tile editor, select the Columns tab.
  2. Click on the column you want to format. The Configure column window opens.
  3. Configure the following fields:
    1. Name:
      Enter a name for the column.
    2. Type:
      Select the data type of the column. Depending on the data type you select this enables additional configuration fields.
  4. Value expression:
    Only displays when editing a custom column. Enter your custom expression to manipulate the actual value of the column.
  5. Select Custom from the Formatting section.
  6. Format Expression:
    Enter your custom expression to cosmetically change how the value displays.
    The configure column window accessed via a custom column

Was this article helpful?

Have more questions or facing an issue?
Submit a ticket