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 name	Type	Description
$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:

Property	Value type	Description
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	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:

   For date fields, use the Text function to convert to strings, and they will display in the dashboard time zone. Text function also allows you to format the values to your preference. 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:

Property	Value type	Description
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	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:

Property	Value type	Description
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)