Pie Chart Component

Function

a!pieChartField( label, instructions, series, showDataLabels, showTooltips, showAsPercentage, labelPosition, helpTooltip, accessibilityText, showWhen, colorScheme, style, seriesLabelStyle, height, data, config, refreshAlways, refreshAfter, refreshInterval, refreshOnReferencedVarChange, refreshOnVarChange, allowImageDownload, loadDataAsync )

Displays numerical data as slices of a single circle. Use a pie chart to graphically display parts of a whole.

See also:

• Configure Charts Using Records
• Chart Color Schemes

Parameters

Name	Keyword	Types	Description
Label	label	Text	Text to display as the field label.
Instructions	instructions	Text	Supplemental text about this field.
Series	series	List of PieChartSeries	Array of data series created with a!chartSeries().
Show data labels	showDataLabels	Boolean	Determines if data values are displayed with each pie slice. Default: false.
Show tooltips	showTooltips	Boolean	Determines if a tooltip displays the data value for a pie slice. Default: false.
Show as percentage	showAsPercentage	Boolean	Determines if the data is shown as a percentage. Default: false.
Label Position	labelPosition	Text	Determines where the label appears. Valid values: "ABOVE" (default) Displays the label above the component. "ADJACENT" Displays the label to the left of the component. "COLLAPSED" Hides the label. The label will still be read by screen readers; see accessibility considerations for more information. "JUSTIFIED" Aligns the label alongside the component starting at the edge of the page.
Help Tooltip	helpTooltip	Text	Displays a help icon with the specified text as a tooltip. The tooltip displays a maximum of 500 characters. The help icon does not show when the label position is "COLLAPSED".
Accessibility Text	accessibilityText	Text	Additional text to be announced by screen readers. Used only for accessibility; produces no visible change.
Visibility	showWhen	Boolean	Determines whether the component is displayed on the interface. When set to false, the component is hidden and is not evaluated. Default: true.
Color scheme	colorScheme	Any type	Determines which color scheme to use in the chart. Use one of the following valid values: "CLASSIC", "MIDNIGHT", "OCEAN", "MOSS", "BERRY", "PARACHUTE", "RAINFOREST" (default), "SUNSET" or define a custom color scheme using a!colorSchemeCustom. See Chart Color Scheme for color scheme examples.
Style	style	Text	Determines if the chart displays as a full pie or as a donut. Valid values: "PIE" (default), "DONUT".
Series Label Style	seriesLabelStyle	Text	Determines where to display the series labels. Valid values: "ON_CHART" (default), "LEGEND", "NONE".
Height	height	Text	Determines the chart height. Valid values: "SHORT", "MEDIUM" (default), "TALL".
Data	data	Any type	Reference to the record type used for the source of this chart. Can accept a!recordData or a Record Type Reference.
Chart Configuration	config	PieChartConfig	Configures how to display data on the chart, including fields used for calculations and grouping, using a!pieChartConfig().
Refresh Always	refreshAlways	Boolean	When true, chart data will be refreshed after each user interaction and each interval refresh. Default: false.
Refresh After	refreshAfter	List of Text String	Refreshes chart data each time a specified event completes. Valid values: "RECORD_ACTION".
Refresh After an Interval of Time	refreshInterval	Number (Decimal)	How often chart data gets refreshed in minutes. When null, chart data will not be refreshed on an interval. Valid values: "0.5", "1", "2", "3", "4", "5", "10", "30", and "60".
Refresh on Reference Variable Change	refreshOnReferencedVarChange	Boolean	When true, chart data will be refreshed each time the value of any variable referenced in the data parameter is updated. To refresh chart data when another variable that is not used in the data parameter changes, use refreshOnVarChange. Default: true.
Refresh on Variable Change	refreshOnVarChange	Any Type	Refreshes chart data each time any of these specific variables change. This allows you to refresh the chart data when a variable that is not referenced in the data parameter is updated. You can define a single variable (e.g. refreshOnVarChange: local!var1) or a list of variables (e.g. refreshOnVarChange: {local!var1, local!var2}).
Allow Image Download	allowImageDownload	Boolean	Determines if the chart download button displays on the chart. Default: false.
Load Chart Data in Background	loadDataAsync	Boolean	Determines whether to load the chart data independently from the rest of the components in the interface. When true, this can improve user experience by allowing users to view the rest of the page while the data loads. See Asynchronous Loading for more information. Default: false.

Configuration

There are two ways to configure a pie chart:

1. Set a record type as the data source and define fields to display on the chart.
2. Perform your own query and define lists of data within the series.

If you have a record type that uses a database as the source, or a record type with data sync enabled, we recommend using the record type as the source of your chart. This configuration is easier because Appian will perform the query for you and display the results directly in the chart.

If your record type uses a web service as the source and does not have data sync enabled, use the categories and series to construct the chart manually.

Using record data

Configuring a pie chart using a record type as the source requires using two parameters: data and config. Once you provide a record type in the data parameter and provide the fields in the config parameter, the chart displays the results.

See Chart Configuration Using Record Data for details on using a record type as the source. See Build Reports from Records for examples of reports created with different charts.

Using series

When using series, you must provide the list of data labels and values directly to the parameter using a list of a!chartSeries().

