chartjs-plugin-datasource v0.1.0

chartjs-plugin-datasource

Chart.js plugin for automatic data loading

Version 0.1 requires Chart.js 2.6.0 or later. If you use the sheet data source type, SheetJS 0.8.0 or later is also required.

Installation

You can download the latest version of chartjs-plugin-datasource from the GitHub releases.

To install via npm:

npm install chartjs-plugin-datasource --save

To install via bower:

bower install chartjs-plugin-datasource --save

To use CDN:

<script src="https://cdn.jsdelivr.net/npm/chartjs-plugin-datasource"></script>

Usage

chartjs-plugin-datasource can be used with ES6 modules, plain JavaScript and module loaders.

chartjs-plugin-datasource requires Chart.js. If you use the sheet data source type, SheetJS (xlsx) is also required.

First, include Chart.js, xlsx.full.js (optional) and chartjs-plugin-datasource.js to your page. Note that chartjs-plugin-datasource must be loaded after the Chart.js and SheetJS libraries. Once imported, the plugin is available under the global property ChartDataSource.

Then, you need to register the plugin to enable it for all charts in the page.

Chart.plugins.register(ChartDataSource);

Or, you can enable the plugin only for specific charts.

var chart = new Chart(ctx, {
    plugins: [ChartDataSource],
    options: {
        // ...
    }
});

Now, a data source URL can be specified as shown in the example below. By default, each row in a CSV file will be mapped to one dataset, and the first column and the first row will be treated as dataset labels and index labels respectively.

options: {
    plugins: {
        datasource: {
            url: 'sample-dataset.csv'
        }
    }
}

sample-dataset.csv

,January,February,March,April,May,June,July
Temperature,7,7,10,15,20,23,26
Precipitation,8.1,14.9,41.0,31.4,42.6,57.5,36.0

Version 0.1 supports CSV, TSV (Tab-Separated Values), PSV (Pipe-Separated Values), JSON, Excel, OpenDocument and more. More data source types are to be added in the upcoming releases.

Usage in ES6 as module

Import the module as ChartDataSource, and register it in the same way as described above.

import ChartDataSource from 'chartjs-plugin-datasource';

Tutorial and Samples

You can find a tutorial and samples at nagix.github.io/chartjs-plugin-datasource.

Configuration

The plugin options can be changed at 2 different levels and with the following priority:

• per chart: options.plugins.datasource.*
• globally: Chart.defaults.global.plugins.datasource.*

Common options between data source types are listed below.

CSV Data Source

The CSV data source supports delimiter-separated values such as CSV, TSV and PSV. The following options are available in 'csv' data type.

JSON Data Source

The JSON data source supports JSON data. The following options are available in 'json' data type.

JSON Lines Data Source

The JSON Lines data source supports JSON Lines data. The same options are supported in 'jsonl' data type as the JSON data source, but they have different default values.

Simplified JSONPath

This plugin uses a simplified version of JSONPath expression to select an array or two-dimensional array from a JSON document. The top level element in JSON data is an object while that in JSON Lines data is an array. The following elements can be used in an expression.

Below are a sample JSON document, Simplified JSONPath expressions and their results.

{
    "labels": ["January", "February", "March", "April", "May"],
    "datasets": [{
        "label": "Temperature",
        "data": [7, 7, 10, 15, 20]
    }, {
        "label": "Precipitation",
        "data": [8.1, 14.9, 41.0, 31.4, 42.6]
    }]
}

So, the JSONPath expressions in the plugin options will look like below.

options: {
    plugins: {
        datasource: {
            url: 'sample-dataset.json',
            datasetLabels: 'datasets[*].label',
            indexLabels: 'labels',
            data: 'datasets[*].data'
        }
    }
}

A JSON document may consist of nested objects where key-value pairs represent labels and corresponding data. In that case, dataset labels and/or index labels will be retrieved automatically, and there is no need to specify datasetLabels and indexLabels options. The following example will generate the same chart as the previous one.

{
    "Temperature": {
        "January": 7,
        "February": 7,
        "March": 10,
        "April": 15,
        "May": 20
    },
    "Precipitation": {
        "January": 8.1,
        "February": 14.9,
        "March": 41.0,
        "April": 31.4,
        "May": 42.0
    }
}

