Create a Chart Card

Digital Assistant has a built-in Card type that allows you to render interactive charts, by taking a chart definition (as a JavaScript object) provided from a connector.

In this guide we will cover how to create a connector that provides such a definition, how the definition is constructed, and how to create the Card in the Workplace Manager.

Our end goal will be an 'Order Volume' Card, that shows some example data for order volumes by year for a few different countries. The result should be a Card that looks as follows:

1-chart-card

Import the connector

First we will import a proof-of-concept connector from the adenin GitHub repository, that provides some sample services - including a definition for an order volume chart with some dummy data.

Navigate to Development → Manage Spaces → Global → Connectors and select the Import from Git option.

2-import-connector-from-git

Now, copy the url https://github.com/adenin-connectors/poc into the Git repository URL field, and leave the remaining settings as-is and select Import.

3-import-connector-from-git-values

Next, navigate to Content Manager → Service Connectors, and Create New Connector.

4-create-new-connector

In this step we simply need to give the connector a name, title, and to select poc from the Connector Type drop-down and Save.

5-configure-new-connector

Defining the chart

Although the connector we have imported already contains a finished service returning a valid chart, we will now break down how the chart has been defined in order to understand how to create one.

You can view this existing implementation in orderVolumeByCountry.js in the GitHub repository, or in Development → Manage Spaces → Global → Connectors, in the activities folder of the connector you imported.

For the purpose of this guide however, we will take a look at a slightly altered version of the above code, as the connector contains some additional functions to provide data randomization and localization of phrases.

To make it easier to understand, we'll replace these with static values, giving us the following code:

activity.Response.Data = {
  title: 'Order Volume',
  link: 'https://some-link-url.com/',
  linkLabel: 'Sales Dashboard',
  chart: {
    configuration: {
      data: {
        labels: ['UK', 'USA', 'Germany'],
        datasets: [
          {
            label: '2018',
            data: [3750, 2500, 3250]
          },
          {
            label: '2019',
            data: [4250, 3500, 5250]
          }
        ]
      },
      options: {
        title: {
          display: true,
          text: 'Order Volume'
        }
      }
    },
    template: 'bar',
    palette: 'office.Office6'
  }
};

Here, we are as usual defining the connector's response to the request by setting the contents of activity.Response.Data.

We can break the JavaScript object we are returning down into several logical units.

Keys title, link and linkLabel are common to all Cards and simply define the title displayed on the Card, and the link (and link text) for the Card's footer. The key chart is the one of relevance to us for this guide, and it should be noted that this key must be defined, and must be named chart, for the chart Card to be able to read it.

Components of the chart object

The chart object itself can then be broken down into three units. The first unit is the configuration key, whose contents should be a regular Chart.js configuration object, which we will cover shortly. We then have a template key and a palette key. These are shorthand keys that reduce the amount of work required in the main configuration key.

A template defines the chart type, along with some default styling options relating to labelling and axes. The possible values for this key are as follows:

  • bar: Bar chart

    6-chart-bar

  • barStacked: Bar chart where values of multiple series are stacked on top of one another, rather than beside one another

    7-chart-barStacked

  • gauge: Special kind of chart that shows a percentage value on a circular gauge

    8-chart-gauge

  • horizontalBar: Bar chart that goes horizontally from left to right, rather than vertically bottom to top

    9-chart-horizontalBar

  • horizontalBarStacked: Same as a horizontal bar, but stacked

    10-chart-horizontalBarStacked

  • line: Line chart

    11-chart-line

  • pie: Pie chart

    12-chart-pie

  • radar: Radar chart

    13-chart-radar

  • sparkline: Special type of line chart with no axes or labels

    18-chart-sparkline

A palette defines the colors used for the data points - bars, lines, or otherwise, and are applied one color per data series. The available palettes are those from the chartjs-plugin-colorschemes options, where the palette name should be used as-is under the palette key.

Any stylistic settings applied by the template and palette requested can be overidden in the main configuration object using the regular Chart.js configuration properties for those options.

Chart.js configuration object

Chart.js has an extremely versatile set of options for configuring the display of charts, so here we will just cover the essential properties under our configuration key. For further information on more advanced features, please refer to the Chart.js documentation.

The object we have under our configuration key is as follows:

activity.Response.Data.chart.configuration = {
  data: {
    labels: ['UK', 'USA', 'Germany'],
    datasets: [
      {
        label: '2018',
        data: [3750, 2500, 3250]
      },
      {
        label: '2019',
        data: [4250, 3500, 5250]
      }
    ]
  },
  options: {
    title: {
      display: true,
      text: 'Order Volume'
    }
  }
};

There are two sub-keys: data, which contains the chart's display data; and options, which contains stylistic properties.

Under the data key, the labels key accepts an array of strings, which are the labels for the provided data points in order (these will be the labels along the chart x-axis, if default axis positioning is used).

Under datasets, we then have an array of objects, one for each dataset in the chart. Each one has a label string to indicate what that dataset represents (these will become chart legend labels), along with a data key which should contain an array of data values.

Each data value corresponds respectively to one of the data point labels, in order. For example, with data: [3750, 2500, 3250] and labels: ['UK', 'USA', 'Germany'], the value for _UK_ is 3750, the value for USA is 2500, etc.

The datasets key must contain at least one dataset, and each value in the data array must have a corresponding - that is, there must be as many labels as there are values in your largest dataset.

Beyond this, all configuration values are optional, provided that chart.template has been specified and is valid. Otherwise, chart.configuration.type must be set to a Chart.js type value, however we recommend always using one of our template values.

In our example we have set one simple options value, title, so that it displays 'Order Volume'. By default, Chart.js titles are turned off, so we have to set display: true and then define our desired title under the text key. The options key has a large amount of more detailed styling options which are covered in the Chart.js documentation.

Creating the Chart Card in Workplace Manager

Now that we have covered what is going on in the connector to define the chart that appears on the Card, we will add a chart Card to Digital Assistant and connect it to the PoC connector service we imported earlier.

Navigate to Content Manager → Now Cards, and Create New Now Card.

14-create-new-now-card

First, add a name and title to your Card:

15-create-chart-card-item

Next, you need to specify the name of the Card component to use - in this case, we want the built-in at-card-chart/at-card-chart-card component.

16-add-chart-card-component-name

Finally, select the connector and service to use:

  1. Select Service Connectors under Service Type drop-down

  2. Find and select poc in the Connector drop-down

  3. Then, select PoC: orderVolumeByCountry (chart) in the Service drop-down

Now, go to your Digital Assistant, Add or Remove Cards, and add the chart card we've created. Go back to the Digital Assistant Workplace tab, and you should see the following result:

1-chart-card