• The labels and data arguments in the series are shown in the data labels and tooltips (if enabled).
• If a series has a non-null label value paired with a 0, null, or empty data value, the data value is treated as 0 and is still displayed if Show data labels is set to true. For example, Americas: 0.
• If a series argument has a null or empty label paired with a non-null data value, the label is displayed as [Series #] with # as the label's index number in the series if Show data labels is set to true. For example, [Series 1]: 3.
• If a series argument has both a null or empty label paired with a 0, null, or empty data value, the above behaviors are combined and the following is displayed if Show data labels is set to true: [Series 1]: 0.

Usage considerations

Chart legends

• If the series label style is set to LEGEND and data labels are displayed, the data labels are shown in the legend in parentheses. For example, West Region (25%).
• Using the LEGEND or NONE series label styles will ensure consistent sizing of the pie for any columns of the same width. When ON_CHART is used for the series label style, the pie changes size based on the length of the series label.
• The ON_CHART style will usually use screen space more effectively than the LEGEND. Since showing the legend guarantees the same size pies across columns of the same width, there may be extra whitespace if a short label is used in the legend.
• If the legend is displayed, it will show below the pie in MEDIUM width columns or narrower; in wider columns the legend will show adjacent to the chart. The legend always displays below the pie on phones.

Chart data and values

• If a data value is negative, the data label shows it as negative (for example -20), but it still displays as a pie slice. To avoid any confusion, negative values should only be used with bar, column, and line charts.
• Since pie chart values do not have an x-axis for reference, Appian recommends setting Show data labels as true.
• When values are shown as percentages, they are rounded to one decimal place. If values in the second decimal place are 5 or higher, the first decimal number is rounded up. If the percentage is less than 0.1%, the chart will not render a slice for the section.
• If data contains a!recordData or a record type reference, the series parameter is ignored.
• When you use a record type as a source for your chart, you can use a!measure() to perform a calculation on a single field. If you need to perform multiple calculations within the same chart, use series to configure your chart instead of data and config.

Chart lines and background colors

When the chart is placed in a colored card, the chart background will match the color of the card. Text labels and lines in the chart will also adjust if a dark background color is used. See the SAIL Design System for best practices on using charts with background colors.

Chart refresh behavior

• You can define a!refreshVariable parameters directly in the chart without creating additional local variables. The only exception being refreshOnVarChange, which refreshes the chart after a specific local variable has changed.
• When you use a record type as the source of your chart, it's recommended to use the refresh parameters in the chart instead of using local variables and the a!refreshVariable() function. This is because the refresh behavior will automatically apply to the fields specified in the data parameter of the chart.
• If you're not using a record type as the source of your chart, it's recommended to use local variables and the a!refreshVariable() function to define refresh behavior since you won't use the data parameter to configure your chart.

Row limit for records-powered components

Interface components that use a record type as the data source are known as records-powered components.

Records-powered components can display a maximum of 5,000 rows. As a best practice, you should not display all 5,000 rows in a component since it may impact performance.

Using the loadDataAsync parameter

Setting the loadDataAsync parameter to true allows the interface to load without waiting for chart data, displaying a placeholder skeleton in its place. This improves user experience by enabling users to interact with other parts of the interface while the chart loads.

Only enable this if either:

• The chart is the slowest-loading component on the interface.
• The chart is the only component on the interface and it takes more than one second to load.

See Asynchronous Loading for more detailed information about enabling asynchronous (async) loading and how it works.

Examples

The examples below demonstrate how to configure your charts using categories and series. For examples on using record data, see Chart Configuration Using Record Data.

Pie chart with label, instructions, and data labels

Use the interactive editor below to test out your code:

Pie chart with label, instructions, data labels, tooltips, and percentage

Use the interactive editor below to test out your code:

Donut style chart with legend and colors assigned in series

Use the interactive editor below to test out your code:

Feature compatibility

The table below lists this component's compatibility with various features in Appian.

Feature	Compatibility	Note
Portals	Compatible
Offline Mobile	Incompatible
Sync-Time Custom Record Fields	Incompatible
Real-Time Custom Record Fields	Incompatible	Custom record fields that evaluate in real time must be configured using one or more Custom Field functions.
Process Reports	Incompatible	Cannot be used to configure a process report.
Process Events	Incompatible	Cannot be used to configure a process event node, such as a start event or timer event.
Process Autoscaling	Compatible

Related Patterns

The following patterns include usage of the Pie Chart Component.

• Aggregate Data and Conditionally Display in a Chart or Grid (Reports, Charts, Query Data, Grids, Records): Aggregate data and conditionally display it in a pie chart or grid. In this pattern, we will calculate the total number of employees in each department and display it in a pie chart and a read-only grid. Then, we'll use a link field to conditionally display each component.

• Aggregate Data and Display in a Chart (Reports, Charts, Query Data, Records): Aggregate data, specifically the total number of employees in a given department, to display in a pie chart.

• Filter the Data in a Grid Using a Chart (Charts, Grids, Filtering, Records): Display an interactive pie chart with selectable sections so that a user may filter the results in a grid.

• Refresh Until Asynchronous Action Completes (Auto-Refresh): Use a refresh interval to display the results of an asynchronous action automatically.

Feedback