Pie Chart

Function: a!pieChartField()

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

See also: Column Chart, Bar Chart, Line Chart, Chart Series, UX Charts Best Practices, a!queryRecordType(), Tempo Report Best Practices, Chart Color Schemes

Parameters

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.

The chart allows using an entity-backed or synced record type as the source. If you have one of these record types available as a source, we recommend using the record type as the source. This configuration is easier because Appian will perform the query for you and display the results in the bar chart directly. If you have complex requirements or your data source is not a entity-backed or synced record type, use the 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 source 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.

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(). See the notes below for guidance.

• 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.

Additional Notes

• 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.
• 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 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.
• 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 UX Design Guide for best practices on using charts with background colors.

Examples

The examples below demonstrate how to configure your charts using categories and series. For examples on using record data, please see Chart Configuration Using Record Data. Copy and paste an example into the INTERFACE DEFINITION in EXPRESSION MODE to see it displayed.

Pie Chart with Label, Instructions, and Data Labels

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
a!pieChartField(
  label: "New Hires by Department",
  instructions: "The number of new employees hired by each department in 2019",
  series: {
    a!chartSeries(label: "Engineering", data: 12),
    a!chartSeries(label: "Professional Services", data:  9),  
    a!chartSeries(label: "Sales", data:  8), 
    a!chartSeries(label: "Finance", data:  6),
    a!chartSeries(label: "HR", data:  4)
  
  },
  colorScheme: "OCEAN",
  showDataLabels: true,
  showTooltips: true,
  showAsPercentage: false
)

Displays the following:

Pie Chart with Label, Instructions, Data Labels, Tooltips, and Percentage

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
a!pieChartField(
  label: "Opportunity Sources",
  instructions: "Leads are calculated based on the initial mode of contact",
  series: {
    a!chartSeries(label: "Existing Client", data: 12),
    a!chartSeries(label: "Inbound Call",    data:  6),
    a!chartSeries(label: "Tradeshow",       data:  8),
    a!chartSeries(label: "Web Site",        data:  6),
    a!chartSeries(label: "Referral",        data:  7)
  },
  colorScheme: "MIDNIGHT",
  showDataLabels: true,
  showTooltips: true,
  showAsPercentage: true
)

Displays the following:

Donut Style Chart with Legend and Colors Assigned in Series

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
a!pieChartField(
  label: "Employee Credential Status",
  labelPosition: "ABOVE",
  series: {
    a!chartSeries(label: "Active Credential", data: 1374, color: "BLUEGRAY"),
    a!chartSeries(label: "Expires within 30 Days", data: 343, color: "AMBER"),
    a!chartSeries(label: "Expired", data: 97, color: "RED")
  },
  height: "SHORT",
  seriesLabelStyle: "LEGEND",
  colorScheme: "CLASSIC",
  style: "DONUT",
  showDataLabels: true,
  showAsPercentage: true
)

Displays the following:

Related Patterns

The following patterns include usage of the Pie Chart Component.

• Aggregate Data from a Data Store Entity and Conditionally Display in a Chart or Grid (Reports, Charts, Query Data, Grids): Aggregate data from a data store entity, specifically the total number of employees in each department, to display in a pie chart.

• Aggregate Data from a Data Store Entity and Display in a Chart (Reports, Charts, Query Data): Aggregate data from a data store entity, 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): 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.