Introducing LineChartCardView: the new Adaptive Card Extension for SPFx

SharePoint Framework version 1.19 is out with the first preview and this brings a new awesome class for the ACE (Adaptive Card Extensions) development, this class is the LineChartCardView!

To check all the new features and changes of the new SPFx version you can check here.

NB : at the time of writing the SPFx version is the beta 0, something may vary in the final release.

The new LineChartCardView class enables the use of a line chart inside an ACE, both the medium and large sizes are supported but there are a couple of things to keep in mind:

• Currently there is a maximum number of 3 data series that you can specify for each chart , this means that you can have at maximum three lines in the chart.
• If you have more than one data serie and you chose the medium size ACE only the first data serie will be shown.

The result

Starting from the resulting UI of the new ACE template, I chose to create a sample that uses a free stock market API (available here, you can create a free API key with a daily limit here) and shows the trending of some stocks.

As a first example, here is the new card template with only one symbol specified:

And here is the same card but with two symbols specified, I was unlucky as at the time of writing there aren’t any exciting ups and downs but you can see what the result is like:

As said before, but it’s worth mentioning again, you can see only one data serie (the first one specified) in the medium size ACE and the result will be the following:

In the control pane of the sample, which at the time of writing needs a little bit of polishing, there is the ability to set the API key, the symbols that you want to display, the interval of the data and the value to show from the API response:

The code

I will not cover here in detail how I called the API, it’s not the scope of this article, but I want to focus on how to use the LineChartCardView , if you’re interested in all the code and see how I retrieved and bind the data you can check it on GitHub here.

In the new update of the Yeoman SharePoint generator there is a new option for the ACE template to be used and that’s the Data Visualization Card Template (preview) as you can see from the screenshot:

After creating a data visualization card template solution (check here if you never created an ACE solution) you will find that the card view control will contains a sample data serie:

const seriesData : IDataPoint<Date>[] = [
  {
    x: new Date(2024, 1, 1),
    y: 1000
  },
  {
    x: new Date(2024, 2, 1),
    y: 2400
  },
...omitted for brevity
];

Which, as you can see, is of type IDataPoint. The type (Date) specified is the type of the x property, if you want to use another type simply change that value and the values assigned to the x properties.

Proceeding with the actual card view implementation the class definition, in the sample I created, is the following:

export class CardView extends BaseComponentsCardView<
    IBasicChartAceAdaptiveCardExtensionProps,
    IBasicChartAceAdaptiveCardExtensionState,
    IDataVisualizationCardViewParameters>

The first two interfaces passed to the BaseComponentsCardView are the properties and the state of my control, but the third interface, the IDataVisualizationCardViewParameters , is a new one that enables the data handling for the line chart control.

The out of the box current implementation of the card view is:

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

Where the get of the cardViewParameters returns an instance of the new LineChartCardView class and that’s composed by the cardBar at the top, where you can specify the title of the card, and the body where you can specify:

• the componentName, which for the line chart template is dataVisualization.
• the type of the chart, which as by the time of writing only supports the line type.
• the series property which contains an array of maximum 3 objects that contains the data for the current series and the label value to show in the line chart. Each of the objects can also have a property color (i.e. ‘#800080’) defined to display a line with a custom color.

If you want to display more than one line you have to simply define more data serie objects and create a new entry in the array (remember: maximum number is 3).

Noteworthy

I want to point out that the limit of 3 maximum data series is because the type of the series property is MaxThreeTuple. This type is defined as following:

export declare type MaxThreeTuple<T> = [T] | [T, T] | [T, T, T];

So if you want to bind an array keep that in mind that you cannot simply bind the array. I overcome this “problem” using an helper method that returns a bindable object:

private _getTupleFromArray(
 arr: ILineChartSeries<Date>[]): MaxThreeTuple<ILineChartSeries<Date>> {
  switch (arr.length) {
    case 1:
      return [arr[0]];
    case 2:
      return [arr[0], arr[1]];
    case 3:
      return [arr[0], arr[1], arr[2]];
    default:
      throw new Error("Array length must be 1, 2 or 3");
  }
}

Conclusions

The new Data Visualization Card Template is a great new way to implement ACEs which allows the users to have responsive charts in the Viva Connections Dashboard context.

If you’re interested in checking out my sample solution which calls a third-party API and bind the result in the LineChartCardView you can check it here.

Hope this helps!