Use advanced formatting

You can use Arcade expressions for advanced formatting of the list, indicator, and table elements to customize how your data points render. A data point can represent either a feature or summary statistic, depending on how the element is configured. When using features, a single data point represents a single feature. When using a statistic, each data point represents the result of that statistic. The list element renders your feature data points as line items, with each line representing one data point. The indicator element renders one data point at a time. The table element renders feature data points as rows, with the ability to control content and format each cell in the row.

Unlike attribute expressions (used in a layer's pop-up, styles, and labels), a single expression is authored for each element. The expression is executed for each data point and returns system-defined and user-defined properties for that element. System-defined properties are the settings you would otherwise configure in an element, such as text and background color. User-defined properties are defined by the user in the expression and can be referenced while configuring the element.

Note:

Attribute expressions authored in web maps don't carry over for use in dashboard elements.

The following table summarizes what data from your layer will be passed into the expression:

Variable nameTypeDescription

$datapoint

Feature or Dictionary

Applies to indicator, table, and list

$reference

Dictionary

Applies to indicator

Note:
Keep the following in mind when writing Arcade expressions:
  • Include a comma after each property in a dictionary, except for the last property.
  • Attribute names must not contain spaces or special characters.

Format lists

For the list element, you can use Arcade expressions by enabling the Advanced formatting option. Once you choose to use advanced formatting, color inputs become unavailable, along with any other system-defined properties.

The expression, which is executed for each line item, is used to define how each line on your list renders. Additionally, an expression can be used to create attributes that can be referenced in the line item template.

Data point attributes can be referenced using the $datapoint global variable in the Arcade editor. The following table provides the list of properties that can be returned from the expression in the form of a dictionary:

PropertyValue typeDescription

textColor

String

Base text color of the line item

backgroundColor

String

Background color of the line item

separatorColor

String

Bottom border color of the line item

selectionTextColor

String

Color used for line item text when the item is selected

selectionColor

String

Base text color used when item is selected

attributes

Dictionary

A dictionary of attribute-value pairs

yourAttributeName

String, Number, Date, Boolean

Attribute that can be referenced in the Line Item Template using the {expression/yourAttributeName} syntax

Note:

Geometry functions are not supported.

For example, if you want the background color of your list to turn red when the value is above a certain threshold, you can create a variable that looks like the following:

var color = IIF($datapoint.fieldName>[threshold], '#F3DED7','')

In this variable, fieldName is the field for your values, and [threshold] is the value at which you want the background color to change. The variable can be used as a property value, such as in the following example:

backgroundColor: color,

Using this variable in the background color property gives you an expression that looks like the following, where the background color of the list item will turn red when the value for speed is above 40:

var color = IIF($datapoint.Speed > 40, '#F3DED7', '');

return {
	backgroundColor: color
}

Enable advanced formatting in a list

To enable advanced formatting in a list element, do the following:

  1. In the configuration window of the list, click the List tab.
  2. In the Advanced formatting section, click Enable.
    Note:
    Once advanced formatting is enabled, system-defined settings such as color inputs become unavailable. These configurations are made in your expression. If you entered values before enabling advanced formatting, they are automatically added to your expression.
  3. Create your formatting expression in the editor.
    Tip:
    If you need help with any of the Arcade functions, click the Information button next to the function to see additional details.
  4. If you want your expression to execute at a specified interval, for example, if your expression uses the Now() function, enable the Refresh script toggle button and set a refresh interval.
  5. Enter any new attributes in the Line item template field using the syntax {expression/yourAttributeName}.

Format indicators

For the indicator element, you can use Arcade expressions by enabling the Advanced formatting option. Once you choose to enable advanced formatting, the system-defined properties, such as color options and value formatting, become unavailable, and conditional formatting turns off. The expression is used to define these rendering properties and conditional logic. Additionally, an expression can pass out user-defined attributes to be referenced in the Title and Description fields on the General tab.

When including a reference value to your indicator, only a statistic-based reference type is available on the Data tab once advanced formatting is enabled. If you previously defined a fixed value reference type, it is automatically added to the expression, along with any conversion factors, text, and color formatting. Value formatting done before enabling advanced formatting is removed and needs to be defined in the expression using value patterns.

Note:

Previous value is not supported in Arcade. If you set a previous value reference type before enabling advanced formatting, it will be converted to the current value.

Data point attributes can be referenced using the $datapoint global variable in the Arcade editor. Depending on whether the value type is Feature or Statistic, $datapoint is of type feature or dictionary, respectively. If a reference statistic has been configured on the Data tab, the $reference global variable will also be available in the editor.

The following table provides the list of properties that can be returned from the expression in the form of a dictionary:

PropertyValue typeDescription

textColor

String

Base text color of indicator element

backgroundColor

String

Background color of indicator element

topText

String

Displays as the top text

topTextColor

String

Color of top text

topTextOutlineColor

String

Color of top text outline

topTextMaxSize

String

Maximum top text size (xx-small | x-small | small | medium | large | x-large | xx-large)

middleText

String

Displays as the middle text

middleTextColor

String

Color of middle text

middleTextOutlineColor

String

Color of middle text outline

middleTextMaxSize

String

Maximum middle text size (xx-small | x-small | small | medium | large | x-large | xx-large)

bottomText

String

Displays as bottom text

bottomTextColor

String

Color of bottom text

bottomTextOutlineColor

String

Color of bottom text outline

bottomTextMaxSize

String

Maximum bottom text size (xx-small | x-small | small | medium | large | x-large | xx-large)

iconName

String

Name of icon defined for indicator

Note:

Icon names are defined outside the expression.

iconAlign

String

Icon placement adjacent to the middle text (left | right)

iconColor

String

Fill color of icon

iconOutlineColor

String

Outline color of icon

noValue

Boolean

Flag to display no value text instead of indicator (true | false)

attributes

Dictionary

A dictionary of attribute-value pairs

yourAttributeName

String, Number, Date, Boolean

Attribute that can be referenced in the Title and Description fields using the {expression/yourAttributeName} syntax

For example, if you have an indicator that shows a value in one unit of measurement, but you also want to show the same value in another unit below it, you can create a variable to convert your existing values. With an indicator showing average temperature in Celsius, you can create a Fahrenheit variable to use in your expression to also display your values in Fahrenheit.

var fahrenheit = Floor(($datapoint.avg_Temperature/5*9)+32)

You can then include the variable as a property value, such as the following:

bottomText: fahrenheit,

Using this variable in the bottom text property gives you an expression that looks like the following, where the average temperature (in Celsius) is displayed in the middle text of the indicator and the Fahrenheit value is displayed in the bottom text:

var farenheit = Floor(($datapoint.avg_Temperature/5*9)+32)

return {
	topText: 'Average Temperature',
	middleText: Floor($datapoint.avg_Temperature),
	bottomText: farenheit,
}

Enable advanced formatting in an indicator

To enable advanced formatting in an indicator element, do the following:

  1. In the configuration window of the indicator, click the Indicator tab.
  2. In the Advanced formatting section, click Enable.
    Note:
    Once advanced formatting is enabled, system-defined settings such as color inputs become unavailable. These configurations are made in your expression. If you entered values before enabling advanced formatting, they are automatically added to your expression.
  3. Create your formatting expression in the editor.
    Tip:
    If you need help with any of the Arcade functions, click the Information button next to the function to see additional details.
  4. If you want your expression to execute at a specified interval, for example, if your expression uses the Now() function, enable the Refresh script toggle button and set a refresh interval.
  5. Optionally, reference any new attributes in the Title and Description fields using the syntax {expression/yourAttributeName}.

Format tables

For the table element, you can use an Arcade expression by enabling the Advanced formatting option. Once you choose to use advanced formatting, color inputs, text alignment options, and other system-defined properties become unavailable and are instead set in the expression.

The expression, which is executed for each row in the table, is used to define the content and formatting for each cell in the column. Data point attributes can be referenced using the $datapoint global variable in the Arcade editor.

The cells dictionary must have a property for each field defined on the Data tab of the table's configuration. For example, in a grouped value table that has a category field for Zone, and a value field of Transaction Amounts, the cells dictionary contains two properties: zone and sum_transaction_amounts.

The following table provides the list of properties that can be returned from the expression in the form of a dictionary:

PropertyValue typeDescription

cells

Dictionary

A dictionary of column names based on fields defined on the Data tab

displayText

String

Text displayed in the cell

Note:

The displayText property is required.

hoverText

String

Text that appears when hovering over the values.

Note:

Hover text must first be enabled in the Table tab.

textColor

String

Text color of the cell

backgroundColor

String

Background color of the cell

textAlign

String

Alignment (left | center | right)

iconName

String

Name of icon defined for the table

Note:

Icon names are defined outside the expression.

iconAlign

String

Icon placement adjacent to the cell's text (left | right)

iconColor

String

Fill color of icon

iconOutlineColor

String

Outline color of icon

You can also use advanced formatting to create conditional formatting for your table. For example, if you have a table displaying recent repair requests, you may want to apply conditional formatting to distinguish the status of requests. You can create a variable that changes the color of the cell based on the status using a variable that looks like the following:

var statusColor = When($datapoint.status== 'new', 'yellow', $datapoint.status== 'closed', 'lightgray', 'white')

You can then assign the variable to the backgroundColor property so the cells are highlighted for new incidents and de-emphasized for closed incidents.

var statusColor = When(
	$datapoint.status == 'new', 'yellow',
	$datapoint.status == 'closed', lightgray', 'white')

return {
	cells:{
		requests:{
			displayText: <span>${$datapoint.requests}</span>, 
			backgroundColor: statusColor,
			}
		}
	}
Note:

Expressions are not applied to a table's summary row.

Enable advanced formatting in a table

To enable advanced formatting in a table element, do the following:

  1. In the configuration window of the table, click the Values tab.
  2. In the Advanced formatting section, click Enable.
    Note:
    Once advanced formatting is enabled, system-defined settings such as color inputs become unavailable. These configurations are made in your expression. If you entered values before enabling advanced formatting, they are automatically added to your expression.
  3. Create your formatting expression in the editor.
    Tip:
    If you need help with any of the Arcade functions, click the Information button next to the function to see additional details.
  4. If you want your expression to execute at a specified interval, for example, if your expression uses the Now() function, enable the Refresh script toggle button and set a refresh interval.

Define icon names

The indicator and table elements allow you to include SVG icons in your element's configuration. When using advanced formatting, icons are added in your Arcade expression.

To add an icon to your Arcade expression, do the following:

  1. In the Icons section below the Arcade editor, click Add.
  2. Choose an icon or create a custom icon.
  3. Enter a name for your icon.
  4. In your Arcade expression, return your icon name as the value for the iconName property.

Color values

When including color values in an expression, they must be returned as strings (surrounded by quotation marks). Color values that are left undefined or are invalid will automatically use defaults. Accepted color value types include hex values, RGB, RGBA, HSL, and HSLA. The following are some examples along with the supported syntaxes:

  • Hex
    • #090
    • #009900
    • #090a
    • #009900aa
  • RGB and RGBA
    • rgb(34, 12, 64)
    • rgba(34, 12, 64, 0.6)
  • HSL and HSLA
    • hsl(50, 33%, 25%)
    • hsla(50, 33%, 25%, 0.75)