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.

Name	Type	Default	Description
`type`	`string`		Data source type. `'csv'`, `'json'`, `'jsonl'` and `'sheet'` are supported by default. If not set, the type will be determined based on the file extension in the specified URL. If the URL doesn't have an extension, `'json'` will be set.
`url`	`string`		Data source URL. It must have the same origin as your page, or a response must have a proper CORS header set.

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.

Name	Type	Default	Description
`delimiter`	`string`		Delimiter for values. If not set, the delimiter will be determined based on the file extension in the specified URL. If the URL doesn't have an extension, `','` will be set.
`rowMapping`	`string`	`'dataset'`	Element type to which each row is mapped. more...
`datasetLabels`	`boolean`	`true`	If `true`, the first column (when `rowMapping` is `'dataset'`) or the first row (when `rowMapping` is `'index'`) will be treated as dataset labels. This option is valid when `rowMapping` is `'dataset'` or `'index'`.
`indexLabels`	`boolean`	`true`	If `true`, the first row (when `rowMapping` is `'dataset'`) or the first column (when `rowMapping` is `'index'`) will be treated as index labels. This option is valid when `rowMapping` is `'dataset'` or `'index'`.
`datapointLabels`	`boolean`	`true`	If `true`, the first row will be treated as property labels for Point objects. If `false`, `['_dataset', 'x', 'y', 'r']` will be used. This option is valid only when `rowMapping` is `'datapoint'`.
`datapointLabelMapping`	`object`	`{_dataset: '_dataset', _index: 'x'}`	Key-value pairs for datapoint label mapping. This option is valid only when `rowMapping` is `'datapoint'`. more...

JSON Data Source

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

Name	Type	Default	Description
`rowMapping`	`string`	`'dataset'`	Element type to which each row is mapped. more...
`datasetLabels`	`string`		Simplified JSONPath expression for an array of the dataset labels. This option is valid when `rowMapping` is `'dataset'` or `'index'`. If not specified but each pair of a dataset label and data is represented as a key-value pair in the objects selected by `data`, those keys will be used. more...
`indexLabels`	`string`		Simplified JSONPath expression for an array of the index labels. This option is valid when `rowMapping` is `'dataset'` or `'index'`. If not specified but each pair of an index label and data is represented as a key-value pair in the objects selected by `data`, those keys will be used. more...
`datapointLabelMapping`	`object`	`{_dataset: '_dataset', _index: 'x'}`	Key-value pairs for datapoint label mapping. This option is valid only when `rowMapping` is `'datapoint'`. more...
`data`	`string`		Simplified JSONPath expression for a two-dimensional array of the data. more...

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.

Name	Type	Default	Description
`rowMapping`	`string`	`'index'`	Element type to which each row is mapped. more...
`datasetLabels`	`string`		Simplified JSONPath expression for an array of the dataset labels. This option is valid when `rowMapping` is `'dataset'` or `'index'`. If not specified but each pair of a dataset label and data is represented as a key-value pair in the objects selected by `data`, those keys will be used. more...
`indexLabels`	`string`		Simplified JSONPath expression for an array of the index labels. This option is valid when `rowMapping` is `'dataset'` or `'index'`. If not specified but each pair of an index label and data is represented as a key-value pair in the objects selected by `data`, those keys will be used. more...
`datapointLabelMapping`	`object`	`{_dataset: '_dataset', _index: 'x'}`	Key-value pairs for datapoint label mapping. This option is valid only when `rowMapping` is `'datapoint'`. more...
`data`	`string`		Simplified JSONPath expression for a two-dimensional array of the data. more...

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.

Element	Description
`.` or `[]`	Child/array operator.
`*`	Wildcard. All objects/elements regardless their names.
`[,]`	Union operator results in a combination of children/array indices sets.

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]
    }]
}

