Expressions

When working with columns in the tile editor, you may want to alter how a piece of data is displayed or to create a new column entirely. In cases such as this, you can provide Mustache-style expressions combined with JavaScript operations to manipulate and format your data any way you see fit.

Types of expressions

There are two types of expressions you can use in SquaredUp: format expressions and value expressions. These share the exact same syntax (see Writing expressions), however their use cases set them apart.

Format expressions

Format expressions are used 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.

For example, you can:

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) }}

Value expressions

Value expressions are used to create completely new values by manipulating the available data. As such these are only used when creating custom columns, but can be used in conjunction with format expressions.

For example, you can:

Create URL columns:
https://example.com?ticketId={{ $['id'] }}
Map values to create state or boolean columns:
{{ $['value'] / 100 ? 'success' : 'error' }} {{ $['log'].includes('ERROR') }}

Using expressions with columns

From the tile editor, select the Columns tab.
Click on the column you want to format. The Configure column window opens.
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.
Value expression:
Only displays when editing a custom column. Enter your custom expression to manipulate the actual value of the column.
Select Custom from the Formatting section.
Format Expression:
Enter your custom expression to cosmetically change how the value displays.
The configure column window accessed via a custom column

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 something like this: Progress: 10 out of 20.

Accessing column data

To access the value from a particular column, use the $ object. Accessing each column as a property on that object, e.g. $.myColumn or $['myColumn'] will return the value for a column called myColumn. From there you can use standard JavaScript to manipulate the value.

Other placeholder variables

Variable	Description	Example
`$`	The current row object, containing the available columns as object properties. Column names containing `.` or other reserved characters must be accessed via a string. 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. This can be used with the `$rows` variable to get the previous or next row for example.	`{{ $rows[$rowIndex + 1].value }}`
`$rows`	An array of all the rows in the dataset. This can be used to calculate aggregate values that are used to format individual values, e.g. calculating the sum of all values to work out the percentage each row contributes.	`{{ $rows.length }}`
`$columns`	An array of all the columns in the data. This can be used to find columns if their names are not known ahead of time.	`{{ $columns.find(c ⇒ c.name == 'myColumn' }}`
`$context`	A single object instance which is passed every time the placeholder is evaluated. This allows for expensive values that don’t change between rows to be cached, for accumulating values across rows, grouping values etc.	`{{ // 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 also supports IntelliSense to make suggestions and show commands/properties that 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`

Was this article helpful?

Have more questions or facing an issue?

Submit a ticket