Custom Formatting

Custom formatting in SquaredUp lets you control how you display and format your data using Mustache-style expressions with JavaScript operations. This feature was previously called format expressions.

For example, you may wish to:

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

Custom formatting changes are purely cosmetic, meaning that while you can format a value of 1 to display as 1000000, any sorting or aggregation you perform on that column will still use the original value of 1.

Configuring custom formatting

From the tile editor, select the Columns tab.
Click on the type you wish to configure, e.g. String, Number etc.
Set the formatting mode to Custom
Enter your custom expression to change the formatting.
As you type, the preview will be updated.

How to use custom formatting

Custom formatting 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	`${{ Format Expression Failed: Cannot read properties of undefined (reading 'toLocaleString') }} suffix`
`${{ $.value &^ }} suffix`	Invalid JavaScript provided	`${{ Format Expression Failed: Unexpected token '^' }} suffix`

Was this article helpful?

Have more questions or facing an issue?

Submit a ticket