options: {
    plugins: {
        datasource: {
            url: 'sample-dataset.json',
            data: '*.*'
        }
    }
}

If you want to specify the order of labels explicitly, you can use union operators as shown below.

options: {
    plugins: {
        datasource: {
            url: 'sample-dataset.json',
            data: '[Temperature, Precipitation][January, February, March, April, May]'
        }
    }
}

Sheet Data Source

The sheet data source supports various spreadsheet formats such as Excel and OpenDocument. The following options are available in 'sheet' data type.

A1 Notation

Some options require a range in A1 notation. This is a string like Sheet1!A1:B2 that refers to a group of cells in the spreadsheet. For example, valid ranges are:

• Sheet1!A1:B2 refers to the first two cells in the top two rows of Sheet1.
• Sheet1!A:A refers to all the cells in the first column of Sheet1.
• Sheet1!1:2 refers to the all the cells in the first two rows of Sheet1.
• Sheet1!A5:A refers to all the cells of the first column of Sheet 1, from row 5 onward.
• A1:B2 refers to the first two cells in the top two rows of the first visible sheet.
• Sheet1 refers to all the cells in Sheet1.

If the sheet name has spaces or starts with a bracket, surround the sheet name with single quotes ('), e.g 'Sheet One'!A1:B2. For simplicity, it is safe to always surround the sheet name with single quotes.

Row Mapping

rowMapping indicates an element type to which each row is mapped. Available values are listed below.

• 'dataset'
• 'index'
• 'datapoint'

When each row contains values for one dataset, 'dataset' is used. In many cases, the first column contains dataset labels and the first row contains index labels. Below is an example of dataset-mapped rows.

When each row contains values for one index, 'index' is used. In many cases, the first column contains index labels and the first row contains dataset labels. Below is an example of index-mapped rows.

When each row contains values for one data point, 'datapoint' is used. This type of data formatting is often called Tidy Data. The first row can have datapoint labels. Below is an example of datapoint-mapped rows.

Datapoint Label Mapping

If rowMapping is 'datapoint', datapointLabelMapping can be used to correspond each column to specific datapoint property. It consists of key-value pairs where the key is a property name in Point data used in the line chart, bubble chart and scatter chart, and the value is a datapoint label specified by the datapointLabels option or a property name in case of 'json' and 'jsonl' data sources.

The following keys are used to indicate a special usage of the column.

• _dataset: This column is treated as dataset labels
• _index: This column is treated as index labels

In the following example, the values in the column labeled as 'month' will be mapped to the property x, and the ones in the column labeled as 'value' will be mapped to the property y.

datapointLabelMapping: {
    _dataset: 'dataset',
    _index: 'month',
    x: 'month',
    y: 'value'
}

If the data source type is 'csv', a value can be a number instead of a label text. In that case, it indicates the column index starting with 0. If the data source type is 'sheet', a value can be a column-only A1 notation (for example, 'B' indicates the second column). Below is an example of a CSV data source specifying the column index for each property in Point data.

datapointLabelMapping: {
    _dataset: 0,
    _index: 1,
    x: 1,
    y: 2
}

Supported Data Format

All supported data formats are listed below.

Cross-Origin Resource Sharing (CORS)

If your data source doesn't share the origin (domain, protocol and port) with your page, the HTTP response from the data source must include the right CORS headers to allow cross-site requests. Modern browsers handle the client-side components of cross-origin sharing, including headers and policy enforcement, and no extra code or configuration is required in your page. But, the server at the data source needs to have the proper configuration to handle requests and response headers.

Response HTTP headers must include at least the following header, which indicates that requests from this origin will be allowed.

Access-Control-Allow-Origin: [<scheme>:]<domain>[:<port>]

The value can also be * which means that the resource can be accessed by any domain in a cross-site manner.

Access-Control-Allow-Origin: *

See Cross-Origin Resource Sharing (CORS) for more details.

Building

You first need to install node dependencies (requires Node.js):

npm install

The following commands will then be available from the repository root:

gulp build            # build dist files
gulp build --watch    # build and watch for changes
gulp lint             # perform code linting
gulp package          # create an archive with dist files and samples

License

chartjs-plugin-datasource is available under the MIT license.