Introducing the new PieChartCardView for Adaptive Card Extensions

Introduction

The version 1.20 of SharePoint Framework introduces two different charts for the Adaptive Card Extensions, in this post I want to cover the PieChartCardView.

As the name suggests, this visual control displays a pie chart which can also be displayed as a donut chart.

I created a sample solution to display and demonstrate how to use this control, if you’re interested you can find it here.

Visual appearance

First things first let’s see how the new component renders. In the sample I used the same data but configured the control in different fashions in order to change the visual result.

Starting with the pie chart, this is the resulting UI:

The control will display different colors and also the labels for each of the data point.

As by now, when a label contains more than 3 characters, it will be truncated after those 3 characters. For example, in the screenshot above, the category with the 20% value has a label “Category” which is truncated and results in “Cat”.

Changing a property of the control, which I will cover in the code section, it’s possible to modify the resulting UI into a donut chart instead of the pie one. Displaying the chart using the donut adds a “total” label text inside of the chart:

The before screenshots were of two ACEs (Adaptive Card Extensions) set to a Large display format, it’s also possible to select the Medium display format to have a more compact card as the following screenshot:

In the property pane of the sample’s web part, I’ve defined two toggles:

• One toggle changes the display fashion from pie to donut setting a property on the PieChartCardView control.
• One toggle highlights the first three results from the data and turn the other sections into a grayscale. This is not a functionality of the control itself but something to demonstrate how it’s possible to customize the UI.

The property pane looks like the following:

Here you can see how the charts renders when highlighting only the first three data points:

Show me the code

After you’ve created your SPFx solution for an Adaptive Card Extension with the SPFx toolkit extension for VSCode (or using the Yeoman generator), you will have to update the @microsoft/sp-adaptive-card-extension-base import inside the card view.

The import should be updated specifying the PieChartCardView and the IPieDataPoint classes:

import {
  BaseComponentsCardView,
  IDataVisualizationCardViewParameters,
  PieChartCardView,
  IPieDataPoint,
} from '@microsoft/sp-adaptive-card-extension-base';

The PieChartCardView will be used to return a new instance of the class when calling the cardViewParameters method of the card view class of the ACE.

If you’re wondering what’s a CardView you can check here what is an ACE and here how to create your first one.

The IPieDataPoint interface is imported to define the data source to be used by the class instance.

For instance, in the sample project, the data source is defined as following:

const seriesData: IPieDataPoint[] = [
  { x: "A", y: 35 },
  { x: "B", y: 20 },
  { x: "Category C", y: 45 },
  { x: "D", y: 30 },
  { x: "E", y: 75 },
  { x: "F", y: 25 },
];

Each of the data point is composed by the following properties:

• x: which is the value that will be used for the x axis, in this case it will be used as the label to be shown to the user. Remember that the labels with more than 3 characters will be truncated.
• y: this property contains the value used to determine the size of the slice.

The IPieDataPoint interface extends the IDataPoint<T> interface and adds also a couple more properties aside of the x and y, those properties are:

• color: if provided, this will define the color to be used for the data point. The supported strings can be the following:
  • green
  • #00FF00
  • rgba(0,255,0,1)
• showLabel: a boolean value to define if the label of the data point should be visible or not.

Returning to the cardViewParameters method of the card view class, it will return an instance of the PieChartCardView, let’s take a look at the sample solution code:

return PieChartCardView({
  cardBar: {
    componentName: 'cardBar',
    title: strings.Title,
  },
  body: {
    componentName: 'dataVisualization',
    dataVisualizationKind: 'pie',
    isDonut: this.properties.isDonut,
    series: [{
      data: data
    }]
  }
});

The object returned has two main properties, the more interesting one of the two is the body property which contains the actual settings for the chart.

Let’s cover the main properties used to define the chart:

• componentName: this will be set to dataVisualization for all of the ACE charts.
• dataVisualizationKind: define which kind of chart will be rendered, the value for the pie chart will be pie.
• isDonut: is used to define if the pie chart will be shown as a pie or as a donut.
• series: an array of IPieChartSeries object, each of these object has a data property of type IPieDataPoint[]. In the code above the data variable it’s just the before mentioned seriesData property. This can be updated to highlight the first three points if the corresponding web part’s property is set to true.

This is all!

Once you return the PieChartCardView object, SharePoint Framework will handle the chart and the visualization, all you have to do now is to run the solution or publish the package and add the ACE in the Viva Connections dashboard.

Conclusions

The PieChartCardView is a great addition to SharePoint Framework and to your Viva Connections dashboard. The control is very useful, graphically appealing and ready to be used in both the large and medium card setting.

Hope this helps!