Create a Data Visualization Adaptive Card Extension

Creating a Data Visualization Adaptive Card Extension (ACE) for SharePoint Online using the SharePoint Framework (SPFx) involves building a custom ACE component to display visual data in the form of charts or other visual elements. Line chart data visualization type was released as part of the SPFx 1.19 release.

Setting Up the SPFx Project for Data Visualization ACE

Step 1. Set up the SPFx project.

yo @microsoft/sharepoint

When prompted, enter the following values (select the default option for all other prompts).

• What is your solution name?: data-visualization-tutorial
• Which type of client-side component to create?: Adaptive Card Extension
• Which template do you want to use?: Data Visualization Card Template
• What is your Adaptive Card Extension name?: DataVisualization

Step 2. Open the following file: ./src/adaptiveCardExtensions/dataVisualization/cardView/CardView.ts. Add the following code to it.

const seriesData: IDataPoint<Date>[] = [
  { x: new Date(2024, 1, 1), y: 1000 },
  { x: new Date(2024, 2, 1), y: 2400 },
  { x: new Date(2024, 3, 1), y: 2000 },
  { x: new Date(2024, 4, 1), y: 2900 },
  { x: new Date(2024, 5, 1), y: 3000 },
  { x: new Date(2024, 6, 1), y: 3100 }
];

export class CardView extends BaseComponentsCardView<..> {
  public get cardViewParameters(): IDataVisualizationCardViewParameters {
    return LineChartCardView({
      cardBar: {
        componentName: 'cardBar',
        title: this.properties.title
      },
      body: {
        componentName: 'dataVisualization',
        dataVisualizationKind: 'line',
        series: [
          {
            data: seriesData,
            lastDataPointLabel: '3.1K'
          }
        ]
      }
    });
  }
}

Step 3. Run the "gulp serve" command to run the code in Workbench or you can deploy it on SharePoint with the following commands.

gulp bundle --ship
gulp package-solution --ship

This will create a line chart on an adaptive card that looks like the following image.

Step 4. The ACE dataVisualization component supports multiple series lines in the chart.

To add multiple lines to the chart, add other entries to the body, series array on the LineChartCardView object in the Card View.

Example. We can have multiple objects inside a series data array, which we have created in step 2.

Open the ./src/adaptiveCardExtensions/dataVisualization/cardView/CardView.ts. Add the following code to it.

// Sample Data
const seriesData: IDataPoint<Date>[] = [
  { x: new Date(2024, 1, 1), y: 1000 },
  { x: new Date(2024, 2, 1), y: 2400 },
  { x: new Date(2024, 3, 1), y: 2000 },
  { x: new Date(2024, 4, 1), y: 2900 },
  { x: new Date(2024, 5, 1), y: 3000 },
  { x: new Date(2024, 6, 1), y: 3100 }
];

const seriesData2: IDataPoint<Date>[] = [
  { x: new Date(2024, 1, 1), y: 600 },
  { x: new Date(2024, 2, 1), y: 1200 },
  { x: new Date(2024, 3, 1), y: 3200 },
  { x: new Date(2024, 4, 1), y: 2800 },
  { x: new Date(2024, 5, 1), y: 3600 },
  { x: new Date(2024, 6, 1), y: 4500 }
];

const seriesData3: IDataPoint<Date>[] = [
  { x: new Date(2024, 1, 1), y: 5200 },
  { x: new Date(2024, 2, 1), y: 1000 },
  { x: new Date(2024, 3, 1), y: 1800 },
  { x: new Date(2024, 4, 1), y: 2900 },
  { x: new Date(2024, 5, 1), y: 600 },
  { x: new Date(2024, 6, 1), y: 400 }
];

export class CardView extends BaseComponentsCardView<
  IRecentSalesAdaptiveCardExtensionProps,
  IRecentSalesAdaptiveCardExtensionState,
  IDataVisualizationCardViewParameters
> {
  public get cardViewParameters(): IDataVisualizationCardViewParameters {
    return LineChartCardView({
      cardBar: {
        componentName: 'cardBar',
        title: this.properties.title
      },
      body: {
        componentName: 'dataVisualization',
        dataVisualizationKind: 'line',
        series: [
          {
            data: seriesData,
            lastDataPointLabel: '3.1K'
          },
          {
            data: seriesData2,
            lastDataPointLabel: '4.5K',
            color: '#800080'
          },
          {
            data: seriesData3,
            lastDataPointLabel: '0.4K',
            color: '#01CBAE'
          }
        ]
      }
    });
  }

  public get onCardSelection(): IQuickViewCardAction | IExternalLinkCardAction | undefined {
    return {
      type: 'QuickView',
      parameters: { view: QUICK_VIEW_REGISTRY_ID }
    };
  }
}

When it is deployed or when we run it in the workbench, the output looks like the following image.

Note. Support for more chart types: The SharePoint Framework v1.20 introduces support for newer chart types, enabling developers to create visually appealing data visualizations like bar, pie, and donut charts.

Bar Chart

Series data array and other code changes are given below to show the data in the Bar chart visualization.

// Sample Data
const seriesData: IDataPoint<string>[] = [
  { x: "Jan", y: 12986 },
  { x: "Feb", y: 13424 },
  { x: "Mar", y: 17118 },
  { x: "Apr", y: 14017 },
  { x: "May", y: 11245 }
];

const seriesData2: IDataPoint<string>[] = [
  { x: "Jan", y: 19631 },
  { x: "Feb", y: 19905 },
  { x: "Mar", y: 17098 },
  { x: "Apr", y: 11918 },
  { x: "May", y: 10357 }
];

const seriesData3: IDataPoint<string>[] = [
  { x: "Jan", y: 19762 },
  { x: "Feb", y: 12926 },
  { x: "Mar", y: 17670 },
  { x: "Apr", y: 19055 },
  { x: "May", y: 18142 }
];

export class CardView extends BaseComponentsCardView<
  IDataVisualizationAdaptiveCardExtensionProps,
  IDataVisualizationAdaptiveCardExtensionState,
  IDataVisualizationCardViewParameters
> {
  public get cardViewParameters(): IDataVisualizationCardViewParameters {
    return BarChartCardView({
      cardBar: {
        componentName: 'cardBar',
        title: this.properties.title
      },
      body: {
        componentName: 'dataVisualization',
        dataVisualizationKind: 'bar',
        series: [
          {
            data: seriesData,
            name: 'Africa'
          },
          {
            data: seriesData2,
            name: 'Asia'
          },
          {
            data: seriesData3,
            name: 'Europe'
          }
        ]
      }
    });
  }
}

When we run it, what will the output look like?

 

In the same way, we can have a Pie/Donut chart too. We just need to change the data in series data array values, and the code inside public gets cardViewParameters().