Simplified JSONPath Expression	Result
`'labels'`	`['January', 'February', 'March', 'April', 'May']`
`'datasets[*].label'`	`['Temperature', 'Precipitation']`
`'datasets[*].data'`	`[[7, 7, 10, 15, 20], [8.1, 14.9, 41.0, 31.4, 42.6]]`
`'[label[0], datasets[*].data[0]]'`	`['January', [5, 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.

Name	Type	Default	Description
`rowMapping`	`string`	`'dataset'`	Element type to which each row is mapped. more...
`datasetLabels`	`string`		Range for dataset labels (A1 Notation). This option is valid when `rowMapping` is `'dataset'` or `'index'`. If neither `datasetLabels` nor `data` are specified, the first column or row from the auto-detected range will be selected.
`indexLabels`	`string`		Range for index labels (A1 Notation). This option is valid when `rowMapping` is `'dataset'` or `'index'`. If neither `indexLabels` nor `data` are specified, the first row or column from the auto-detected range will be selected.
`datapointLabels`	`string`		Range for property labels for Point objects (A1 Notation). This option is valid only when `rowMapping` is `'datapoint'`. If neither `datapointLabels` nor `data` are specified, the first row from the auto-detected range will be selected. If no data is found, `['_dataset', 'x', 'y', 'r']` will be used.
`datapointLabelMapping`	`object`	`{_dataset: '_dataset', _index: 'x'}`	Key-value pairs for datapoint label mapping. This option is valid only when `rowMapping` is `'datapoint'`. more...
`data`	`string`		Range for the data (A1 Notation). If not specified, the range will be detected automatically.

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.

	January	February	March	April	May
Temperature	7	7	10	15	20
Precipitation	8.1	14.9	41.0	31.4	42.6

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.

	Temperature	Precipitation
January	7	8.1
February	7	14.9
March	10	41.0
April	15	31.4
May	20	42.6

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.

dataset	month	value
Temperature	January	7
Temperature	February	7
Temperature	March	10
Temperature	April	15
Temperature	May	20
Precipitation	January	8.1
Precipitation	February	14.9
Precipitation	March	41.0
Precipitation	April	31.4
Precipitation	May	42.6

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.

Data Source Type	Format	Extension	Description
CSV	CSV	`csv`	RFC 4180-compliant Comma-Separated Values. The default delimiter is `','`.
CSV	TSV	`tsv`	Tab-Separated Values. The default delimiter is `'\t'`.
CSV	PSV	`psv`	Pipe-Separated Values. The default delimiter is `'
JSON	JSON	`json`	JSON
JSON Lines	JSON Lines	`jsonl`	JSON Lines
Sheet	XLSX/XLSM	`xlsx` `xlsm`	Excel 2007+ XML Formats
Sheet	XLSB BIFF12	`xlsb`	Excel 2007+ Binary
Sheet	XML SpreadsheetML	`xml`	Excel 2003-2004 XML Format
Sheet	XLS BIFF8	`xls`	Excel 97-2004
Sheet	XLS BIFF5	`xls`	Excel 5.0/95
Sheet	XLS/XLW BIFF4	`xls` `xlw`	Excel 4.0
Sheet	XLS BIFF3	`xls`	Excel 3.0
Sheet	XLS BIFF2	`xls`	Excel 2.0/2.1
Sheet	CSV/TXT	`csv` `txt`	Delimiter-Separated Values
Sheet	DIF	`dif`	Data Interchange Format
Sheet	SYLK/SLK	`sylk` `slk`	Symbolic Link
Sheet	PRN	`prn`	Lotus Formatted Text
Sheet	TXT	`txt`	UTF-16 Unicode Text
Sheet	ODS	`ods`	OpenDocument Spreadsheet
Sheet	DODS	`fods`	Flat XML ODF Spreadsheet
Sheet	标文通 UOS1/UOS2	`uos`	Uniform Office Format Spreadsheet
Sheet	DBF	`dbf`	dBASE II/III/IV / Visual FoxPro
Sheet	WKS/WK1/WK2/WK3/WK4/123	`wks` `wk1` `wk2` `wk3` `wk4` `123`	Lotus 1-2-3
Sheet	WQ1/WQ2/WB1/WB2/WB3/QPW	`wq1` `wq2` `wb1` `wb2` `wb3` `qpw`	Quattro Pro Spreadsheet
Sheet	HTML	`html` `htm`	HTML Tables
Sheet	ETH	`eth`	EtherCalc Record Format

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 test             # run all tests
gulp test --watch     # run all tests and watch for changes
gulp test --coverage  # run all tests and generate code coverage
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.

Grienauer/chartjs-plugin-datasource