SAIL Design System guidance available for Charts
Every chart should tell a story. What does yours say? Learn how to build rich reporting dashboards that provide users with visualizations of their data. |
a!pieChartField( label, instructions, series, showDataLabels, showTooltips, showAsPercentage, labelPosition, helpTooltip, accessibilityText, showWhen, colorScheme, style, seriesLabelStyle, height, data, config, refreshAlways, refreshAfter, refreshInterval, refreshOnReferencedVarChange, refreshOnVarChange )
Displays numerical data as slices of a single circle. Use a pie chart to graphically display parts of a whole.
See also:
Name | Keyword | Types | Description |
---|---|---|---|
Label |
|
Text |
Text to display as the field label. |
Instructions |
|
Text |
Supplemental text about this field. |
Series |
|
List of PieChartSeries |
Array of data series created with a!chartSeries(). |
Show data labels |
|
Boolean |
Determines if data values are displayed with each pie slice. Default: false. |
Show tooltips |
|
Boolean |
Determines if a tooltip displays the data value for a pie slice. Default: false. |
Show as percentage |
|
Boolean |
Determines if the data is shown as a percentage. Default: false. |
Label Position |
|
Text |
Determines where the label appears. Valid values:
|
Help Tooltip |
|
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 |
Accessibility Text |
|
Text |
Additional text to be announced by screen readers. Used only for accessibility; produces no visible change. |
Visibility |
|
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 |
|
Any type |
Determines which color scheme to use in the chart. Use one of the following valid values: |
Style |
|
Text |
Determines if the chart displays as a full pie or as a donut. Valid values: |
Series Label Style |
|
Text |
Determines where to display the series labels. Valid values: |
Height |
|
Text |
Determines the chart height. Valid values: |
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 |
|
PieChartConfig |
Configures how to display data on the chart, including fields used for calculations and grouping, using a!pieChartConfig(). |
Refresh Always |
|
Boolean |
When true, chart data will be refreshed after each user interaction and each interval refresh. Default: false. |
Refresh After |
|
List of Text String |
Refreshes chart data each time a specified event completes. Valid values: |
Refresh After an Interval of Time |
|
Number (Decimal) |
How often chart data gets refreshed in minutes. When null, chart data will not be refreshed on an interval. Valid values: |
Refresh on Reference Variable Change |
|
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 |
Refresh on Variable Change |
|
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. r |
There are two ways to configure a pie chart:
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.
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.
When using series, you must provide the list of data labels and values directly to the parameter using a list of a!chartSeries()
.
true
. For example, Americas: 0
.[Series #]
with #
as the label's index number in the series if Show data labels is set to true
. For example, [Series 1]: 3
.true
: [Series 1]: 0
.LEGEND
and data labels are displayed, the data labels are shown in the legend in parentheses. For example, West Region (25%)
.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.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.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.-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.true
.a!recordData
or a record type reference, the series parameter is ignored.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.
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.In a portal, you can't use a record type as the data source for a chart. Instead, use the categories and series parameters to construct the chart manually. See Working with Data in Portals to learn how to query data in a portal.
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.
Use the interactive editor below to test out your code:
Use the interactive editor below to test out your code:
Use the interactive editor below to test out your code:
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. |
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.
Pie Chart Component