diff --git a/docs/configuration/index.md b/docs/configuration/index.md index b689fc328ea..bc75d7162e5 100644 --- a/docs/configuration/index.md +++ b/docs/configuration/index.md @@ -2,6 +2,38 @@ The configuration is used to change how the chart behaves. There are properties to control styling, fonts, the legend, etc. +## Cofiguration object structure + +The top level structure of Chart.js configuration: + +```javascript +const config = { + type: 'line' + data: {} + options: {} + plugins: [] +} +``` + +### type + +Chart type determines the main type of the chart. + +**note** A dataset can override the `type`, this is how mixed charts are constructed. + +### data + +See [Data Structures](../general/data-structures) for details. + +### options + +Majority of the documentation talks about these options. + +### plugins + +Inline plugins can be included in this array. It is an alternative way of adding plugins for single chart (vs registering the plugin globally). +More about plugins in the [developers section](../developers/plugins.md). + ## Global Configuration This concept was introduced in Chart.js 1.0 to keep configuration [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself), and allow for changing options globally across chart types, avoiding the need to specify options for each instance, or the default for a particular chart type. diff --git a/docs/configuration/interactions.md b/docs/configuration/interactions.md index a2b92449583..43dca6dd4c3 100644 --- a/docs/configuration/interactions.md +++ b/docs/configuration/interactions.md @@ -108,6 +108,8 @@ When configuring the interaction with the graph via `interaction`, `hover` or `t The modes are detailed below and how they behave in conjunction with the `intersect` setting. +See how different modes work with the tooltip in [tooltip interactions sample](../samples/tooltip/interactions.md ) + ### point Finds all of the items that intersect the point. @@ -126,7 +128,7 @@ const chart = new Chart(ctx, { ### nearest -Gets the items that are at the nearest distance to the point. The nearest item is determined based on the distance to the center of the chart item (point, bar). You can use the `axis` setting to define which directions are used in distance calculation. If `intersect` is true, this is only triggered when the mouse position intersects an item in the graph. This is very useful for combo charts where points are hidden behind bars. +Gets the items that are at the nearest distance to the point. The nearest item is determined based on the distance to the center of the chart item (point, bar). You can use the `axis` setting to define which coordinates are considered in distance calculation. If `intersect` is true, this is only triggered when the mouse position intersects an item in the graph. This is very useful for combo charts where points are hidden behind bars. ```javascript const chart = new Chart(ctx, { diff --git a/docs/general/data-structures.md b/docs/general/data-structures.md index 1a62fc02724..65b8775510e 100644 --- a/docs/general/data-structures.md +++ b/docs/general/data-structures.md @@ -8,8 +8,13 @@ The provides labels can be of the type string or number to be rendered correctly ## Primitive[] ```javascript -data: [20, 10], -labels: ['a', 'b'] +type: 'bar', +data: { + datasets: [{ + data: [20, 10], + }], + labels: ['a', 'b'] +} ``` When the `data` is an array of numbers, values from `labels` array at the same index are used for the index axis (`x` for vertical, `y` for horizontal charts). @@ -17,15 +22,30 @@ When the `data` is an array of numbers, values from `labels` array at the same i ## Object[] ```javascript -data: [{x: 10, y: 20}, {x: 15, y: null}, {x: 20, y: 10}] +type: 'line', +data: { + datasets: [{ + data: [{x: 10, y: 20}, {x: 15, y: null}, {x: 20, y: 10}] + }] +} ``` ```javascript -data: [{x:'2016-12-25', y:20}, {x:'2016-12-26', y:10}] +type: 'line', +data: { + datasets: [{ + data: [{x:'2016-12-25', y:20}, {x:'2016-12-26', y:10}] + }] +} ``` ```javascript -data: [{x:'Sales', y:20}, {x:'Revenue', y:10}] +type: 'bar', +data: { + datasets: [{ + data: [{x:'Sales', y:20}, {x:'Revenue', y:10}] + }] +} ``` This is also the internal format used for parsed data. In this mode, parsing can be disabled by specifying `parsing: false` at chart options or dataset. If parsing is disabled, data must be sorted and in the formats the associated chart type and scales use internally. @@ -68,9 +88,14 @@ options: { ## Object ```javascript +type: 'pie', data: { - January: 10, - February: 20 + datasets: [{ + data: { + January: 10, + February: 20 + } + }] } ``` diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 25d944a206f..ea8ef96f21d 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -18,6 +18,50 @@ Now that we have a canvas we can use, we need to include Chart.js in our page. Now, we can create a chart. We add a script to our page: +```html + +``` + +Finally, render the chart using our configuration: + +```html + +``` + +It's that easy to get started using Chart.js! From here you can explore the many options that can help you customise your charts with scales, tooltips, labels, colors, custom actions, and much more. + +Here the sample above is presented with our sample block: + ```js chart-editor // const labels = [ @@ -53,21 +97,10 @@ module.exports = { }; ``` -Finally, render the chart using our configuration: - -```html - -``` - -It's that easy to get started using Chart.js! From here you can explore the many options that can help you customise your charts with scales, tooltips, labels, colors, custom actions, and much more. +:::tip Note +As you can see, some of the boilerplate needed is not visible in our sample blocks, as the samples focus on the configuration options. +::: -All our examples are [available online](/samples/) but you can also download the `Chart.js.zip` archive attached to every [release](https://github.com/chartjs/Chart.js/releases) to experiment with our samples locally from the `/samples` folder. +All our examples are [available online](/samples/). To run the samples locally you first have to install all the necessary packages using the `npm ci` command, after this you can run `npm run docs:dev` to build the documentation. As soon as the build is done, you can go to [http://localhost:8080/samples/](http://localhost:8080/samples/) to see the samples. diff --git a/docs/samples/tooltip/interactions.md b/docs/samples/tooltip/interactions.md index 2ee3deca891..b28bbb46f68 100644 --- a/docs/samples/tooltip/interactions.md +++ b/docs/samples/tooltip/interactions.md @@ -30,13 +30,29 @@ const actions = [ } }, { - name: 'Mode: nearest', + name: 'Mode: nearest, axis: xy', handler(chart) { chart.options.interaction.axis = 'xy'; chart.options.interaction.mode = 'nearest'; chart.update(); } }, + { + name: 'Mode: nearest, axis: x', + handler(chart) { + chart.options.interaction.axis = 'x'; + chart.options.interaction.mode = 'nearest'; + chart.update(); + } + }, + { + name: 'Mode: nearest, axis: y', + handler(chart) { + chart.options.interaction.axis = 'y'; + chart.options.interaction.mode = 'nearest'; + chart.update(); + } + }, { name: 'Mode: x', handler(chart) { @@ -98,8 +114,8 @@ const config = { title: { display: true, text: (ctx) => { - const {intersect, mode} = ctx.chart.options.interaction; - return 'Mode: ' + mode + ', intersect: ' + intersect; + const {axis = 'xy', intersect, mode} = ctx.chart.options.interaction; + return 'Mode: ' + mode + ', axis: ' + axis + ', intersect: ' + intersect; } }, } @@ -111,4 +127,4 @@ module.exports = { actions: actions, config: config, }; -``` \ No newline at end of file +```