Introducing the new BarChartCardView 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 BarChartCardView. As the name suggests, this visual control displays a bar chart.

If you’re interested about the other chart control introduced with SPFx version 1.20 you can find a blog post about it here.

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 some sample data so don’t judge the results, it’s just for sample purpose .

This is the resulting UI:

The above is the resulting UI when the ACE is set to Large and it as the maximum space available. The same ACE but with a size of Medium will only show a part of the available results in a more limited space:

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 BarChartCardView and the IDataPoint classes:

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

Those two imports will be used for:

• IDataPoint: defining the data that will be used in the bar chart.
• BarChartCardView: defining the actual ACE content.

Let’s have a quick look at how the IDataPoint interface is used. Starting with the interface definition:

export declare interface IDataPoint<T> {
    x: T;
    y: number;
}

The generic type T defines what type of data will be set to the x property while the y property will define the number associated with that value.

For example one of the data series that I’ve used in the sample solution is as following:

const seriesData1: IDataPoint<string>[] = [
  { x: "C#", y: 12500 },
  { x: "TypeScript", y: 19800 },
  { x: "Go", y: 9000 },
  { x: "Rust", y: 10900 }
];

The x values are strings and in this sample are the labels that will be shown on the x-axis. The y values are numbers and those represents how high the bars will be.

Let’s proceed with the actual code that returns the ACE content so let’s dive into the cardViewParameters method:

public get cardViewParameters(): IDataVisualizationCardViewParameters {
  return BarChartCardView({
    cardBar: {
      componentName: "cardBar",
      title: this.properties.title,
    },
    body: {
      componentName: "dataVisualization",
      dataVisualizationKind: "bar",
      series: [
      {
        data: seriesData1,
    name: "2020",
      },
      {
        data: seriesData2,
    name: "2021",
      },
      {
        data: seriesData3,
    name: "2022",
      }],
    },
  });
}

The BarChartCardView object contains two different properties. The cardBar property contains the component name and the title of the ACE. The property body contains the definition of the bar chart main content, the available properties are:

• componentName: will necessary be dataVisualization.
• dataVisualizationKind: will necessary be bar.
• series: an array of objects where you can specify multiple series of data and also assigning a specific name, this will be used in the chart legenda.

This is it!

After returning the new BarChartCardView object the ACE will render the bar chart.

Conclusions

The version 1.20 of the SharePoint Framework introduced new charts and those additions are awesome, useful and pretty easy to implement. Those new charts are by default already aware of the ACE dimension and are a very useful graphic feature for your Viva Connection Dashboard.

Have fun using those chart ACEs!

Hope this helps!