From 63b2004763837c58d905274447c9400fbbf10c6d Mon Sep 17 00:00:00 2001 From: etimberg Date: Thu, 22 Dec 2016 22:19:29 -0500 Subject: [PATCH] Moved docs over to new folder structure. Removed old doc files. Fixed #3547, #3490, and #3118 while at it. --- docs/00-Getting-Started.md | 126 ------- docs/01-Chart-Configuration.md | 518 -------------------------- docs/02-Scales.md | 369 ------------------ docs/03-Line-Chart.md | 187 ---------- docs/04-Bar-Chart.md | 174 --------- docs/05-Radar-Chart.md | 125 ------- docs/06-Polar-Area-Chart.md | 109 ------ docs/07-Pie-Doughnut-Chart.md | 115 ------ docs/08-Bubble-Chart.md | 100 ----- docs/09-Advanced.md | 467 ----------------------- docs/10-Notes.md | 115 ------ docs/axes/README.md | 112 ++++++ docs/axes/cartesian/README.md | 93 +++++ docs/axes/cartesian/category.md | 38 ++ docs/axes/cartesian/linear.md | 124 ++++++ docs/axes/cartesian/logarithmic.md | 43 +++ docs/axes/cartesian/time.md | 120 ++++++ docs/axes/labelling.md | 63 ++++ docs/axes/radial/README.md | 5 + docs/axes/radial/linear.md | 211 +++++++++++ docs/axes/styling.md | 104 ++++++ docs/charts/README.md | 3 + docs/charts/bar.md | 218 +++++++++++ docs/charts/bubble.md | 81 ++++ docs/charts/doughnut.md | 130 +++++++ docs/charts/line.md | 214 +++++++++++ docs/charts/mixed.md | 37 ++ docs/charts/polar.md | 112 ++++++ docs/charts/radar.md | 151 ++++++++ docs/charts/scatter.md | 49 +++ docs/configuration/README.md | 34 ++ docs/configuration/animations.md | 116 ++++++ docs/configuration/elements/README.md | 18 + docs/configuration/elements/arc.md | 18 + docs/configuration/elements/bar.md | 29 ++ docs/configuration/elements/line.md | 58 +++ docs/configuration/elements/point.md | 43 +++ docs/configuration/layout.md | 28 ++ docs/configuration/legend.md | 220 +++++++++++ docs/configuration/title.md | 67 ++++ docs/configuration/tooltip.md | 304 +++++++++++++++ docs/developers/README.md | 22 ++ docs/developers/api.md | 143 +++++++ docs/developers/axes.md | 131 +++++++ docs/developers/charts.md | 76 ++++ docs/developers/contributing.md | 34 ++ docs/developers/plugins/README.md | 9 + docs/developers/plugins/api.md | 186 +++++++++ docs/developers/plugins/registry.md | 11 + docs/general/README.md | 1 + docs/general/colors.md | 49 +++ docs/general/fonts.md | 41 ++ docs/general/interactions/README.md | 18 + docs/general/interactions/events.md | 29 ++ docs/general/interactions/modes.md | 104 ++++++ docs/general/responsive.md | 49 +++ docs/getting-started/README.md | 43 +++ docs/getting-started/installation.md | 41 ++ docs/getting-started/integration.md | 34 ++ docs/getting-started/usage.md | 65 ++++ docs/notes/README.md | 1 + docs/notes/comparison.md | 32 ++ docs/notes/extensions.md | 26 ++ docs/notes/license.md | 3 + 64 files changed, 3991 insertions(+), 2405 deletions(-) delete mode 100644 docs/00-Getting-Started.md delete mode 100644 docs/01-Chart-Configuration.md delete mode 100644 docs/02-Scales.md delete mode 100644 docs/03-Line-Chart.md delete mode 100644 docs/04-Bar-Chart.md delete mode 100644 docs/05-Radar-Chart.md delete mode 100644 docs/06-Polar-Area-Chart.md delete mode 100644 docs/07-Pie-Doughnut-Chart.md delete mode 100644 docs/08-Bubble-Chart.md delete mode 100644 docs/09-Advanced.md delete mode 100644 docs/10-Notes.md create mode 100644 docs/axes/README.md create mode 100644 docs/axes/cartesian/README.md create mode 100644 docs/axes/cartesian/category.md create mode 100644 docs/axes/cartesian/linear.md create mode 100644 docs/axes/cartesian/logarithmic.md create mode 100644 docs/axes/cartesian/time.md create mode 100644 docs/axes/labelling.md create mode 100644 docs/axes/radial/README.md create mode 100644 docs/axes/radial/linear.md create mode 100644 docs/axes/styling.md create mode 100644 docs/charts/README.md create mode 100644 docs/charts/bar.md create mode 100644 docs/charts/bubble.md create mode 100644 docs/charts/doughnut.md create mode 100644 docs/charts/line.md create mode 100644 docs/charts/mixed.md create mode 100644 docs/charts/polar.md create mode 100644 docs/charts/radar.md create mode 100644 docs/charts/scatter.md create mode 100644 docs/configuration/README.md create mode 100644 docs/configuration/animations.md create mode 100644 docs/configuration/elements/README.md create mode 100644 docs/configuration/elements/arc.md create mode 100644 docs/configuration/elements/bar.md create mode 100644 docs/configuration/elements/line.md create mode 100644 docs/configuration/elements/point.md create mode 100644 docs/configuration/layout.md create mode 100644 docs/configuration/legend.md create mode 100644 docs/configuration/title.md create mode 100644 docs/configuration/tooltip.md create mode 100644 docs/developers/README.md create mode 100644 docs/developers/api.md create mode 100644 docs/developers/axes.md create mode 100644 docs/developers/charts.md create mode 100644 docs/developers/contributing.md create mode 100644 docs/developers/plugins/README.md create mode 100644 docs/developers/plugins/api.md create mode 100644 docs/developers/plugins/registry.md create mode 100644 docs/general/README.md create mode 100644 docs/general/colors.md create mode 100644 docs/general/fonts.md create mode 100644 docs/general/interactions/README.md create mode 100644 docs/general/interactions/events.md create mode 100644 docs/general/interactions/modes.md create mode 100644 docs/general/responsive.md create mode 100644 docs/getting-started/README.md create mode 100644 docs/getting-started/installation.md create mode 100644 docs/getting-started/integration.md create mode 100644 docs/getting-started/usage.md create mode 100644 docs/notes/README.md create mode 100644 docs/notes/comparison.md create mode 100644 docs/notes/extensions.md create mode 100644 docs/notes/license.md diff --git a/docs/00-Getting-Started.md b/docs/00-Getting-Started.md deleted file mode 100644 index 81e03c0a986..00000000000 --- a/docs/00-Getting-Started.md +++ /dev/null @@ -1,126 +0,0 @@ ---- -title: Getting started -anchor: getting-started ---- - -### Download Chart.js - -You can download the latest version of [Chart.js on GitHub](https://github.com/chartjs/Chart.js/releases/latest) or just use these [Chart.js CDN](https://cdnjs.com/libraries/Chart.js) links. -If you download or clone the repository, you must run `gulp build` to generate the dist files. Chart.js no longer comes with prebuilt release versions, so an alternative option to downloading the repo is **strongly** advised. - -### Installation - -#### npm - -```bash -npm install chart.js --save -``` - -#### bower - -```bash -bower install chart.js --save -``` - -### Selecting the Correct Build - -Chart.js provides two different builds that are available for your use. The `Chart.js` and `Chart.min.js` files include Chart.js and the accompanying color parsing library. If this version is used and you require the use of the time axis, [Moment.js](http://momentjs.com/) will need to be included before Chart.js. - -The `Chart.bundle.js` and `Chart.bundle.min.js` builds include Moment.js in a single file. This version should be used if you require time axes and want a single file to include, select this version. Do not use this build if your application already includes Moment.js. If you do, Moment.js will be included twice, increasing the page load time and potentially introducing version issues. - -### Usage - -To import Chart.js using an old-school script tag: - -```html - - -``` - -To import Chart.js using an awesome module loader: - -```javascript - -// Using CommonJS -var Chart = require('chart.js') -var myChart = new Chart({...}) - -// ES6 -import Chart from 'chart.js' -let myChart = new Chart({...}) - -// Using requirejs -require(['path/to/Chartjs'], function(Chart){ - var myChart = new Chart({...}) -}) - -``` - -### Creating a Chart - -To create a chart, we need to instantiate the `Chart` class. To do this, we need to pass in the node, jQuery instance, or 2d context of the canvas of where we want to draw the chart. Here's an example. - -```html - -``` - -```javascript -// Any of the following formats may be used -var ctx = document.getElementById("myChart"); -var ctx = document.getElementById("myChart").getContext("2d"); -var ctx = $("#myChart"); -var ctx = "myChart"; -``` - -Once you have the element or context, you're ready to instantiate a pre-defined chart-type or create your own! - -The following example instantiates a bar chart showing the number of votes for different colors and the y-axis starting at 0. - -```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. - -There are many examples of Chart.js that are available in the `/samples` folder of `Chart.js.zip` that is attatched to every [release](https://github.com/chartjs/Chart.js/releases). diff --git a/docs/01-Chart-Configuration.md b/docs/01-Chart-Configuration.md deleted file mode 100644 index 883d74ec009..00000000000 --- a/docs/01-Chart-Configuration.md +++ /dev/null @@ -1,518 +0,0 @@ ---- -title: Chart Configuration -anchor: chart-configuration ---- - -Chart.js provides a number of options for changing the behaviour of created charts. These configuration options can be changed on a per chart basis by passing in an options object when creating the chart. Alternatively, the global configuration can be changed which will be used by all charts created after that point. - -### Chart Data - -To display data, the chart must be passed a data object that contains all of the information needed by the chart. The data object can contain the following parameters - -Name | Type | Description ---- | --- | ---- -datasets | Array[object] | Contains data for each dataset. See the documentation for each chart type to determine the valid options that can be attached to the dataset -labels | Array[string] | Optional parameter that is used with the [category axis](#scales-category-scale). -xLabels | Array[string] | Optional parameter that is used with the category axis and is used if the axis is horizontal -yLabels | Array[string] | Optional parameter that is used with the category axis and is used if the axis is vertical - -### Creating a Chart with Options - -To create a chart with configuration options, simply pass an object containing your configuration to the constructor. In the example below, a line chart is created and configured to not be responsive. - -```javascript -var chart = new Chart(ctx, { - type: 'line', - data: data, - options: { - responsive: false - } -}); -``` - -### 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. - -Chart.js merges the options object passed to the chart with the global configuration using chart type defaults and scales defaults appropriately. This way you can be as specific as you would like in your individual chart configuration, while still changing the defaults for all chart types where applicable. The global general options are defined in `Chart.defaults.global`. The defaults for each chart type are discussed in the documentation for that chart type. - -The following example would set the hover mode to 'nearest' for all charts where this was not overridden by the chart type defaults or the options passed to the constructor on creation. - -```javascript -Chart.defaults.global.hover.mode = 'nearest'; - -// Hover mode is set to nearest because it was not overridden here -var chartHoverModeNearest = new Chart(ctx, { - type: 'line', - data: data, -}); - -// This chart would have the hover mode that was passed in -var chartDifferentHoverMode = new Chart(ctx, { - type: 'line', - data: data, - options: { - hover: { - // Overrides the global setting - mode: 'index' - } - } -}) -``` - -#### Global Font Settings - -There are 4 special global settings that can change all of the fonts on the chart. These options are in `Chart.defaults.global`. - -Name | Type | Default | Description ---- | --- | --- | --- -defaultFontColor | Color | '#666' | Default font color for all text -defaultFontFamily | String | "'Helvetica Neue', 'Helvetica', 'Arial', sans-serif" | Default font family for all text -defaultFontSize | Number | 12 | Default font size (in px) for text. Does not apply to radialLinear scale point labels -defaultFontStyle | String | 'normal' | Default font style. Does not apply to tooltip title or footer. Does not apply to chart title - -### Common Chart Configuration - -The following options are applicable to all charts. The can be set on the [global configuration](#chart-configuration-global-configuration), or they can be passed to the chart constructor. - -Name | Type | Default | Description ---- | --- | --- | --- -responsive | Boolean | true | Resizes the chart canvas when its container does. -responsiveAnimationDuration | Number | 0 | Duration in milliseconds it takes to animate to new size after a resize event. -maintainAspectRatio | Boolean | true | Maintain the original canvas aspect ratio `(width / height)` when resizing -events | Array[String] | `["mousemove", "mouseout", "click", "touchstart", "touchmove", "touchend"]` | Events that the chart should listen to for tooltips and hovering -onClick | Function | null | Called if the event is of type 'mouseup' or 'click'. Called in the context of the chart and passed the event and an array of active elements -legendCallback | Function | ` function (chart) { }` | Function to generate a legend. Receives the chart object to generate a legend from. Default implementation returns an HTML string. -onResize | Function | null | Called when a resize occurs. Gets passed two arguments: the chart instance and the new size. - -### Layout Configuration - -The layout configuration is passed into the `options.layout` namespace. The global options for the chart layout is defined in `Chart.defaults.global.layout`. - -Name | Type | Default | Description ---- | --- | --- | --- -padding | Number or Object | 0 | The padding to add inside the chart. If this value is a number, it is applied to all sides of the chart (left, top, right, bottom). If this value is an object, the `left` property defines the left padding. Similarly the `right`, `top`, and `bottom` properties can also be specified. - - -### Title Configuration - -The title configuration is passed into the `options.title` namespace. The global options for the chart title is defined in `Chart.defaults.global.title`. - -Name | Type | Default | Description ---- | --- | --- | --- -display | Boolean | false | Display the title block -position | String | 'top' | Position of the title. Possible values are 'top', 'left', 'bottom' and 'right'. -fullWidth | Boolean | true | Marks that this box should take the full width of the canvas (pushing down other boxes) -fontSize | Number | 12 | Font size inherited from global configuration -fontFamily | String | "'Helvetica Neue', 'Helvetica', 'Arial', sans-serif" | Font family inherited from global configuration -fontColor | Color | "#666" | Font color inherited from global configuration -fontStyle | String | 'bold' | Font styling of the title. -padding | Number | 10 | Number of pixels to add above and below the title text -text | String | '' | Title text - -#### Example Usage - -The example below would enable a title of 'Custom Chart Title' on the chart that is created. - -```javascript -var chart = new Chart(ctx, { - type: 'line', - data: data, - options: { - title: { - display: true, - text: 'Custom Chart Title' - } - } -}) -``` - -### Legend Configuration - -The legend configuration is passed into the `options.legend` namespace. The global options for the chart legend is defined in `Chart.defaults.global.legend`. - -Name | Type | Default | Description ---- | --- | --- | --- -display | Boolean | true | Is the legend displayed -position | String | 'top' | Position of the legend. Possible values are 'top', 'left', 'bottom' and 'right'. -fullWidth | Boolean | true | Marks that this box should take the full width of the canvas (pushing down other boxes) -onClick | Function | `function(event, legendItem) {}` | A callback that is called when a 'click' event is registered on top of a label item -onHover | Function | `function(event, legendItem) {}` | A callback that is called when a 'mousemove' event is registered on top of a label item -labels |Object|-| See the [Legend Label Configuration](#chart-configuration-legend-label-configuration) section below. -reverse | Boolean | false | Legend will show datasets in reverse order - -#### Legend Label Configuration - -The legend label configuration is nested below the legend configuration using the `labels` key. - -Name | Type | Default | Description ---- | --- | --- | --- -boxWidth | Number | 40 | Width of coloured box -fontSize | Number | 12 | Font size inherited from global configuration -fontStyle | String | "normal" | Font style inherited from global configuration -fontColor | Color | "#666" | Font color inherited from global configuration -fontFamily | String | "'Helvetica Neue', 'Helvetica', 'Arial', sans-serif" | Font family inherited from global configuration -padding | Number | 10 | Padding between rows of colored boxes -generateLabels: | Function | `function(chart) { }` | Generates legend items for each thing in the legend. Default implementation returns the text + styling for the color box. See [Legend Item](#chart-configuration-legend-item-interface) for details. -filter | Function | null | Filters legend items out of the legend. Receives 2 parameters, a [Legend Item](#chart-configuration-legend-item-interface) and the chart data -usePointStyle | Boolean | false | Label style will match corresponding point style (size is based on fontSize, boxWidth is not used in this case). - -#### Legend Item Interface - -Items passed to the legend `onClick` function are the ones returned from `labels.generateLabels`. These items must implement the following interface. - -```javascript -{ - // Label that will be displayed - text: String, - - // Fill style of the legend box - fillStyle: Color, - - // If true, this item represents a hidden dataset. Label will be rendered with a strike-through effect - hidden: Boolean, - - // For box border. See https://developer.mozilla.org/en/docs/Web/API/CanvasRenderingContext2D/lineCap - lineCap: String, - - // For box border. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash - lineDash: Array[Number], - - // For box border. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset - lineDashOffset: Number, - - // For box border. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin - lineJoin: String, - - // Width of box border - lineWidth: Number, - - // Stroke style of the legend box - strokeStyle: Color - - // Point style of the legend box (only used if usePointStyle is true) - pointStyle: String -} -``` - -#### Example - -The following example will create a chart with the legend enabled and turn all of the text red in color. - -```javascript -var chart = new Chart(ctx, { - type: 'bar', - data: data, - options: { - legend: { - display: true, - labels: { - fontColor: 'rgb(255, 99, 132)' - } - } -} -}); -``` - -### Tooltip Configuration - -The tooltip configuration is passed into the `options.tooltips` namespace. The global options for the chart tooltips is defined in `Chart.defaults.global.tooltips`. - -Name | Type | Default | Description ---- | --- | --- | --- -enabled | Boolean | true | Are tooltips enabled -custom | Function | null | See [section](#advanced-usage-external-tooltips) below -mode | String | 'nearest' | Sets which elements appear in the tooltip. See [Interaction Modes](#interaction-modes) for details -intersect | Boolean | true | if true, the tooltip mode applies only when the mouse position intersects with an element. If false, the mode will be applied at all times. -position | String | 'average' | The mode for positioning the tooltip. 'average' mode will place the tooltip at the average position of the items displayed in the tooltip. 'nearest' will place the tooltip at the position of the element closest to the event position. New modes can be defined by adding functions to the Chart.Tooltip.positioners map. -itemSort | Function | undefined | Allows sorting of [tooltip items](#chart-configuration-tooltip-item-interface). Must implement at minimum a function that can be passed to [Array.prototype.sort](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort). This function can also accept a third parameter that is the data object passed to the chart. -filter | Function | undefined | Allows filtering of [tooltip items](#chart-configuration-tooltip-item-interface). Must implement at minimum a function that can be passed to [Array.prototype.filter](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Array/filter). This function can also accept a second parameter that is the data object passed to the chart. -backgroundColor | Color | 'rgba(0,0,0,0.8)' | Background color of the tooltip -titleFontFamily | String | "'Helvetica Neue', 'Helvetica', 'Arial', sans-serif" | Font family for tooltip title inherited from global font family -titleFontSize | Number | 12 | Font size for tooltip title inherited from global font size -titleFontStyle | String | "bold" | -titleFontColor | Color | "#fff" | Font color for tooltip title -titleSpacing | Number | 2 | Spacing to add to top and bottom of each title line. -titleMarginBottom | Number | 6 | Margin to add on bottom of title section -bodyFontFamily | String | "'Helvetica Neue', 'Helvetica', 'Arial', sans-serif" | Font family for tooltip items inherited from global font family -bodyFontSize | Number | 12 | Font size for tooltip items inherited from global font size -bodyFontStyle | String | "normal" | -bodyFontColor | Color | "#fff" | Font color for tooltip items. -bodySpacing | Number | 2 | Spacing to add to top and bottom of each tooltip item -footerFontFamily | String | "'Helvetica Neue', 'Helvetica', 'Arial', sans-serif" | Font family for tooltip footer inherited from global font family. -footerFontSize | Number | 12 | Font size for tooltip footer inherited from global font size. -footerFontStyle | String | "bold" | Font style for tooltip footer. -footerFontColor | Color | "#fff" | Font color for tooltip footer. -footerSpacing | Number | 2 | Spacing to add to top and bottom of each footer line. -footerMarginTop | Number | 6 | Margin to add before drawing the footer -xPadding | Number | 6 | Padding to add on left and right of tooltip -yPadding | Number | 6 | Padding to add on top and bottom of tooltip -caretSize | Number | 5 | Size, in px, of the tooltip arrow -cornerRadius | Number | 6 | Radius of tooltip corner curves -multiKeyBackground | Color | "#fff" | Color to draw behind the colored boxes when multiple items are in the tooltip -displayColors | Boolean | true | if true, color boxes are shown in the tooltip -callbacks | Object | | See the [callbacks section](#chart-configuration-tooltip-callbacks) below - -#### Tooltip Callbacks - -The tooltip label configuration is nested below the tooltip configuration using the `callbacks` key. The tooltip has the following callbacks for providing text. For all functions, 'this' will be the tooltip object created from the Chart.Tooltip constructor. - -All functions are called with the same arguments: a [tooltip item](#chart-configuration-tooltip-item-interface) and the data object passed to the chart. All functions must return either a string or an array of strings. Arrays of strings are treated as multiple lines of text. - -Callback | Arguments | Description ---- | --- | --- -beforeTitle | `Array[tooltipItem], data` | Text to render before the title -title | `Array[tooltipItem], data` | Text to render as the title -afterTitle | `Array[tooltipItem], data` | Text to render after the title -beforeBody | `Array[tooltipItem], data` | Text to render before the body section -beforeLabel | `tooltipItem, data` | Text to render before an individual label -label | `tooltipItem, data` | Text to render for an individual item in the tooltip -labelColor | `tooltipItem, chart` | Returns the colors to render for the tooltip item. Return as an object containing two parameters: `borderColor` and `backgroundColor`. -afterLabel | `tooltipItem, data` | Text to render after an individual label -afterBody | `Array[tooltipItem], data` | Text to render after the body section -beforeFooter | `Array[tooltipItem], data` | Text to render before the footer section -footer | `Array[tooltipItem], data` | Text to render as the footer -afterFooter | `Array[tooltipItem], data` | Text to render after the footer section -dataPoints | `Array[tooltipItem]` | List of matching point informations. - -#### Tooltip Item Interface - -The tooltip items passed to the tooltip callbacks implement the following interface. - -```javascript -{ - // X Value of the tooltip as a string - xLabel: String, - - // Y value of the tooltip as a string - yLabel: String, - - // Index of the dataset the item comes from - datasetIndex: Number, - - // Index of this data item in the dataset - index: Number, - - // X position of matching point - x: Number, - - // Y position of matching point - y: Number, -} -``` - -### Hover Configuration - -The hover configuration is passed into the `options.hover` namespace. The global hover configuration is at `Chart.defaults.global.hover`. - -Name | Type | Default | Description ---- | --- | --- | --- -mode | String | 'nearest' | Sets which elements appear in the tooltip. See [Interaction Modes](#interaction-modes) for details -intersect | Boolean | true | if true, the hover mode only applies when the mouse position intersects an item on the chart -animationDuration | Number | 400 | Duration in milliseconds it takes to animate hover style changes -onHover | Function | null | Called when any of the events fire. Called in the context of the chart and passed the event and an array of active elements (bars, points, etc) - -### Interaction Modes -When configuring interaction with the graph via hover or tooltips, a number of different modes are available. - -The following table details the modes and how they behave in conjunction with the `intersect` setting - -Mode | Behaviour ---- | --- -point | Finds all of the items that intersect the point -nearest | Gets the item that is nearest to the point. The nearest item is determined based on the distance to the center of the chart item (point, bar). If 2 or more items are at the same distance, the one with the smallest area is used. 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. -single (deprecated) | Finds the first item that intersects the point and returns it. Behaves like 'nearest' mode with intersect = true. -label (deprecated) | See `'index'` mode -index | Finds item at the same index. If the `intersect` setting is true, the first intersecting item is used to determine the index in the data. If `intersect` false the nearest item is used to determine the index. -x-axis (deprecated) | Behaves like `'index'` mode with `intersect = false` -dataset | Finds items in the same dataset. If the `intersect` setting is true, the first intersecting item is used to determine the index in the data. If `intersect` false the nearest item is used to determine the index. -x | Returns all items that would intersect based on the `X` coordinate of the position only. Would be useful for a vertical cursor implementation. Note that this only applies to cartesian charts -y | Returns all items that would intersect based on the `Y` coordinate of the position. This would be useful for a horizontal cursor implementation. Note that this only applies to cartesian charts. - -### Animation Configuration - -The following animation options are available. The global options for are defined in `Chart.defaults.global.animation`. - -Name | Type | Default | Description ---- |:---:| --- | --- -duration | Number | 1000 | The number of milliseconds an animation takes. -easing | String | "easeOutQuart" | Easing function to use. Available options are: `'linear'`, `'easeInQuad'`, `'easeOutQuad'`, `'easeInOutQuad'`, `'easeInCubic'`, `'easeOutCubic'`, `'easeInOutCubic'`, `'easeInQuart'`, `'easeOutQuart'`, `'easeInOutQuart'`, `'easeInQuint'`, `'easeOutQuint'`, `'easeInOutQuint'`, `'easeInSine'`, `'easeOutSine'`, `'easeInOutSine'`, `'easeInExpo'`, `'easeOutExpo'`, `'easeInOutExpo'`, `'easeInCirc'`, `'easeOutCirc'`, `'easeInOutCirc'`, `'easeInElastic'`, `'easeOutElastic'`, `'easeInOutElastic'`, `'easeInBack'`, `'easeOutBack'`, `'easeInOutBack'`, `'easeInBounce'`, `'easeOutBounce'`, `'easeInOutBounce'`. See [Robert Penner's easing equations](http://robertpenner.com/easing/). -onProgress | Function | none | Callback called on each step of an animation. Passed a single argument, an object, containing the chart instance and an object with details of the animation. -onComplete | Function | none | Callback called at the end of an animation. Passed the same arguments as `onProgress` - -#### Animation Callbacks - -The `onProgress` and `onComplete` callbacks are useful for synchronizing an external draw to the chart animation. The callback is passed an object that implements the following interface. An example usage of these callbacks can be found on [Github](https://github.com/chartjs/Chart.js/blob/master/samples/animation/progress-bar.html). This sample displays a progress bar showing how far along the animation is. - -```javascript -{ - // Chart instance - chart, - - // Contains details of the on-going animation - animationObject, -} -``` - -#### Animation Object - -The animation object passed to the callbacks is of type `Chart.Animation`. The object has the following parameters. - -```javascript -{ - // Current Animation frame number - currentStep: Number, - - // Number of animation frames - numSteps: Number, - - // Animation easing to use - easing: String, - - // Function that renders the chart - render: Function, - - // User callback - onAnimationProgress: Function, - - // User callback - onAnimationComplete: Function -} -``` - -### Element Configuration - -The global options for elements are defined in `Chart.defaults.global.elements`. - -Options can be configured for four different types of elements: arc, lines, points, and rectangles. When set, these options apply to all objects of that type unless specifically overridden by the configuration attached to a dataset. - -#### Arc Configuration - -Arcs are used in the polar area, doughnut and pie charts. They can be configured with the following options. The global arc options are stored in `Chart.defaults.global.elements.arc`. - -Name | Type | Default | Description ---- | --- | --- | --- -backgroundColor | Color | 'rgba(0,0,0,0.1)' | Default fill color for arcs. Inherited from the global default -borderColor | Color | '#fff' | Default stroke color for arcs -borderWidth | Number | 2 | Default stroke width for arcs - -#### Line Configuration - -Line elements are used to represent the line in a line chart. The global line options are stored in `Chart.defaults.global.elements.line`. - -Name | Type | Default | Description ---- | --- | --- | --- -tension | Number | 0.4 | Default bezier curve tension. Set to `0` for no bezier curves. -backgroundColor | Color | 'rgba(0,0,0,0.1)' | Default line fill color -borderWidth | Number | 3 | Default line stroke width -borderColor | Color | 'rgba(0,0,0,0.1)' | Default line stroke color -borderCapStyle | String | 'butt' | Default line cap style. See [MDN](https://developer.mozilla.org/en/docs/Web/API/CanvasRenderingContext2D/lineCap) -borderDash | Array | `[]` | Default line dash. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash) -borderDashOffset | Number | 0.0 | Default line dash offset. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset) -borderJoinStyle | String | 'miter' | Default line join style. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin) -capBezierPoints | Boolean | true | If true, bezier control points are kept inside the chart. If false, no restriction is enforced. -fill | Boolean or String | true | If true, the fill is assumed to be to zero. String values are 'zero', 'top', and 'bottom' to fill to different locations. If `false`, no fill is added -stepped | Boolean | false | If true, the line is shown as a stepped line and 'tension' will be ignored - -#### Point Configuration - -Point elements are used to represent the points in a line chart or a bubble chart. The global point options are stored in `Chart.defaults.global.elements.point`. - -Name | Type | Default | Description ---- | --- | --- | --- -radius | Number | 3 | Default point radius -pointStyle | String | 'circle' | Default point style -backgroundColor | Color | 'rgba(0,0,0,0.1)' | Default point fill color -borderWidth | Number | 1 | Default point stroke width -borderColor | Color | 'rgba(0,0,0,0.1)' | Default point stroke color -hitRadius | Number | 1 | Extra radius added to point radius for hit detection -hoverRadius | Number | 4 | Default point radius when hovered -hoverBorderWidth | Number | 1 | Default stroke width when hovered - -#### Rectangle Configuration - -Rectangle elements are used to represent the bars in a bar chart. The global rectangle options are stored in `Chart.defaults.global.elements.rectangle`. - -Name | Type | Default | Description ---- | --- | --- | --- -backgroundColor | Color | 'rgba(0,0,0,0.1)' | Default bar fill color -borderWidth | Number | 0 | Default bar stroke width -borderColor | Color | 'rgba(0,0,0,0.1)' | Default bar stroke color -borderSkipped | String | 'bottom' | Default skipped (excluded) border for rectangle. Can be one of `bottom`, `left`, `top`, `right` - -### Colors - -When supplying colors to Chart options, you can use a number of formats. You can specify the color as a string in hexadecimal, RGB, or HSL notations. If a color is needed, but not specified, Chart.js will use the global default color. This color is stored at `Chart.defaults.global.defaultColor`. It is initially set to 'rgba(0, 0, 0, 0.1)'; - -You can also pass a [CanvasGradient](https://developer.mozilla.org/en-US/docs/Web/API/CanvasGradient) object. You will need to create this before passing to the chart, but using it you can achieve some interesting effects. - -### Patterns - -An alternative option is to pass a [CanvasPattern](https://developer.mozilla.org/en-US/docs/Web/API/CanvasPattern) object. For example, if you wanted to fill a dataset with a pattern from an image you could do the following. - -```javascript -var img = new Image(); -img.src = 'https://example.com/my_image.png'; -img.onload = function() { - var ctx = document.getElementById('canvas').getContext('2d'); - var fillPattern = ctx.createPattern(img, 'repeat'); - - var chart = new Chart(ctx, { - data: { - labels: ['Item 1', 'Item 2', 'Item 3'], - datasets: [{ - data: [10, 20, 30], - backgroundColor: fillPattern - }] - } - }) -} -``` - -Using pattern fills for data graphics can help viewers with vision deficiencies (e.g. color-blindness or partial sight) to [more easily understand your data](http://betweentwobrackets.com/data-graphics-and-colour-vision/). - -Using the [Patternomaly](https://github.com/ashiguruma/patternomaly) library you can generate patterns to fill datasets. - -```javascript -var chartData = { - datasets: [{ - data: [45, 25, 20, 10], - backgroundColor: [ - pattern.draw('square', '#ff6384'), - pattern.draw('circle', '#36a2eb'), - pattern.draw('diamond', '#cc65fe'), - pattern.draw('triangle', '#ffce56'), - ] - }], - labels: ['Red', 'Blue', 'Purple', 'Yellow'] -}; -``` - -### Mixed Chart Types - -When creating a chart, you have the option to overlay different chart types on top of each other as separate datasets. - -To do this, you must set a `type` for each dataset individually. You can create mixed chart types with bar and line chart types. - -When creating the chart you must set the overall `type` as `bar`. - -```javascript -var myChart = new Chart(ctx, { - type: 'bar', - data: { - labels: ['Item 1', 'Item 2', 'Item 3'], - datasets: [ - { - type: 'bar', - label: 'Bar Component', - data: [10, 20, 30], - }, - { - type: 'line', - label: 'Line Component', - data: [30, 20, 10], - } - ] - } -}); -``` diff --git a/docs/02-Scales.md b/docs/02-Scales.md deleted file mode 100644 index a8abfb4b382..00000000000 --- a/docs/02-Scales.md +++ /dev/null @@ -1,369 +0,0 @@ ---- -title: Scales -anchor: scales ---- - -Scales in v2.0 of Chart.js are significantly more powerful, but also different than those of v1.0. -* Multiple X & Y axes are supported. -* A built-in label auto-skip feature detects would-be overlapping ticks and labels and removes every nth label to keep things displaying normally. -* Scale titles are supported -* New scale types can be extended without writing an entirely new chart type - - -### Common Configuration - -Every scale extends a core scale class with the following options: - -Name | Type | Default | Description ---- | --- | --- | --- -type | String | Chart specific. | Type of scale being employed. Custom scales can be created and registered with a string key. Options: ["category"](#scales-category-scale), ["linear"](#scales-linear-scale), ["logarithmic"](#scales-logarithmic-scale), ["time"](#scales-time-scale), ["radialLinear"](#scales-radial-linear-scale) -display | Boolean | true | If true, show the scale including gridlines, ticks, and labels. Overrides *gridLines.display*, *scaleLabel.display*, and *ticks.display*. -position | String | "left" | Position of the scale. Possible values are 'top', 'left', 'bottom' and 'right'. -id | String | | The ID is used to link datasets and scale axes together. The properties `datasets.xAxisID` or `datasets.yAxisID` have to match the scale properties `scales.xAxes.id` or `scales.yAxes.id`. This is especially needed if multi-axes charts are used. -beforeUpdate | Function | undefined | Callback called before the update process starts. Passed a single argument, the scale instance. -beforeSetDimensions | Function | undefined | Callback that runs before dimensions are set. Passed a single argument, the scale instance. -afterSetDimensions | Function | undefined | Callback that runs after dimensions are set. Passed a single argument, the scale instance. -beforeDataLimits | Function | undefined | Callback that runs before data limits are determined. Passed a single argument, the scale instance. -afterDataLimits | Function | undefined | Callback that runs after data limits are determined. Passed a single argument, the scale instance. -beforeBuildTicks | Function | undefined | Callback that runs before ticks are created. Passed a single argument, the scale instance. -afterBuildTicks | Function | undefined | Callback that runs after ticks are created. Useful for filtering ticks. Passed a single argument, the scale instance. -beforeTickToLabelConversion | Function | undefined | Callback that runs before ticks are converted into strings. Passed a single argument, the scale instance. -afterTickToLabelConversion | Function | undefined | Callback that runs after ticks are converted into strings. Passed a single argument, the scale instance. -beforeCalculateTickRotation | Function | undefined | Callback that runs before tick rotation is determined. Passed a single argument, the scale instance. -afterCalculateTickRotation | Function | undefined | Callback that runs after tick rotation is determined. Passed a single argument, the scale instance. -beforeFit | Function | undefined | Callback that runs before the scale fits to the canvas. Passed a single argument, the scale instance. -afterFit | Function | undefined | Callback that runs after the scale fits to the canvas. Passed a single argument, the scale instance. -afterUpdate | Function | undefined | Callback that runs at the end of the update process. Passed a single argument, the scale instance. -**gridLines** | Object | - | See [grid line configuration](#grid-line-configuration) section. -**scaleLabel** | Object | | See [scale title configuration](#scale-title-configuration) section. -**ticks** | Object | | See [tick configuration](#tick-configuration) section. - -#### Grid Line Configuration - -The grid line configuration is nested under the scale configuration in the `gridLines` key. It defines options for the grid lines that run perpendicular to the axis. - -Name | Type | Default | Description ---- | --- | --- | --- -display | Boolean | true | -color | Color or Array[Color] | "rgba(0, 0, 0, 0.1)" | Color of the grid lines. -borderDash | Array[Number] | [] | Length and spacing of dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash) -borderDashOffset | Number | 0.0 | Offset for line dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset) -lineWidth | Number or Array[Number] | 1 | Stroke width of grid lines -drawBorder | Boolean | true | If true draw border on the edge of the chart -drawOnChartArea | Boolean | true | If true, draw lines on the chart area inside the axis lines. This is useful when there are multiple axes and you need to control which grid lines are drawn -drawTicks | Boolean | true | If true, draw lines beside the ticks in the axis area beside the chart. -tickMarkLength | Number | 10 | Length in pixels that the grid lines will draw into the axis area. -zeroLineWidth | Number | 1 | Stroke width of the grid line for the first index (index 0). -zeroLineColor | Color | "rgba(0, 0, 0, 0.25)" | Stroke color of the grid line for the first index (index 0). -offsetGridLines | Boolean | false | If true, labels are shifted to be between grid lines. This is used in the bar chart. - -#### Scale Title Configuration - -The scale label configuration is nested under the scale configuration in the `scaleLabel` key. It defines options for the scale title. - -Name | Type | Default | Description ---- | --- | --- | --- -display | Boolean | false | -labelString | String | "" | The text for the title. (i.e. "# of People", "Response Choices") -fontColor | Color | "#666" | Font color for the scale title. -fontFamily| String | "'Helvetica Neue', 'Helvetica', 'Arial', sans-serif" | Font family for the scale title, follows CSS font-family options. -fontSize | Number | 12 | Font size for the scale title. -fontStyle | String | "normal" | Font style for the scale title, follows CSS font-style options (i.e. normal, italic, oblique, initial, inherit). - -#### Tick Configuration - -The tick configuration is nested under the scale configuration in the `ticks` key. It defines options for the tick marks that are generated by the axis. - -Name | Type | Default | Description ---- | --- | --- | --- -autoSkip | Boolean | true | If true, automatically calculates how many labels that can be shown and hides labels accordingly. Turn it off to show all labels no matter what -autoSkipPadding | Number | 0 | Padding between the ticks on the horizontal axis when `autoSkip` is enabled. *Note: Only applicable to horizontal scales.* -callback | Function | `function(value) { return helpers.isArray(value) ? value : '' + value; }` | Returns the string representation of the tick value as it should be displayed on the chart. See [callback](#scales-creating-custom-tick-formats) section below. -display | Boolean | true | If true, show the ticks. -fontColor | Color | "#666" | Font color for the tick labels. -fontFamily | String | "'Helvetica Neue', 'Helvetica', 'Arial', sans-serif" | Font family for the tick labels, follows CSS font-family options. -fontSize | Number | 12 | Font size for the tick labels. -fontStyle | String | "normal" | Font style for the tick labels, follows CSS font-style options (i.e. normal, italic, oblique, initial, inherit). -labelOffset | Number | 0 | Distance in pixels to offset the label from the centre point of the tick (in the y direction for the x axis, and the x direction for the y axis). *Note: this can cause labels at the edges to be cropped by the edge of the canvas* -maxRotation | Number | 90 | Maximum rotation for tick labels when rotating to condense labels. Note: Rotation doesn't occur until necessary. *Note: Only applicable to horizontal scales.* -minRotation | Number | 0 | Minimum rotation for tick labels. *Note: Only applicable to horizontal scales.* -mirror | Boolean | false | Flips tick labels around axis, displaying the labels inside the chart instead of outside. *Note: Only applicable to vertical scales.* -padding | Number | 10 | Padding between the tick label and the axis. *Note: Only applicable to horizontal scales.* -reverse | Boolean | false | Reverses order of tick labels. - -#### Creating Custom Tick Formats - -The `callback` method may be used for advanced tick customization. In the following example, every label of the Y axis would be displayed in scientific notation. - -If the callback returns `null` or `undefined` the associated grid line will be hidden. - -```javascript -var chart = new Chart(ctx, { - type: 'line', - data: data, - options: { - scales: { - yAxes: [{ - ticks: { - // Create scientific notation labels - callback: function(value, index, values) { - return value.toExponential(); - } - } - }] - } - } -}); -``` - -### Category Scale - -The category scale will be familiar to those who have used v1.0. Labels are drawn from one of the label arrays included in the chart data. If only `data.labels` is defined, this will be used. If `data.xLabels` is defined and the axis is horizontal, this will be used. Similarly, if `data.yLabels` is defined and the axis is vertical, this property will be used. Using both `xLabels` and `yLabels` together can create a chart that uses strings for both the X and Y axes. - -#### Configuration Options - -The category scale has the following additional options that can be set. - -Name | Type | Default | Description ---- | --- | --- | --- -ticks.min | String | - | The minimum item to display. Must be a value in the `labels` array -ticks.max | String | - | The maximum item to display. Must be a value in the `labels` array - -### Linear Scale - -The linear scale is use to chart numerical data. It can be placed on either the x or y axis. The scatter chart type automatically configures a line chart to use one of these scales for the x axis. As the name suggests, linear interpolation is used to determine where a value lies on the axis. - -#### Configuration Options - -The following options are provided by the linear scale. They are all located in the `ticks` sub options. - -Name | Type | Default | Description ---- | --- | --- | --- -beginAtZero | Boolean | - | if true, scale will include 0 if it is not already included. -min | Number | - | User defined minimum number for the scale, overrides minimum value from data. -max | Number | - | User defined maximum number for the scale, overrides maximum value from data. -maxTicksLimit | Number | 11 | Maximum number of ticks and gridlines to show. If not defined, it will limit to 11 ticks but will show all gridlines. -fixedStepSize | Number | - | User defined fixed step size for the scale. If set, the scale ticks will be enumerated by multiple of stepSize, having one tick per increment. If not set, the ticks are labeled automatically using the nice numbers algorithm. -stepSize | Number | - | if defined, it can be used along with the min and the max to give a custom number of steps. See the example below. -suggestedMax | Number | - | User defined maximum number for the scale, overrides maximum value *except for if* it is lower than the maximum value. -suggestedMin | Number | - | User defined minimum number for the scale, overrides minimum value *except for if* it is higher than the minimum value. - -#### Example Configuration - -The following example creates a line chart with a vertical axis that goes from 0 to 5 in 0.5 sized steps. - -```javascript -var chart = new Chart(ctx, { - type: 'line', - data: data, - options: { - scales: { - yAxes: [{ - ticks: { - max: 5, - min: 0, - stepSize: 0.5 - } - }] - } - } -}); -``` - -### Logarithmic Scale - -The logarithmic scale is use to chart numerical data. It can be placed on either the x or y axis. As the name suggests, logarithmic interpolation is used to determine where a value lies on the axis. - -#### Configuration Options - -The following options are provided by the logarithmic scale. They are all located in the `ticks` sub options. - -Name | Type | Default | Description ---- | --- | --- | --- -min | Number | - | User defined minimum number for the scale, overrides minimum value from data. -max | Number | - | User defined maximum number for the scale, overrides maximum value from data. - -#### Example Configuration - -The following example creates a chart with a logarithmic X axis that ranges from 1 to 1000. - -```javascript -var chart = new Chart(ctx, { - type: 'line', - data: data, - options: { - scales: { - xAxes: [{ - type: 'logarithmic', - position: 'bottom', - ticks: { - min: 1, - max: 1000 - } - }] - } - } -}) -``` - -### Time Scale - -The time scale is used to display times and dates. It can only be placed on the X axis. When building its ticks, it will automatically calculate the most comfortable unit base on the size of the scale. - -#### Configuration Options - -The following options are provided by the time scale. They are all located in the `time` sub options. - -Name | Type | Default | Description ---- | --- | --- | --- -displayFormats | Object | - | See [Display Formats](#scales-display-formats) section below. -isoWeekday | Boolean | false | If true and the unit is set to 'week', iso weekdays will be used. -max | [Time](#scales-date-formats) | - | If defined, this will override the data maximum -min | [Time](#scales-date-formats) | - | If defined, this will override the data minimum -parser | String or Function | - | If defined as a string, it is interpreted as a custom format to be used by moment to parse the date. If this is a function, it must return a moment.js object given the appropriate data value. -round | String | - | If defined, dates will be rounded to the start of this unit. See [Time Units](#scales-time-units) below for the allowed units. -tooltipFormat | String | '' | The moment js format string to use for the tooltip. -unit | String | - | If defined, will force the unit to be a certain type. See [Time Units](#scales-time-units) section below for details. -unitStepSize | Number | 1 | The number of units between grid lines. -minUnit | String | 'millisecond' | The minimum display format to be used for a time unit - -#### Date Formats - -When providing data for the time scale, Chart.js supports all of the formats that Moment.js accepts. See [Moment.js docs](http://momentjs.com/docs/#/parsing/) for details. - -#### Display Formats - -The following display formats are used to configure how different time units are formed into strings for the axis tick marks. See [moment.js](http://momentjs.com/docs/#/displaying/format/) for the allowable format strings. - -Name | Default ---- | --- -millisecond | 'SSS [ms]' -second | 'h:mm:ss a' -minute | 'h:mm:ss a' -hour | 'MMM D, hA' -day | 'll' -week | 'll' -month | 'MMM YYYY' -quarter | '[Q]Q - YYYY' -year | 'YYYY' - -For example, to set the display format for the 'quarter' unit to show the month and year, the following config would be passed to the chart constructor. - -```javascript -var chart = new Chart(ctx, { - type: 'line', - data: data, - options: { - scales: { - xAxes: [{ - type: 'time', - time: { - displayFormats: { - quarter: 'MMM YYYY' - } - } - }] - } - } -}) -``` - -#### Time Units - -The following time measurements are supported. The names can be passed as strings to the `time.unit` config option to force a certain unit. - -* millisecond -* second -* minute -* hour -* day -* week -* month -* quarter -* year - -For example, to create a chart with a time scale that always displayed units per month, the following config could be used. - -```javascript -var chart = new Chart(ctx, { - type: 'line', - data: data, - options: { - scales: { - xAxes: [{ - time: { - unit: 'month' - } - }] - } - } -}) -``` - -### Radial Linear Scale - -The radial linear scale is used specifically for the radar and polar area chart types. It overlays the chart area, rather than being positioned on one of the edges. - -#### Configuration Options - -The following additional configuration options are provided by the radial linear scale. - -Name | Type | Default | Description ---- | --- | --- | --- -lineArc | Boolean | false | If true, circular arcs are used else straight lines are used. The former is used by the polar area chart and the latter by the radar chart -angleLines | Object | - | See the Angle Line Options section below for details. -pointLabels | Object | - | See the Point Label Options section below for details. -ticks | Object | - | See the Ticks table below for options. - -#### Angle Line Options - -The following options are used to configure angled lines that radiate from the center of the chart to the point labels. They can be found in the `angleLines` sub options. Note that these options only apply if `lineArc` is false. - -Name | Type | Default | Description ---- | --- | --- | --- -display | Boolean | true | If true, angle lines are shown. -color | Color | 'rgba(0, 0, 0, 0.1)' | Color of angled lines -lineWidth | Number | 1 | Width of angled lines - -#### Point Label Options - -The following options are used to configure the point labels that are shown on the perimeter of the scale. They can be found in the `pointLabels` sub options. Note that these options only apply if `lineArc` is false. - -Name | Type | Default | Description ---- | --- | --- | --- -callback | Function | - | Callback function to transform data label to axis label -fontColor | Color | '#666' | Font color -fontFamily | String | "'Helvetica Neue', 'Helvetica', 'Arial', sans-serif" | Font family to render -fontSize | Number | 10 | Font size in pixels -fontStyle | String | 'normal' | Font Style to use - - -#### Tick Options - -Name | Type | Default | Description ---- | --- | --- | --- -backdropColor | Color | 'rgba(255, 255, 255, 0.75)' | Color of label backdrops -backdropPaddingX | Number | 2 | Horizontal padding of label backdrop -backdropPaddingY | Number | 2 | Vertical padding of label backdrop -beginAtZero | Boolean | - | if true, scale will include 0 if it is not already included. -min | Number | - | User defined minimum number for the scale, overrides minimum value from data. -max | Number | - | User defined maximum number for the scale, overrides maximum value from data. -maxTicksLimit | Number | 11 | Maximum number of ticks and gridlines to show. If not defined, it will limit to 11 ticks but will show all gridlines. -showLabelBackdrop | Boolean | true | If true, draw a background behind the tick labels -fixedStepSize | Number | - | User defined fixed step size for the scale. If set, the scale ticks will be enumerated by multiple of stepSize, having one tick per increment. If not set, the ticks are labeled automatically using the nice numbers algorithm. -stepSize | Number | - | if defined, it can be used along with the min and the max to give a custom number of steps. See the example below. -suggestedMax | Number | - | User defined maximum number for the scale, overrides maximum value *except for if* it is lower than the maximum value. -suggestedMin | Number | - | User defined minimum number for the scale, overrides minimum value *except for if* it is higher than the minimum value. - -### Update Default Scale config - -The default configuration for a scale can be easily changed using the scale service. Pass in a partial configuration that will be merged with the current scale default configuration. - -For example, to set the minimum value of 0 for all linear scales, you would do the following. Any linear scales created after this time would now have a minimum of 0. -``` -Chart.scaleService.updateScaleDefaults('linear', { - ticks: { - min: 0 - } -}) -``` diff --git a/docs/03-Line-Chart.md b/docs/03-Line-Chart.md deleted file mode 100644 index 24b77cfe6df..00000000000 --- a/docs/03-Line-Chart.md +++ /dev/null @@ -1,187 +0,0 @@ ---- -title: Line Chart -anchor: line-chart ---- -### Introduction -A line chart is a way of plotting data points on a line. Often, it is used to show trend data, and the comparison of two data sets. - -
- -
- -### Example Usage -```javascript -var myLineChart = new Chart(ctx, { - type: 'line', - data: data, - options: options -}); -``` - -Alternatively a line chart can be created using syntax similar to the v1.0 syntax -```javascript -var myLineChart = Chart.Line(ctx, { - data: data, - options: options -}); -``` - -### Dataset Structure - -The following options can be included in a line chart dataset to configure options for that specific dataset. - -All point* properties can be specified as an array. If these are set to an array value, the first value applies to the first point, the second value to the second point, and so on. - -Property | Type | Usage ---- | --- | --- -data | See [data point](#line-chart-data-points) section | The data to plot in a line -label | `String` | The label for the dataset which appears in the legend and tooltips -xAxisID | `String` | The ID of the x axis to plot this dataset on -yAxisID | `String` | The ID of the y axis to plot this dataset on -fill | `Boolean` | If true, fill the area under the line -cubicInterpolationMode | `String` | Algorithm used to interpolate a smooth curve from the discrete data points. Options are 'default' and 'monotone'. The 'default' algorithm uses a custom weighted cubic interpolation, which produces pleasant curves for all types of datasets. The 'monotone' algorithm is more suited to `y = f(x)` datasets : it preserves monotonicity (or piecewise monotonicity) of the dataset being interpolated, and ensures local extremums (if any) stay at input data points. If left untouched (`undefined`), the global `options.elements.line.cubicInterpolationMode` property is used. -lineTension | `Number` | Bezier curve tension of the line. Set to 0 to draw straightlines. This option is ignored if monotone cubic interpolation is used. *Note* This was renamed from 'tension' but the old name still works. -backgroundColor | `Color` | The fill color under the line. See [Colors](#chart-configuration-colors) -borderWidth | `Number` | The width of the line in pixels -borderColor | `Color` | The color of the line. -borderCapStyle | `String` | Cap style of the line. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineCap) -borderDash | `Array` | Length and spacing of dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash) -borderDashOffset | `Number` | Offset for line dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset) -borderJoinStyle | `String` | Line joint style. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin) -pointBorderColor | `Color or Array` | The border color for points. -pointBackgroundColor | `Color or Array` | The fill color for points -pointBorderWidth | `Number or Array` | The width of the point border in pixels -pointRadius | `Number or Array` | The radius of the point shape. If set to 0, nothing is rendered. -pointHoverRadius | `Number or Array` | The radius of the point when hovered -pointHitRadius | `Number or Array` | The pixel size of the non-displayed point that reacts to mouse events -pointHoverBackgroundColor | `Color or Array` | Point background color when hovered -pointHoverBorderColor | `Color or Array` | Point border color when hovered -pointHoverBorderWidth | `Number or Array` | Border width of point when hovered -pointStyle | `String, Array, Image, Array` | The style of point. Options are 'circle', 'triangle', 'rect', 'rectRounded', 'rectRot', 'cross', 'crossRot', 'star', 'line', and 'dash'. If the option is an image, that image is drawn on the canvas using `drawImage`. -showLine | `Boolean` | If false, the line is not drawn for this dataset -spanGaps | `Boolean` | If true, lines will be drawn between points with no or null data -steppedLine | `Boolean` | If true, the line is shown as a stepped line and 'lineTension' will be ignored - -An example data object using these attributes is shown below. -```javascript -var data = { - labels: ["January", "February", "March", "April", "May", "June", "July"], - datasets: [ - { - label: "My First dataset", - fill: false, - lineTension: 0.1, - backgroundColor: "rgba(75,192,192,0.4)", - borderColor: "rgba(75,192,192,1)", - borderCapStyle: 'butt', - borderDash: [], - borderDashOffset: 0.0, - borderJoinStyle: 'miter', - pointBorderColor: "rgba(75,192,192,1)", - pointBackgroundColor: "#fff", - pointBorderWidth: 1, - pointHoverRadius: 5, - pointHoverBackgroundColor: "rgba(75,192,192,1)", - pointHoverBorderColor: "rgba(220,220,220,1)", - pointHoverBorderWidth: 2, - pointRadius: 1, - pointHitRadius: 10, - data: [65, 59, 80, 81, 56, 55, 40], - spanGaps: false, - } - ] -}; -``` - -The line chart usually requires an array of labels. This labels are shown on the X axis. There must be one label for each data point. More labels than datapoints are allowed, in which case the line ends at the last data point. -The data for line charts is broken up into an array of datasets. Each dataset has a colour for the fill, a colour for the line and colours for the points and strokes of the points. These colours are strings just like CSS. You can use RGBA, RGB, HEX or HSL notation. - -The label key on each dataset is optional, and can be used when generating a scale for the chart. - -When `spanGaps` is set to true, the gaps between points in sparse datasets are filled in. By default, it is off. - -### Data Points - -The data passed to the chart can be passed in two formats. The most common method is to pass the data array as an array of numbers. In this case, the `data.labels` array must be specified and must contain a label for each point or, in the case of labels to be displayed over multiple lines an array of labels (one for each line) i.e `[["June","2015"], "July"]`. - -The alternate is used for sparse datasets. Data is specified using an object containing `x` and `y` properties. This is used for scatter charts as documented below. - -### Scatter Line Charts - -Scatter line charts can be created by changing the X axis to a linear axis. To use a scatter chart, data must be passed as objects containing X and Y properties. The example below creates a scatter chart with 3 points. - -```javascript -var scatterChart = new Chart(ctx, { - type: 'line', - data: { - datasets: [{ - label: 'Scatter Dataset', - data: [{ - x: -10, - y: 0 - }, { - x: 0, - y: 10 - }, { - x: 10, - y: 5 - }] - }] - }, - options: { - scales: { - xAxes: [{ - type: 'linear', - position: 'bottom' - }] - } - } -}); -``` - -### Chart Options - -These are the customisation options specific to Line charts. These options are merged with the [global chart configuration options](#chart-configuration-global-configuration), and form the options of the chart. - -Name | Type | Default | Description ---- | --- | --- | --- -showLines | Boolean | true | If false, the lines between points are not drawn -spanGaps | Boolean | false | If true, NaN data does not break the line - -You can override these for your `Chart` instance by passing a member `options` into the `Line` method. - -For example, we could have a line chart display without an X axis by doing the following. The config merge is smart enough to handle arrays so that you do not need to specify all axis settings to change one thing. - -```javascript -new Chart(ctx, { - type: 'line', - data: data, - options: { - scales: { - xAxes: [{ - display: false - }] - } - } -}); -``` - -We can also change these defaults values for each Line type that is created, this object is available at `Chart.defaults.line`. - -### Stacked Charts - -Stacked area charts can be created by setting the Y axis to a stacked configuration. The following example would have stacked lines. - -```javascript -var stackedLine = new Chart(ctx, { - type: 'line', - data: data, - options: { - scales: { - yAxes: [{ - stacked: true - }] - } - } -}); -``` \ No newline at end of file diff --git a/docs/04-Bar-Chart.md b/docs/04-Bar-Chart.md deleted file mode 100644 index ef2cd3c19a6..00000000000 --- a/docs/04-Bar-Chart.md +++ /dev/null @@ -1,174 +0,0 @@ ---- -title: Bar Chart -anchor: bar-chart ---- - -### Introduction -A bar chart is a way of showing data as bars. - -It is sometimes used to show trend data, and the comparison of multiple data sets side by side. - -
- -
- -### Example Usage -```javascript -var myBarChart = new Chart(ctx, { - type: 'bar', - data: data, - options: options -}); -``` - -Or if you want horizontal bars. - -```javascript -var myBarChart = new Chart(ctx, { - type: 'horizontalBar', - data: data, - options: options -}); -``` - -### Dataset Structure -The following options can be included in a bar chart dataset to configure options for that specific dataset. - -Some properties can be specified as an array. If these are set to an array value, the first value applies to the first bar, the second value to the second bar, and so on. - -Property | Type | Usage ---- | --- | --- -data | `Array` | The data to plot as bars -label | `String` | The label for the dataset which appears in the legend and tooltips -xAxisID | `String` | The ID of the x axis to plot this dataset on -yAxisID | `String` | The ID of the y axis to plot this dataset on -backgroundColor | `Color or Array` | The fill color of the bars. See [Colors](#chart-configuration-colors) -borderColor | `Color or Array` | Bar border color -borderWidth | `Number or Array` | Border width of bar in pixels -borderSkipped | `String or Array` | Which edge to skip drawing the border for. Options are 'bottom', 'left', 'top', and 'right' -hoverBackgroundColor | `Color or Array` | Bar background color when hovered -hoverBorderColor | `Color or Array` | Bar border color when hovered -hoverBorderWidth | `Number or Array` | Border width of bar when hovered -stack | `String` | The ID of the group to which this dataset belongs to (when stacked, each group will be a separate stack) - -An example data object using these attributes is shown below. - -```javascript -var data = { - labels: ["January", "February", "March", "April", "May", "June", "July"], - datasets: [ - { - label: "My First dataset", - backgroundColor: [ - 'rgba(255, 99, 132, 0.2)', - 'rgba(54, 162, 235, 0.2)', - 'rgba(255, 206, 86, 0.2)', - 'rgba(75, 192, 192, 0.2)', - 'rgba(153, 102, 255, 0.2)', - 'rgba(255, 159, 64, 0.2)' - ], - borderColor: [ - 'rgba(255,99,132,1)', - 'rgba(54, 162, 235, 1)', - 'rgba(255, 206, 86, 1)', - 'rgba(75, 192, 192, 1)', - 'rgba(153, 102, 255, 1)', - 'rgba(255, 159, 64, 1)' - ], - borderWidth: 1, - data: [65, 59, 80, 81, 56, 55, 40], - } - ] -}; -``` -The bar chart has the a very similar data structure to the line chart, and has an array of datasets, each with colours and an array of data. -We have an array of labels too for display. In the example, we are showing the same data as the previous line chart example. - -### Chart Options - -These are the customisation options specific to Bar charts. These options are merged with the [global chart configuration options](#global-chart-configuration), and form the options of the chart. - -The default options for bar chart are defined in `Chart.defaults.bar`. - -Name | Type | Default | Description ---- |:---:| --- | --- -*hover*.mode | String | "label" | Label's hover mode. "label" is used since the x axis displays data by the index in the dataset. -scales | Object | - | - -*scales*.xAxes | Array | | The bar chart officially supports only 1 x-axis but uses an array to keep the API consistent. Use a scatter chart if you need multiple x axes. -*Options for xAxes* | | | -type | String | "Category" | As defined in [Scales](#scales-category-scale). -display | Boolean | true | If true, show the scale. -id | String | "x-axis-0" | Id of the axis so that data can bind to it -stacked | Boolean | false | If true, bars are stacked on the x-axis -barThickness | Number | | Manually set width of each bar in pixels. If not set, the bars are sized automatically. -categoryPercentage | Number | 0.8 | Percent (0-1) of the available width (the space between the gridlines for small datasets) for each data-point to use for the bars. [Read More](#bar-chart-barpercentage-vs-categorypercentage) -barPercentage | Number | 0.9 | Percent (0-1) of the available width each bar should be within the category percentage. 1.0 will take the whole category width and put the bars right next to each other. [Read More](#bar-chart-barpercentage-vs-categorypercentage) -gridLines | Object | [See Scales](#scales) | -*gridLines*.offsetGridLines | Boolean | true | If true, the bars for a particular data point fall between the grid lines. If false, the grid line will go right down the middle of the bars. -| | | -*scales*.yAxes | Array | `[{ type: "linear" }]` | -*Options for yAxes* | | | -type | String | "linear" | As defined in [Scales](#scales-linear-scale). -display | Boolean | true | If true, show the scale. -id | String | "y-axis-0" | Id of the axis so that data can bind to it. -stacked | Boolean | false | If true, bars are stacked on the y-axis -barThickness | Number | | Manually set height of each bar in pixels. If not set, the bars are sized automatically. - -You can override these for your `Chart` instance by passing a second argument into the `Bar` method as an object with the keys you want to override. - -For example, we could have a bar chart without a stroke on each bar by doing the following: - -```javascript -new Chart(ctx, { - type: "bar", - data: data, - options: { - scales: { - xAxes: [{ - stacked: true - }], - yAxes: [{ - stacked: true - }] - } - } -}); -// This will create a chart with all of the default options, merged from the global config, -// and the Bar chart defaults but this particular instance will have `stacked` set to true -// for both x and y axes. -``` - -We can also change these defaults values for each Bar type that is created, this object is available at `Chart.defaults.bar`. For horizontal bars, this object is available at `Chart.defaults.horizontalBar`. - -The default options for horizontal bar charts are defined in `Chart.defaults.horizontalBar` and are same as those of the bar chart, but with `xAxes` and `yAxes` swapped and the following additional options. - -Name | Type | Default | Description ---- |:---:| --- | --- -*Options for xAxes* | | | -position | String | "bottom" | -*Options for yAxes* | | | -position | String | "left" | - -### barPercentage vs categoryPercentage - -The following shows the relationship between the bar percentage option and the category percentage option. - -```text -// categoryPercentage: 1.0 -// barPercentage: 1.0 -Bar: | 1.0 | 1.0 | -Category: | 1.0 | -Sample: |===========| - -// categoryPercentage: 1.0 -// barPercentage: 0.5 -Bar: |.5| |.5| -Category: | 1.0 | -Sample: |==============| - -// categoryPercentage: 0.5 -// barPercentage: 1.0 -Bar: |1.||1.| -Category: | .5 | -Sample: |==============| -``` diff --git a/docs/05-Radar-Chart.md b/docs/05-Radar-Chart.md deleted file mode 100644 index 977574faf6c..00000000000 --- a/docs/05-Radar-Chart.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: Radar Chart -anchor: radar-chart ---- - -### Introduction -A radar chart is a way of showing multiple data points and the variation between them. - -They are often useful for comparing the points of two or more different data sets. - -
- -
- -### Example Usage - -```javascript -var myRadarChart = new Chart(ctx, { - type: 'radar', - data: data, - options: options -}); -``` - -### Dataset Structure - -The following options can be included in a radar chart dataset to configure options for that specific dataset. - -All point* properties can be specified as an array. If these are set to an array value, the first value applies to the first point, the second value to the second point, and so on. - -Property | Type | Usage ---- | --- | --- -data | `Array` | The data to plot in a line -label | `String` | The label for the dataset which appears in the legend and tooltips -fill | `Boolean` | If true, fill the area under the line -lineTension | `Number` | Bezier curve tension of the line. Set to 0 to draw straightlines. *Note* This was renamed from 'tension' but the old name still works. -backgroundColor | `Color` | The fill color under the line. See [Colors](#chart-configuration-colors) -borderWidth | `Number` | The width of the line in pixels -borderColor | `Color` | The color of the line. -borderCapStyle | `String` | Cap style of the line. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineCap) -borderDash | `Array` | Length and spacing of dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash) -borderDashOffset | `Number` | Offset for line dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset) -borderJoinStyle | `String` | Line joint style. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin) -pointBorderColor | `Color or Array` | The border color for points. -pointBackgroundColor | `Color or Array` | The fill color for points -pointBorderWidth | `Number or Array` | The width of the point border in pixels -pointRadius | `Number or Array` | The radius of the point shape. If set to 0, nothing is rendered. -pointHoverRadius | `Number or Array` | The radius of the point when hovered -pointHitRadius | `Number or Array` | The pixel size of the non-displayed point that reacts to mouse events -pointHoverBackgroundColor | `Color or Array` | Point background color when hovered -pointHoverBorderColor | `Color or Array` | Point border color when hovered -pointHoverBorderWidth | `Number or Array` | Border width of point when hovered -pointStyle | `String or Array` | The style of point. Options include 'circle', 'triangle', 'rect', 'rectRounded', 'rectRot', 'cross', 'crossRot', 'star', 'line', and 'dash' - -An example data object using these attributes is shown below. - -```javascript -var data = { - labels: ["Eating", "Drinking", "Sleeping", "Designing", "Coding", "Cycling", "Running"], - datasets: [ - { - label: "My First dataset", - backgroundColor: "rgba(179,181,198,0.2)", - borderColor: "rgba(179,181,198,1)", - pointBackgroundColor: "rgba(179,181,198,1)", - pointBorderColor: "#fff", - pointHoverBackgroundColor: "#fff", - pointHoverBorderColor: "rgba(179,181,198,1)", - data: [65, 59, 90, 81, 56, 55, 40] - }, - { - label: "My Second dataset", - backgroundColor: "rgba(255,99,132,0.2)", - borderColor: "rgba(255,99,132,1)", - pointBackgroundColor: "rgba(255,99,132,1)", - pointBorderColor: "#fff", - pointHoverBackgroundColor: "#fff", - pointHoverBorderColor: "rgba(255,99,132,1)", - data: [28, 48, 40, 19, 96, 27, 100] - } - ] -}; -``` -For a radar chart, to provide context of what each point means, we include an array of strings that show around each point in the chart. -For the radar chart data, we have an array of datasets. Each of these is an object, with a fill colour, a stroke colour, a colour for the fill of each point, and a colour for the stroke of each point. We also have an array of data values. -The label key on each dataset is optional, and can be used when generating a scale for the chart. - - -### Chart Options - -These are the customisation options specific to Radar charts. These options are merged with the [global chart configuration options](#global-chart-configuration), and form the options of the chart. - -The default options for radar chart are defined in `Chart.defaults.radar`. - -Name | Type | Default | Description ---- | --- | --- | --- -scale | Object | [See Scales](#scales) and [Defaults for Radial Linear Scale](#scales-radial-linear-scale) | Options for the one scale used on the chart. Use this to style the ticks, labels, and grid lines. -*scale*.type | String |"radialLinear" | As defined in ["Radial Linear"](#scales-radial-linear-scale). -*elements*.line | Object | | Options for all line elements used on the chart, as defined in the global elements, duplicated here to show Radar chart specific defaults. -*elements.line*.lineTension | Number | 0 | Tension exhibited by lines when calculating splineCurve. Setting to 0 creates straight lines. -startAngle | Number | 0 | The number of degrees to rotate the chart clockwise. - -You can override these for your `Chart` instance by passing a second argument into the `Radar` method as an object with the keys you want to override. - -For example, we could have a radar chart without a point for each on piece of data by doing the following: - -```javascript -new Chart(ctx, { - type: "radar", - data: data, - options: { - scale: { - reverse: true, - ticks: { - beginAtZero: true - } - } - } -}); -// This will create a chart with all of the default options, merged from the global config, -// and the Radar chart defaults but this particular instance's scale will be reversed as -// well as the ticks beginning at zero. -``` - -We can also change these defaults values for each Radar type that is created, this object is available at `Chart.defaults.radar`. diff --git a/docs/06-Polar-Area-Chart.md b/docs/06-Polar-Area-Chart.md deleted file mode 100644 index 4f2d8960d0b..00000000000 --- a/docs/06-Polar-Area-Chart.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: Polar Area Chart -anchor: polar-area-chart ---- -### Introduction -Polar area charts are similar to pie charts, but each segment has the same angle - the radius of the segment differs depending on the value. - -This type of chart is often useful when we want to show a comparison data similar to a pie chart, but also show a scale of values for context. - -
- -
- -### Example Usage - -```javascript -new Chart(ctx, { - data: data, - type: 'polarArea', - options: options -}); -``` - -### Dataset Structure - -The following options can be included in a polar area chart dataset to configure options for that specific dataset. - -Some properties are specified as arrays. The first value applies to the first bar, the second value to the second bar, and so on. - -Property | Type | Usage ---- | --- | --- -data | `Array` | The data to plot as arcs -label | `String` | The label for the dataset which appears in the legend and tooltips -backgroundColor | `Array` | The fill color of the arcs. See [Colors](#chart-configuration-colors) -borderColor | `Array` | Arc border color -borderWidth | `Array` | Border width of arcs in pixels -hoverBackgroundColor | `Array` | Arc background color when hovered -hoverBorderColor | `Array` | Arc border color when hovered -hoverBorderWidth | `Array` | Border width of arc when hovered - -An example data object using these attributes is shown below. - -```javascript -var data = { - datasets: [{ - data: [ - 11, - 16, - 7, - 3, - 14 - ], - backgroundColor: [ - "#FF6384", - "#4BC0C0", - "#FFCE56", - "#E7E9ED", - "#36A2EB" - ], - label: 'My dataset' // for legend - }], - labels: [ - "Red", - "Green", - "Yellow", - "Grey", - "Blue" - ] -}; -``` -As you can see, for the chart data you pass in an array of objects, with a value and a colour. The value attribute should be a number, while the color attribute should be a string. Similar to CSS, for this string you can use HEX notation, RGB, RGBA or HSL. - -### Chart Options - -These are the customisation options specific to Polar Area charts. These options are merged with the [global chart configuration options](#global-chart-configuration), and form the options of the chart. - -Name | Type | Default | Description ---- | --- | --- | --- -startAngle | Number | -0.5 * Math.PI | Sets the starting angle for the first item in a dataset -scale | Object | [See Scales](#scales) and [Defaults for Radial Linear Scale](#scales-radial-linear-scale) | Options for the one scale used on the chart. Use this to style the ticks, labels, and grid. -*scale*.type | String |"radialLinear" | As defined in ["Radial Linear"](#scales-radial-linear-scale). -*scale*.lineArc | Boolean | true | When true, lines are circular. -*animation*.animateRotate | Boolean |true | If true, will animate the rotation of the chart. -*animation*.animateScale | Boolean | true | If true, will animate scaling the chart. -*legend*.*labels*.generateLabels | Function | `function(data) {} ` | Returns labels for each the legend -*legend*.onClick | Function | function(event, legendItem) {} ` | Handles clicking an individual legend item -legendCallback | Function | `function(chart) ` | Generates the HTML legend via calls to `generateLegend` - -You can override these for your `Chart` instance by passing a second argument into the `PolarArea` method as an object with the keys you want to override. - -For example, we could have a polar area chart with a black stroke on each segment like so: - -```javascript -new Chart(ctx, { - data: data, - type: "polarArea", - options: { - elements: { - arc: { - borderColor: "#000000" - } - } - } -}); -// This will create a chart with all of the default options, merged from the global config, -// and the PolarArea chart defaults but this particular instance will have `elements.arc.borderColor` set to `"#000000"`. -``` - -We can also change these defaults values for each PolarArea type that is created, this object is available at `Chart.defaults.polarArea`. diff --git a/docs/07-Pie-Doughnut-Chart.md b/docs/07-Pie-Doughnut-Chart.md deleted file mode 100644 index 99830132281..00000000000 --- a/docs/07-Pie-Doughnut-Chart.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: Pie & Doughnut Charts -anchor: doughnut-pie-chart ---- -### Introduction -Pie and doughnut charts are probably the most commonly used charts there are. They are divided into segments, the arc of each segment shows the proportional value of each piece of data. - -They are excellent at showing the relational proportions between data. - -Pie and doughnut charts are effectively the same class in Chart.js, but have one different default value - their `cutoutPercentage`. This equates what percentage of the inner should be cut out. This defaults to `0` for pie charts, and `50` for doughnuts. - -They are also registered under two aliases in the `Chart` core. Other than their different default value, and different alias, they are exactly the same. - -
- -
- -
- -
-
- -### Example Usage - -```javascript -// For a pie chart -var myPieChart = new Chart(ctx,{ - type: 'pie', - data: data, - options: options -}); -``` - -```javascript -// And for a doughnut chart -var myDoughnutChart = new Chart(ctx, { - type: 'doughnut', - data: data, - options: options -}); -``` - -### Dataset Structure - -Property | Type | Usage ---- | --- | --- -data | `Array` | The data to plot as arcs -label | `String` | The label for the dataset which appears in the legend and tooltips -backgroundColor | `Array` | The fill color of the arcs. See [Colors](#chart-configuration-colors) -borderColor | `Array` | Arc border color -borderWidth | `Array` | Border width of arcs in pixels -hoverBackgroundColor | `Array` | Arc background color when hovered -hoverBorderColor | `Array` | Arc border color when hovered -hoverBorderWidth | `Array` | Border width of arc when hovered - -An example data object using these attributes is shown below. - -```javascript -var data = { - labels: [ - "Red", - "Blue", - "Yellow" - ], - datasets: [ - { - data: [300, 50, 100], - backgroundColor: [ - "#FF6384", - "#36A2EB", - "#FFCE56" - ], - hoverBackgroundColor: [ - "#FF6384", - "#36A2EB", - "#FFCE56" - ] - }] -}; -``` - -For a pie chart, datasets need to contain an array of data points. The data points should be a number, Chart.js will total all of the numbers and calculate the relative proportion of each. You can also add an array of background colors. The color attributes should be a string. Similar to CSS, for this string you can use HEX notation, RGB, RGBA or HSL. - -### Chart Options - -These are the customisation options specific to Pie & Doughnut charts. These options are merged with the [global chart configuration options](#global-chart-configuration), and form the options of the chart. - -Name | Type | Default | Description ---- | --- | --- | --- -cutoutPercentage | Number | 50 - for doughnut, 0 - for pie | The percentage of the chart that is cut out of the middle. -rotation | Number | -0.5 * Math.PI | Starting angle to draw arcs from -circumference | Number | 2 * Math.PI | Sweep to allow arcs to cover -*animation*.animateRotate | Boolean |true | If true, will animate the rotation of the chart. -*animation*.animateScale | Boolean | false | If true, will animate scaling the Doughnut from the centre. -*legend*.*labels*.generateLabels | Function | `function(chart) {} ` | Returns a label for each item to be displayed on the legend. -*legend*.onClick | Function | function(event, legendItem) {} ` | Handles clicking an individual legend item - -You can override these for your `Chart` instance by passing a second argument into the `Doughnut` method as an object with the keys you want to override. - -For example, we could have a doughnut chart that animates by scaling out from the centre like so: - -```javascript -new Chart(ctx,{ - type:"doughnut", - options: { - animation:{ - animateScale:true - } - } -}); -// This will create a chart with all of the default options, merged from the global config, -// and the Doughnut chart defaults but this particular instance will have `animateScale` set to `true`. -``` - -We can also change these default values for each Doughnut type that is created, this object is available at `Chart.defaults.doughnut`. Pie charts also have a clone of these defaults available to change at `Chart.defaults.pie`, with the only difference being `cutoutPercentage` being set to 0. diff --git a/docs/08-Bubble-Chart.md b/docs/08-Bubble-Chart.md deleted file mode 100644 index 59b8b773053..00000000000 --- a/docs/08-Bubble-Chart.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: Bubble Chart -anchor: bubble-chart ---- -### Introduction -A bubble chart is used to display three dimensions of data at the same time. The location of the bubble is determined by the first two dimensions and the corresponding horizontal and vertical axes. The third dimension is represented by the size of the individual bubbles. - -
- -
-
- -### Example Usage - -```javascript -// For a bubble chart -var myBubbleChart = new Chart(ctx,{ - type: 'bubble', - data: data, - options: options -}); -``` - -### Dataset Structure - -Property | Type | Usage ---- | --- | --- -data | `Array` | The data to plot as bubbles. See [Data format](#bubble-chart-data-format) -label | `String` | The label for the dataset which appears in the legend and tooltips -backgroundColor | `Color Array` | The fill color of the bubbles. See [Colors](#chart-configuration-colors) -borderColor | `Color or Array` | The stroke color of the bubbles. -borderWidth | `Number or Array` | The stroke width of bubble in pixels. -hoverBackgroundColor | `Color or Array` | The fill color of the bubbles when hovered. -hoverBorderColor | `Color or Array` | The stroke color of the bubbles when hovered. -hoverBorderWidth | `Number or Array` | The stroke width of the bubbles when hovered. -hoverRadius | `Number or Array` | Additional radius to add to data radius on hover. - -An example data object using these attributes is shown below. This example creates a single dataset with 2 different bubbles. - -```javascript -var data = { - datasets: [ - { - label: 'First Dataset', - data: [ - { - x: 20, - y: 30, - r: 15 - }, - { - x: 40, - y: 10, - r: 10 - } - ], - backgroundColor:"#FF6384", - hoverBackgroundColor: "#FF6384", - }] -}; -``` - -### Data Object - -Data for the bubble chart is passed in the form of an object. The object must implement the following interface. It is important to note that the radius property, `r` is **not** scaled by the chart. It is the raw radius in pixels of the bubble that is drawn on the canvas. - -```javascript -{ - // X Value - x: , - - // Y Value - y: , - - // Radius of bubble. This is not scaled. - r: -} -``` - -### Chart Options - -The bubble chart has no unique configuration options. To configure options common to all of the bubbles, the point element options are used. - -For example, to give all bubbles a 1px wide black border, the following options would be used. - -```javascript -new Chart(ctx,{ - type:"bubble", - options: { - elements: { - points: { - borderWidth: 1, - borderColor: 'rgb(0, 0, 0)' - } - } - } -}); -``` - -We can also change the default values for the Bubble chart type. Doing so will give all bubble charts created after this point the new defaults. The default configuration for the bubble chart can be accessed at `Chart.defaults.bubble`. diff --git a/docs/09-Advanced.md b/docs/09-Advanced.md deleted file mode 100644 index 9d1f2834137..00000000000 --- a/docs/09-Advanced.md +++ /dev/null @@ -1,467 +0,0 @@ ---- -title: Advanced usage -anchor: advanced-usage ---- - - -### Prototype Methods - -For each chart, there are a set of global prototype methods on the shared `ChartType` which you may find useful. These are available on all charts created with Chart.js, but for the examples, let's use a line chart we've made. - -```javascript -// For example: -var myLineChart = new Chart(ctx, config); -``` - -#### .destroy() - -Use this to destroy any chart instances that are created. This will clean up any references stored to the chart object within Chart.js, along with any associated event listeners attached by Chart.js. -This must be called before the canvas is reused for a new chart. - -```javascript -// Destroys a specific chart instance -myLineChart.destroy(); -``` - -#### .update(duration, lazy) - -Triggers an update of the chart. This can be safely called after updating the data object. This will update all scales, legends, and then re-render the chart. - -```javascript -// duration is the time for the animation of the redraw in milliseconds -// lazy is a boolean. if true, the animation can be interrupted by other animations -myLineChart.data.datasets[0].data[2] = 50; // Would update the first dataset's value of 'March' to be 50 -myLineChart.update(); // Calling update now animates the position of March from 90 to 50. -``` - -> **Note:** replacing the data reference (e.g. `myLineChart.data = {datasets: [...]}` only works starting **version 2.6**. Prior that, replacing the entire data object could be achieved with the following workaround: `myLineChart.config.data = {datasets: [...]}`. - -#### .reset() - -Reset the chart to it's state before the initial animation. A new animation can then be triggered using `update`. - -```javascript -myLineChart.reset(); -``` - -#### .render(duration, lazy) - -Triggers a redraw of all chart elements. Note, this does not update elements for new data. Use `.update()` in that case. - -```javascript -// duration is the time for the animation of the redraw in milliseconds -// lazy is a boolean. if true, the animation can be interrupted by other animations -myLineChart.render(duration, lazy); -``` - -#### .stop() - -Use this to stop any current animation loop. This will pause the chart during any current animation frame. Call `.render()` to re-animate. - -```javascript -// Stops the charts animation loop at its current frame -myLineChart.stop(); -// => returns 'this' for chainability -``` - -#### .resize() - -Use this to manually resize the canvas element. This is run each time the canvas container is resized, but you can call this method manually if you change the size of the canvas nodes container element. - -```javascript -// Resizes & redraws to fill its container element -myLineChart.resize(); -// => returns 'this' for chainability -``` - -#### .clear() - -Will clear the chart canvas. Used extensively internally between animation frames, but you might find it useful. - -```javascript -// Will clear the canvas that myLineChart is drawn on -myLineChart.clear(); -// => returns 'this' for chainability -``` - -#### .toBase64Image() - -This returns a base 64 encoded string of the chart in it's current state. - -```javascript -myLineChart.toBase64Image(); -// => returns png data url of the image on the canvas -``` - -#### .generateLegend() - -Returns an HTML string of a legend for that chart. The legend is generated from the `legendCallback` in the options. - -```javascript -myLineChart.generateLegend(); -// => returns HTML string of a legend for this chart -``` - -#### .getElementAtEvent(e) - -Calling `getElementAtEvent(event)` on your Chart instance passing an argument of an event, or jQuery event, will return the single element at the event position. If there are multiple items within range, only the first is returned - -```javascript -myLineChart.getElementAtEvent(e); -// => returns the first element at the event point. -``` - -#### .getElementsAtEvent(e) - -Looks for the element under the event point, then returns all elements at the same data index. This is used internally for 'label' mode highlighting. - -Calling `getElementsAtEvent(event)` on your Chart instance passing an argument of an event, or jQuery event, will return the point elements that are at that the same position of that event. - -```javascript -canvas.onclick = function(evt){ - var activePoints = myLineChart.getElementsAtEvent(evt); - // => activePoints is an array of points on the canvas that are at the same position as the click event. -}; -``` - -This functionality may be useful for implementing DOM based tooltips, or triggering custom behaviour in your application. - -#### .getDatasetAtEvent(e) - -Looks for the element under the event point, then returns all elements from that dataset. This is used internally for 'dataset' mode highlighting - -```javascript -myLineChart.getDatasetAtEvent(e); -// => returns an array of elements -``` - -#### .getDatasetMeta(index) - -Looks for the dataset that matches the current index and returns that metadata. This returned data has all of the metadata that is used to construct the chart. - -The `data` property of the metadata will contain information about each point, rectangle, etc. depending on the chart type. - -Extensive examples of usage are available in the [Chart.js tests](https://github.com/chartjs/Chart.js/tree/master/test). - -```javascript -var meta = myChart.getDatasetMeta(0); -var x = meta.data[0]._model.x -``` - -### External Tooltips - -You can enable custom tooltips in the global or chart configuration like so: - -```javascript -var myPieChart = new Chart(ctx, { - type: 'pie', - data: data, - options: { - tooltips: { - custom: function(tooltip) { - // tooltip will be false if tooltip is not visible or should be hidden - if (!tooltip) { - return; - } - - // Otherwise, tooltip will be an object with all tooltip properties like: - - // tooltip.caretSize - // tooltip.caretPadding - // tooltip.chart - // tooltip.cornerRadius - // tooltip.fillColor - // tooltip.font... - // tooltip.text - // tooltip.x - // tooltip.y - // tooltip.caretX - // tooltip.caretY - // etc... - } - } - } -}); -``` - -See `samples/tooltips/line-customTooltips.html` for examples on how to get started. - -### Writing New Scale Types - -Starting with Chart.js 2.0 scales can be individually extended. Scales should always derive from Chart.Scale. - -```javascript -var MyScale = Chart.Scale.extend({ - /* extensions ... */ -}); - -// MyScale is now derived from Chart.Scale -``` - -Once you have created your scale class, you need to register it with the global chart object so that it can be used. A default config for the scale may be provided when registering the constructor. The first parameter to the register function is a string key that is used later to identify which scale type to use for a chart. - -```javascript -Chart.scaleService.registerScaleType('myScale', MyScale, defaultConfigObject); -``` - -To use the new scale, simply pass in the string key to the config when creating a chart. - -```javascript -var lineChart = new Chart(ctx, { - data: data, - type: 'line', - options: { - scales: { - yAxes: [{ - type: 'myScale' // this is the same key that was passed to the registerScaleType function - }] - } - } -}) -``` - -#### Scale Properties - -Scale instances are given the following properties during the fitting process. - -```javascript -{ - left: Number, // left edge of the scale bounding box - right: Number, // right edge of the bounding box' - top: Number, - bottom: Number, - width: Number, // the same as right - left - height: Number, // the same as bottom - top - - // Margin on each side. Like css, this is outside the bounding box. - margins: { - left: Number, - right: Number, - top: Number, - bottom: Number, - }, - - // Amount of padding on the inside of the bounding box (like CSS) - paddingLeft: Number, - paddingRight: Number, - paddingTop: Number, - paddingBottom: Number, -} -``` - -#### Scale Interface -To work with Chart.js, custom scale types must implement the following interface. - -```javascript -{ - // Determines the data limits. Should set this.min and this.max to be the data max/min - determineDataLimits: function() {}, - - // Generate tick marks. this.chart is the chart instance. The data object can be accessed as this.chart.data - // buildTicks() should create a ticks array on the axis instance, if you intend to use any of the implementations from the base class - buildTicks: function() {}, - - // Get the value to show for the data at the given index of the the given dataset, ie this.chart.data.datasets[datasetIndex].data[index] - getLabelForIndex: function(index, datasetIndex) {}, - - // Get the pixel (x coordinate for horizontal axis, y coordinate for vertical axis) for a given value - // @param index: index into the ticks array - // @param includeOffset: if true, get the pixel halway between the given tick and the next - getPixelForTick: function(index, includeOffset) {}, - - // Get the pixel (x coordinate for horizontal axis, y coordinate for vertical axis) for a given value - // @param value : the value to get the pixel for - // @param index : index into the data array of the value - // @param datasetIndex : index of the dataset the value comes from - // @param includeOffset : if true, get the pixel halway between the given tick and the next - getPixelForValue: function(value, index, datasetIndex, includeOffset) {} - - // Get the value for a given pixel (x coordinate for horizontal axis, y coordinate for vertical axis) - // @param pixel : pixel value - getValueForPixel: function(pixel) {} -} -``` - -Optionally, the following methods may also be overwritten, but an implementation is already provided by the `Chart.Scale` base class. - -```javascript - // Transform the ticks array of the scale instance into strings. The default implementation simply calls this.options.ticks.callback(numericalTick, index, ticks); - convertTicksToLabels: function() {}, - - // Determine how much the labels will rotate by. The default implementation will only rotate labels if the scale is horizontal. - calculateTickRotation: function() {}, - - // Fits the scale into the canvas. - // this.maxWidth and this.maxHeight will tell you the maximum dimensions the scale instance can be. Scales should endeavour to be as efficient as possible with canvas space. - // this.margins is the amount of space you have on either side of your scale that you may expand in to. This is used already for calculating the best label rotation - // You must set this.minSize to be the size of your scale. It must be an object containing 2 properties: width and height. - // You must set this.width to be the width and this.height to be the height of the scale - fit: function() {}, - - // Draws the scale onto the canvas. this.(left|right|top|bottom) will have been populated to tell you the area on the canvas to draw in - // @param chartArea : an object containing four properties: left, right, top, bottom. This is the rectangle that lines, bars, etc will be drawn in. It may be used, for example, to draw grid lines. - draw: function(chartArea) {}, -``` - -The Core.Scale base class also has some utility functions that you may find useful. -```javascript -{ - // Returns true if the scale instance is horizontal - isHorizontal: function() {}, - - // Get the correct value from the value from this.chart.data.datasets[x].data[] - // If dataValue is an object, returns .x or .y depending on the return of isHorizontal() - // If the value is undefined, returns NaN - // Otherwise returns the value. - // Note that in all cases, the returned value is not guaranteed to be a Number - getRightValue: function(dataValue) {}, -} -``` - -### Writing New Chart Types - -Chart.js 2.0 introduces the concept of controllers for each dataset. Like scales, new controllers can be written as needed. - -```javascript -Chart.controllers.MyType = Chart.DatasetController.extend({ - -}); - - -// Now we can create a new instance of our chart, using the Chart.js API -new Chart(ctx, { - // this is the string the constructor was registered at, ie Chart.controllers.MyType - type: 'MyType', - data: data, - options: options -}); -``` - -#### Dataset Controller Interface - -Dataset controllers must implement the following interface. - -```javascript -{ - // Create elements for each piece of data in the dataset. Store elements in an array on the dataset as dataset.metaData - addElements: function() {}, - - // Create a single element for the data at the given index and reset its state - addElementAndReset: function(index) {}, - - // Draw the representation of the dataset - // @param ease : if specified, this number represents how far to transition elements. See the implementation of draw() in any of the provided controllers to see how this should be used - draw: function(ease) {}, - - // Remove hover styling from the given element - removeHoverStyle: function(element) {}, - - // Add hover styling to the given element - setHoverStyle: function(element) {}, - - // Update the elements in response to new data - // @param reset : if true, put the elements into a reset state so they can animate to their final values - update: function(reset) {}, -} -``` - -The following methods may optionally be overridden by derived dataset controllers -```javascript -{ - // Initializes the controller - initialize: function(chart, datasetIndex) {}, - - // Ensures that the dataset represented by this controller is linked to a scale. Overridden to helpers.noop in the polar area and doughnut controllers as these - // chart types using a single scale - linkScales: function() {}, - - // Called by the main chart controller when an update is triggered. The default implementation handles the number of data points changing and creating elements appropriately. - buildOrUpdateElements: function() {} -} -``` - -### Extending Existing Chart Types - -Extending or replacing an existing controller type is easy. Simply replace the constructor for one of the built in types with your own. - -The built in controller types are: -* `Chart.controllers.line` -* `Chart.controllers.bar` -* `Chart.controllers.radar` -* `Chart.controllers.doughnut` -* `Chart.controllers.polarArea` -* `Chart.controllers.bubble` - -#### Bar Controller -The bar controller has a special property that you should be aware of. To correctly calculate the width of a bar, the controller must determine the number of datasets that map to bars. To do this, the bar controller attaches a property `bar` to the dataset during initialization. If you are creating a replacement or updated bar controller, you should do the same. This will ensure that charts with regular bars and your new derived bars will work seamlessly. - -### Creating Plugins - -Starting with v2.1.0, you can create plugins for chart.js. To register your plugin, simply call `Chart.plugins.register` and pass your plugin in. -Plugins will be called at the following times -* Start of initialization -* End of initialization -* Start of update -* After the chart scales have calculated -* Start of datasets update -* End of datasets update -* End of update (before render occurs) -* Start of draw -* End of draw -* Before datasets draw -* After datasets draw -* Resize -* Before an animation is started -* When an event occurs on the canvas (mousemove, click, etc). This requires the `options.events` property handled - -Plugins should implement the `IPlugin` interface: -```javascript -{ - beforeInit: function(chart) { }, - afterInit: function(chart) { }, - - resize: function(chart, newChartSize) { }, - - beforeUpdate: function(chart) { }, - afterScaleUpdate: function(chart) { } - beforeDatasetsUpdate: function(chart) { } - afterDatasetsUpdate: function(chart) { } - afterUpdate: function(chart) { }, - - // This is called at the start of a render. It is only called once, even if the animation will run for a number of frames. Use beforeDraw or afterDraw - // to do something on each animation frame - beforeRender: function(chart) { }, - - // Easing is for animation - beforeDraw: function(chart, easing) { }, - afterDraw: function(chart, easing) { }, - // Before the datasets are drawn but after scales are drawn - beforeDatasetsDraw: function(chart, easing) { }, - afterDatasetsDraw: function(chart, easing) { }, - - destroy: function(chart) { } - - // Called when an event occurs on the chart - beforeEvent: function(chart, event) {} - afterEvent: function(chart, event) {} -} -``` - -### Building Chart.js - -Chart.js uses gulp to build the library into a single JavaScript file. - -Firstly, we need to ensure development dependencies are installed. With node and npm installed, after cloning the Chart.js repo to a local directory, and navigating to that directory in the command line, we can run the following: - -```bash -npm install -npm install -g gulp -``` - -This will install the local development dependencies for Chart.js, along with a CLI for the JavaScript task runner gulp. - -Now, we can run the `gulp build` task. - -```bash -gulp build -``` diff --git a/docs/10-Notes.md b/docs/10-Notes.md deleted file mode 100644 index 451a8a8cc90..00000000000 --- a/docs/10-Notes.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: Notes -anchor: notes ---- -### Previous versions - -Version 2 has a completely different API than earlier versions. - -Most earlier version options have current equivalents or are the same. - -Please use the documentation that is available on [chartjs.org](http://www.chartjs.org/docs/) for the current version of Chart.js. - -Please note - documentation for previous versions are available on the GitHub repo. - -- [1.x Documentation](https://github.com/chartjs/Chart.js/tree/v1.1.1/docs) - -### Browser support - -Chart.js offers support for all browsers where canvas is supported. - -Browser support for the canvas element is available in all modern & major mobile browsers (http://caniuse.com/#feat=canvas). - -Thanks to BrowserStack for allowing our team to test on thousands of browsers. - - -### Bugs & issues - -Please report these on the GitHub page - at github.com/chartjs/Chart.js. If you could include a link to a simple jsbin or similar to demonstrate the issue, that'd be really helpful. - - -### Contributing - -New contributions to the library are welcome, but we ask that you please follow these guidelines: - -- Use tabs for indentation, not spaces. -- Only change the individual files in `/src`. -- Check that your code will pass `eslint` code standards, `gulp lint` will run this for you. -- Check that your code will pass tests, `gulp test` will run tests for you. -- Keep pull requests concise, and document new functionality in the relevant `.md` file. -- Consider whether your changes are useful for all users, or if creating a Chart.js plugin would be more appropriate. - -### License - -Chart.js is open source and available under the MIT license. - -### Charting Library Comparison - -Library Features - -| Feature | Chart.js | D3 | HighCharts | Chartist | -| ------- | -------- | --- | ---------- | -------- | -| Completely Free | ✓ | ✓ | | ✓ | -| Canvas | ✓ | | | | -| SVG | | ✓ | ✓ | ✓ | -| Built-in Charts | ✓ | | ✓ | ✓ | -| 8+ Chart Types | ✓ | ✓ | ✓ | | -| Extendable to Custom Charts | ✓ | ✓ | | | -| Supports Modern Browsers | ✓ | ✓ | ✓ | ✓ | -| Extensive Documentation | ✓ | ✓ | ✓ | ✓ | -| Open Source | ✓ | ✓ | ✓ | ✓ | - -Built in Chart Types - -| Type | Chart.js | HighCharts | Chartist | -| ---- | -------- | ---------- | -------- | -| Combined Types | ✓ | ✓ | | -| Line | ✓ | ✓ | ✓ | -| Bar | ✓ | ✓ | ✓ | -| Horizontal Bar | ✓ | ✓ | ✓ | -| Pie/Doughnut | ✓ | ✓ | ✓ | -| Polar Area | ✓ | ✓ | | -| Radar | ✓ | | | -| Scatter | ✓ | ✓ | ✓ | -| Bubble | ✓ | | | -| Gauges | | ✓ | | -| Maps (Heat/Tree/etc.) | | ✓ | | - -### Popular Plugins - -There are many plugins that add additional functionality to Chart.js. Some particularly notable ones are listed here. In addition, many plugins can be found on the [Chart.js GitHub organization](https://github.com/chartjs). - - - chartjs-plugin-annotation.js - Draw lines and boxes on chart area - - chartjs-plugin-deferred.js - Defer initial chart update until chart scrolls into viewport - - chartjs-plugin-draggable.js - Makes select chart elements draggable with the mouse - - chartjs-plugin-zoom.js - Enable zooming and panning on charts - - Chart.BarFunnel.js - Adds a bar funnel chart type - - Chart.LinearGauge.js - Adds a linear gauge chart type - - Chart.Smith.js - Adds a smith chart type - -### Popular Extensions - -There are many extensions which are available for use with popular frameworks. Some particularly notable ones are listed here. - -#### Angular - - angular-chart.js - - tc-angular-chartjs - - angular-chartjs - - Angular Chart-js Directive - -#### React - - react-chartjs2 - - react-chartjs-2 - -#### Django - - Django JChart - - Django Chartjs - -#### Ruby on Rails - - chartjs-ror - -#### Laravel - - laravel-chartjs - -#### Vue.js - - vue-chartjs diff --git a/docs/axes/README.md b/docs/axes/README.md new file mode 100644 index 00000000000..6b619ab8f38 --- /dev/null +++ b/docs/axes/README.md @@ -0,0 +1,112 @@ +# Axes + +Axes are an integral part of a chart. They are used to determine how data maps to a pixel value on the chart. In a cartesian chart, there is 1 or more X axis and 1 or more Y axis to map points onto the 2 dimensional canvas. These axes are know as ['cartesian axes'](./cartesian/README.md#cartesian-axes). + +In a radial chart, such as a radar chart or a polar area chart, there is a single axis that maps points in the angular and radial directions. These are known as ['radial axes'](./radial/README.md#radial-axes). + +Scales in Chart.js >V2.0 are significantly more powerful, but also different than those of v1.0. +* Multiple X & Y axes are supported. +* A built-in label auto-skip feature detects would-be overlapping ticks and labels and removes every nth label to keep things displaying normally. +* Scale titles are supported +* New scale types can be extended without writing an entirely new chart type + +# Common Configuration + +The following properties are common to all axes provided by Chart.js + +## display +**Type:** Boolean +**Default:** `true` +If set to `false` the axis is hidden from view. Overrides *gridLines.display*, *scaleLabel.display*, and *ticks.display*. + +Every scale extends a core scale class with the following options: + +## Callbacks +There are a number of config callbacks that can be used to change parameters in the scale at different points in the update process. + +### beforeUpdate +Callback called before the update process starts. Passed a single argument, the scale instance. + +`beforeUpdate: function(scaleInstance)` + +### beforeSetDimensions +Callback that runs before dimensions are set. Passed a single argument, the scale instance. + +`beforeSetDimensions: function(scaleInstance)` + +### afterSetDimensions +Callback that runs after dimensions are set. Passed a single argument, the scale instance. + +`afterSetDimensions: function(scaleInstance)` + +### beforeDataLimits +Callback that runs before data limits are determined. Passed a single argument, the scale instance. + +`beforeDataLimits: function(scaleInstance)` + +### afterDataLimits +Callback that runs after data limits are determined. Passed a single argument, the scale instance. + +`afterDataLimits: function(scaleInstance)` + +### beforeBuildTicks +Callback that runs before ticks are created. Passed a single argument, the scale instance. + +`beforeBuildTicks: function(scaleInstance)` + +### afterBuildTicks +Callback that runs after ticks are created. Useful for filtering ticks. Passed a single argument, the scale instance. + +`afterBuildTicks: function(scaleInstance)` + +### beforeTickToLabelConversion +Callback that runs before ticks are converted into strings. Passed a single argument, the scale instance. + +`beforeTickToLabelConversion: function(scaleInstance)` + +### afterTickToLabelConversion +Callback that runs after ticks are converted into strings. Passed a single argument, the scale instance. + +`afterTickToLabelConversion: function(scaleInstance)` + +### beforeCalculateTickRotation +Callback that runs before tick rotation is determined. Passed a single argument, the scale instance. + +`beforeCalculateTickRotation: function(scaleInstance)` + +### afterCalculateTickRotation +Callback that runs after tick rotation is determined. Passed a single argument, the scale instance. + +`afterCalculateTickRotation: function(scaleInstance)` + +### beforeFit +Callback that runs before the scale fits to the canvas. Passed a single argument, the scale instance. + +`beforeFit: function(scaleInstance)` + +### afterFit +Callback that runs after the scale fits to the canvas. Passed a single argument, the scale instance. + +`afterFit: function(scaleInstance)` + +### afterUpdate +Callback that runs at the end of the update process. Passed a single argument, the scale instance. + +`afterUpdate: function(scaleInstance)` + +## Updating Axis Defaults + +The default configuration for a scale can be easily changed using the scale service. All you need to do is to pass in a partial configuration that will be merged with the current scale default configuration to form the new default. + +For example, to set the minimum value of 0 for all linear scales, you would do the following. Any linear scales created after this time would now have a minimum of 0. + +```javascript +Chart.scaleService.updateScaleDefaults('linear', { + ticks: { + min: 0 + } +}); +``` + +## Creating New Axes +To create a new axis, see the [developer docs](../developers/axes.md). diff --git a/docs/axes/cartesian/README.md b/docs/axes/cartesian/README.md new file mode 100644 index 00000000000..7bd443164b7 --- /dev/null +++ b/docs/axes/cartesian/README.md @@ -0,0 +1,93 @@ +# Cartesian Axes + +Axes that follow a cartesian grid are known as 'Cartesian Axes'. Cartesian axes are used for line, bar, and bubble charts. Four cartesian axes are included in Chart.js by default. + +* [linear](./linear.md#linear-cartesian-axis) +* [logarithmic](./logarithmic.md#logarithmic-cartesian-axis) +* [category](./category.md#category-cartesian-axis) +* [time](./time.md#time-cartesian-axis) + +# Common Configuration + +All of the included cartesian axes support a number of common options. + +## type +**Type:** String +**Default:** Chart specific +Type of scale being employed. Custom scales can be created and registered with a string key. This allows changing the type of an axis for a chart. + +## position +**Type:** String +Position of the axis in the chart. Possible values are: +* 'top' +* 'left' +* 'bottom' +* 'right'. + +## id +**Type:** String +The ID is used to link datasets and scale axes together. The properties `dataset.xAxisID` or `dataset.yAxisID` have to match the scale properties `scales.xAxes.id` or `scales.yAxes.id`. This is especially needed if multi-axes charts are used. + +```javascript +var myChart = new Chart(ctx, { + type: 'line', + data: { + datasets: [{ + // This dataset appears on the first axis + yAxisID: 'first-y-axis' + }, { + // This dataset appears on the second axis + yAxisID: 'second-y-axis' + }] + }, + options: { + scales: { + yAxes: [{ + id: 'first-y-axis', + type: 'linear' + }, { + id: 'second-y-axis', + type: 'linear' + }] + } + } +}); +``` + +## Tick Configuration +The following options are common to all cartesian axes but do not apply to other axes. + +### autoSkip +**Type:** Boolean +**Default:** `true` +If true, automatically calculates how many labels that can be shown and hides labels accordingly. Turn it off to show all labels no matter what + +### autoSkipPadding +**Type:** Number +**Default:** `0` +Padding between the ticks on the horizontal axis when `autoSkip` is enabled. *Note: Only applicable to horizontal scales.* + +### labelOffset +**Type:** Number +**Default:** `0` +Distance in pixels to offset the label from the centre point of the tick (in the y direction for the x axis, and the x direction for the y axis). *Note: this can cause labels at the edges to be cropped by the edge of the canvas* + +### maxRotation +**Type:** Number +**Default:** `90` +Maximum rotation for tick labels when rotating to condense labels. Note: Rotation doesn't occur until necessary. *Note: Only applicable to horizontal scales.* + +### minRotation +**Type:** Number +**Default:** `0` +Minimum rotation for tick labels. *Note: Only applicable to horizontal scales.* + +### mirror +**Type:** Boolean +**Default:** `false` +Flips tick labels around axis, displaying the labels inside the chart instead of outside. *Note: Only applicable to vertical scales.* + +### padding +**Type:** Number +**Default:** `10` +Padding between the tick label and the axis. *Note: Only applicable to horizontal scales.* \ No newline at end of file diff --git a/docs/axes/cartesian/category.md b/docs/axes/cartesian/category.md new file mode 100644 index 00000000000..0037bed0fe9 --- /dev/null +++ b/docs/axes/cartesian/category.md @@ -0,0 +1,38 @@ +# Category Cartesian Axis + +The category scale will be familiar to those who have used v1.0. Labels are drawn from one of the label arrays included in the chart data. If only `data.labels` is defined, this will be used. If `data.xLabels` is defined and the axis is horizontal, this will be used. Similarly, if `data.yLabels` is defined and the axis is vertical, this property will be used. Using both `xLabels` and `yLabels` together can create a chart that uses strings for both the X and Y axes. + +## Tick Configuration Options + +The category scale provides the following options for configuring tick marks. + +### min +**Type:** String +The minimum item to display. Must be a value in the `labels` array. + +In the example below, the x axis would only display "March" through "June". + +```javascript +let chart = new Chart(ctx, { + type: 'line', + data: { + datasets: [{ + data: [10, 20, 30, 40, 50, 60] + }], + labels: ['January', 'February', 'March', 'April', 'May', 'June'], + }, + options: { + scales: { + xAxes: [{ + ticks: { + min: 'March' + } + }] + } + } +}); +``` + +### max +**Type:** String +The maximum item to display. Must be a value in the `labels` array. \ No newline at end of file diff --git a/docs/axes/cartesian/linear.md b/docs/axes/cartesian/linear.md new file mode 100644 index 00000000000..3c43081f0de --- /dev/null +++ b/docs/axes/cartesian/linear.md @@ -0,0 +1,124 @@ +# Linear Cartesian Axis + +The linear scale is use to chart numerical data. It can be placed on either the x or y axis. The scatter chart type automatically configures a line chart to use one of these scales for the x axis. As the name suggests, linear interpolation is used to determine where a value lies on the axis. + +## Tick Configuration Options + +The following options are provided by the linear scale. They are all located in the `ticks` sub options. + +### beginAtZero +**Type:** Boolean +if true, scale will include 0 if it is not already included. + +```javascript +let options = { + scales: { + yAxes: [{ + ticks: { + beginAtZero: true + } + }] + } +} +``` + +### min +**Type:** Number +User defined minimum number for the scale, overrides minimum value from data. + +```javascript +let options = { + scales: { + yAxes: [{ + type: 'linear', + ticks: { + // y axis now starts at -100 + min: -100 + } + }] + } +}; +``` + +### max +**Type:** Number +User defined maximum number for the scale, overrides maximum value from data. + +```javascript +let options = { + scales: { + yAxes: [{ + type: 'linear', + ticks: { + // y axis now ends at 250 + max: 250 + } + }] + } +}; +``` + +### maxTicksLimit +**Type:** Number +**Default:** 11 +Maximum number of ticks and gridlines to show. + +### stepSize +**Type:** Number +User defined fixed step size for the scale. If set, the scale ticks will be enumerated by multiple of stepSize, having one tick per increment. If not set, the ticks are labeled automatically using the nice numbers algorithm. + +This example sets up a chart with a y axis that creates ticks at `0, 0.5, 1, 1.5, 2, 2.5, 3, 3.5, 4, 4.5, 5`. + +```javascript +let options = { + scales: { + yAxes: [{ + ticks: { + max: 5, + min: 0, + stepSize: 0.5 + } + }] + } +}; +``` + +### suggestedMax +**Type:** Number +Adjustment used when calculating the maximum data value. This can be used to extend the range of the axis while maintaing the auto fit behaviour. + +```javascript +let maxDataValue = Math.max(mostPositiveValue, options.ticks.suggestedMax); +``` + +In this example, the largest positive value is 50, but the data maximum is expanded out to 100. + +```javascript +let chart = new Chart(ctx, { + type: 'line', + data: { + datasets: [{ + label: 'First dataset', + data: [0, 20, 40, 50] + }], + labels: ['January', 'February', 'March', 'April'] + }, + options: { + scales: { + yAxes: [{ + ticks: { + suggestedMax: 100 + } + }] + } + } +}); +``` + +### suggestedMin +**Type:** Number +Adjustment used when calculating the maximum data value. This can be used to extend the range of the axis while maintaing the auto fit behaviour. + +```javascript +let minDataValue = Math.min(mostNegativeValue, options.ticks.suggestedMin); +``` \ No newline at end of file diff --git a/docs/axes/cartesian/logarithmic.md b/docs/axes/cartesian/logarithmic.md new file mode 100644 index 00000000000..2157465c5a5 --- /dev/null +++ b/docs/axes/cartesian/logarithmic.md @@ -0,0 +1,43 @@ +# Logarithmic Cartesian Axis + +The logarithmic scale is use to chart numerical data. It can be placed on either the x or y axis. As the name suggests, logarithmic interpolation is used to determine where a value lies on the axis. + +## Tick Configuration Options + +The following options are provided by the logarithmic scale. They are all located in the `ticks` sub options. + +### min +**Type:** Number +User defined minimum number for the scale, overrides minimum value from data. + +```javascript +let options = { + scales: { + yAxes: [{ + type: 'logarithmic', + ticks: { + // y axis now starts at 1e-03 + min: 0.001 + } + }] + } +}; +``` + +### max +**Type:** Number +User defined maximum number for the scale, overrides maximum value from data. + +```javascript +let options = { + scales: { + yAxes: [{ + type: 'linear', + ticks: { + // y axis now ends at 1e06 + max: 1e06 + } + }] + } +}; +``` \ No newline at end of file diff --git a/docs/axes/cartesian/time.md b/docs/axes/cartesian/time.md new file mode 100644 index 00000000000..b837bd675fb --- /dev/null +++ b/docs/axes/cartesian/time.md @@ -0,0 +1,120 @@ +# Time Cartesian Axis + +The time scale is used to display times and dates. When building its ticks, it will automatically calculate the most comfortable unit base on the size of the scale. + +## Configuration Options + +The following options are provided by the time scale. They are all located in the `time` sub options. + +### displayFormats +**Type:** Object +The following display formats are used to configure how different time units are formed into strings for the axis tick marks. See [moment.js](http://momentjs.com/docs/#/displaying/format/) for the allowable format strings. + +Name | Default +--- | --- +millisecond | 'SSS [ms]' +second | 'h:mm:ss a' +minute | 'h:mm:ss a' +hour | 'MMM D, hA' +day | 'll' +week | 'll' +month | 'MMM YYYY' +quarter | '[Q]Q - YYYY' +year | 'YYYY' + +For example, to set the display format for the 'quarter' unit to show the month and year, the following config would be passed to the chart constructor. + +```javascript +var chart = new Chart(ctx, { + type: 'line', + data: data, + options: { + scales: { + xAxes: [{ + type: 'time', + time: { + displayFormats: { + quarter: 'MMM YYYY' + } + } + }] + } + } +}) +``` + +### isoWeekday +**Type:** Boolean +**Default:** `false` +If true and the unit is set to 'week', iso weekdays will be used. + +### max +**Type:** [Time](#date-formats) +If defined, this will override the data maximum + +### min +**Type:** [Time](#date-formats) +If defined, this will override the data minimum + +### parser +**Type:** String or Function +If defined as a string, it is interpreted as a custom format to be used by moment to parse the date. + +If this is a function, it must return a moment.js object given the appropriate data value. + +### round +**Type:** String +If defined, dates will be rounded to the start of this unit. See [Time Units](#scales-time-units) below for the allowed units. + +### tooltipFormat +**Type:** String +The moment js format string to use for the tooltip. + +### unit +**Type:** String +If defined, will force the unit to be a certain type. See [Time Units](#scales-time-units) section below for details. + +### unitStepSize +**Type:** Number +The number of units between grid lines. + +### minUnit +**Type:** String +**Default:** millisecond' +The minimum display format to be used for a time unit. + +## Date Formats + +When providing data for the time scale, Chart.js supports all of the formats that Moment.js accepts. See [Moment.js docs](http://momentjs.com/docs/#/parsing/) for details. + +## Time Units + +The following time measurements are supported. The names can be passed as strings to the `time.unit` config option to force a certain unit. + +* millisecond +* second +* minute +* hour +* day +* week +* month +* quarter +* year + +For example, to create a chart with a time scale that always displayed units per month, the following config could be used. + +```javascript +var chart = new Chart(ctx, { + type: 'line', + data: data, + options: { + scales: { + xAxes: [{ + time: { + unit: 'month' + } + }] + } + } +}) +``` \ No newline at end of file diff --git a/docs/axes/labelling.md b/docs/axes/labelling.md new file mode 100644 index 00000000000..83fd891ed4a --- /dev/null +++ b/docs/axes/labelling.md @@ -0,0 +1,63 @@ +# Labeling Axes + +When creating a chart, you want to tell the viewer what data they are viewing. To do this, you need to label the axis. + +## Scale Title Configuration + +The scale label configuration is nested under the scale configuration in the `scaleLabel` key. It defines options for the scale title. Note that this only applies to cartesian axes. + +### display +**Type:** Boolean +**Default:** `false` +If true, display the axis title. + +### labelString +**Type:** String +**Default:** `''` +The text for the title. (i.e. "# of People" or "Respone Choices"). + +### fontColor +**Type:** Color +**Default:** `'#666` +Font color for scale title. + +### fontFamily +**Type:** String +**Default:** `"'Helvetica Neue', 'Helvetica', 'Arial', sans-serif"` +Font family for the scale title, follows CSS font-family options. + +### fontSize +**Type:** Number +**Default:** `12` +Font size for scale title. + +### fontStyle +**Type:** String +**Default:** `'normal'` +Font style for the scale title, follows CSS font-style options (i.e. normal, italic, oblique, initial, inherit). + +## Creating Custom Tick Formats + +It is also common to want to change the tick marks to include information about the data type. For example, adding a dollar sign ('$'). To do this, you need to override the `ticks.callback` method in the axis configuration. +In the following example, every label of the Y axis would be displayed with a dollar sign at the front.. + +If the callback returns `null` or `undefined` the associated grid line will be hidden. + +```javascript +var chart = new Chart(ctx, { + type: 'line', + data: data, + options: { + scales: { + yAxes: [{ + ticks: { + // Include a dollar sign in the ticks + callback: function(value, index, values) { + return '$' + value; + } + } + }] + } + } +}); +``` \ No newline at end of file diff --git a/docs/axes/radial/README.md b/docs/axes/radial/README.md new file mode 100644 index 00000000000..64ebe82057c --- /dev/null +++ b/docs/axes/radial/README.md @@ -0,0 +1,5 @@ +# Radial Axes + +Radial axes are used specifically for the radar and polar area chart types. These axes overlay the chart area, rather than being positioned on one of the edges. One radial axis is included by default in Chart.js. + +* [linear](./linear.md#linear-radial-axis) \ No newline at end of file diff --git a/docs/axes/radial/linear.md b/docs/axes/radial/linear.md new file mode 100644 index 00000000000..1fc8905a669 --- /dev/null +++ b/docs/axes/radial/linear.md @@ -0,0 +1,211 @@ +# Linear Radial Axis + +The linear scale is use to chart numerical data. As the name suggests, linear interpolation is used to determine where a value lies in relation the center of the axis. + +The following additional configuration options are provided by the radial linear scale. + +## Configuration Options + +The axis has configuration properties for ticks, angle lines (line that appear in a radar chart outward from the center), pointLabels (labels around the edge in a radar chart). The following sections define each of the properties in those sections. + +## Tick Options +The following options are provided by the linear scale. They are all located in the `ticks` sub options. + +### backdropColor +**Type:** Color +**Default:** `'rgba(255, 255, 255, 0.75)'` +Color of label backdrops. + +### backdropPaddingX +**Type:** Number +**Default:** 2 +Horizontal padding of label backdrop. + +### backdropPaddingY +**Type:** Number +**Default:** 2 +Vertical padding of label backdrop. + +### beginAtZero +**Type:** Boolean +if true, scale will include 0 if it is not already included. + +```javascript +let options = { + scales: { + yAxes: [{ + ticks: { + beginAtZero: true + } + }] + } +} +``` + +### min +**Type:** Number +User defined minimum number for the scale, overrides minimum value from data. + +```javascript +let options = { + scales: { + yAxes: [{ + type: 'linear', + ticks: { + // y axis now starts at -100 + min: -100 + } + }] + } +}; +``` + +### max +**Type:** Number +User defined maximum number for the scale, overrides maximum value from data. + +```javascript +let options = { + scales: { + yAxes: [{ + type: 'linear', + ticks: { + // y axis now ends at 250 + max: 250 + } + }] + } +}; +``` + +### maxTicksLimit +**Type:** Number +**Default:** 11 +Maximum number of ticks and gridlines to show. + +### stepSize +**Type:** Number +User defined fixed step size for the scale. If set, the scale ticks will be enumerated by multiple of stepSize, having one tick per increment. If not set, the ticks are labeled automatically using the nice numbers algorithm. + +This example sets up a chart with a y axis that creates ticks at `0, 0.5, 1, 1.5, 2, 2.5, 3, 3.5, 4, 4.5, 5`. + +```javascript +let options = { + scales: { + yAxes: [{ + ticks: { + max: 5, + min: 0, + stepSize: 0.5 + } + }] + } +}; +``` + +### suggestedMax +**Type:** Number +Adjustment used when calculating the maximum data value. This can be used to extend the range of the axis while maintaing the auto fit behaviour. + +```javascript +let maxDataValue = Math.max(mostPositiveValue, options.ticks.suggestedMax); +``` + +In this example, the largest positive value is 50, but the data maximum is expanded out to 100. + +```javascript +let chart = new Chart(ctx, { + type: 'line', + data: { + datasets: [{ + label: 'First dataset', + data: [0, 20, 40, 50] + }], + labels: ['January', 'February', 'March', 'April'] + }, + options: { + scales: { + yAxes: [{ + ticks: { + suggestedMax: 100 + } + }] + } + } +}); +``` + +### suggestedMin +**Type:** Number +Adjustment used when calculating the maximum data value. This can be used to extend the range of the axis while maintaing the auto fit behaviour. + +```javascript +let minDataValue = Math.min(mostNegativeValue, options.ticks.suggestedMin); +``` + +### showLabelBackdrop +**Type:** Boolean +**Default:** `true` +If true, draw a background behind the tick labels. + +## Angle Line Options + +The following options are used to configure angled lines that radiate from the center of the chart to the point labels. They can be found in the `angleLines` sub options. Note that these options only apply if `lineArc` is false. + +### display +**Type:** Boolean +**Default:** `true` +If true, angle lines are shown. + +### color +**Type:** Color +**Default:** `rgba(0, 0, 0, 0.1)` +Color of angled lines + +### lineWidth +**Type:** Number +**Default:** `1` +Width of angled lines + +## Point Label Options + +The following options are used to configure the point labels that are shown on the perimeter of the scale. They can be found in the `pointLabels` sub options. Note that these options only apply if `lineArc` is false. + +### callback +**Type:** Function +Callback function to transform data labels to point labels. The default implementation simply returns the current string. + +### fontColor +**Type:** Color +**default:** `'#666'` +Font color for point labels. + +To render the point labels in red text, one would do: +```javascript +let radar = new Chart(ctx, { + type: 'radar', + data: data, + options: { + scale: { + pointLabels: { + fontColor: 'rgb(255, 0, 0)' + } + } + } +}) +``` + +### fontFamily +**Type:** String +**default:** `"'Helvetica Neue', 'Helvetica', 'Arial', sans-serif"` +Font family to use when rendering labels. + +### fontSize +**Type:** Number +**default:** 10 +Font size in pixels. + +### fontStyle +**Type:** String +**default:** 'normal' +Font style to use when rendering point labels. \ No newline at end of file diff --git a/docs/axes/styling.md b/docs/axes/styling.md new file mode 100644 index 00000000000..9be973fcdb7 --- /dev/null +++ b/docs/axes/styling.md @@ -0,0 +1,104 @@ +# Styling + +There are a number of options to allow styling an axis. There are settings to control [grid lines](#grid-line-configuration) and [ticks](#tick-configuration). + +## Grid Line Configuration + +The grid line configuration is nested under the scale configuration in the `gridLines` key. It defines options for the grid lines that run perpendicular to the axis. + +### display +**Type:** Boolean +**Default:** `true` +If false, do not display grid lines for this axis. + +### color +**Type:** Color or Color[] +**Default:** `"rgba(0, 0, 0, 0.1)"` +The color of the grid lines. If specified as an array, the first color applies to the first grid line, the second to the second grid line and so on. + +### borderDash +**Type:** Number[] +**Default:** `[]` +Length and spacing of dashes on grid lines. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash) + +### borderDashOffset +**Type:** Number +**Default:** `0.0` +Offset for line dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset) + +### lineWidth +**Type:** Number of Number[] +**Default:** `1` +Stroke width of grid lines. + +### drawBorder +**Type:** Boolean +**Default:** `true` +If true, draw border at the edge between the axis and the chart area. + +### drawOnChartArea +**Type:** Boolean +**Default:** `true` +If true, draw lines on the chart area inside the axis lines. This is useful when there are multiple axes and you need to control which grid lines are drawn. + +### drawTicks +**Type:** Boolean +**Default:** `true` +If true, draw lines beside the ticks in the axis area beside the chart. + +### tickMarkLength +**Type:** Number +**Default:** `10` +Length in pixels that the grid lines will draw into the axis area. + +### zeroLineWidth +**Type:** Number +**Default:** `1` +Stroke width of the grid line for the first index (index 0). + +### zeroLineColor +**Type:** Color +**Default:** "rgba(0, 0, 0, 0.25)" +Stroke color of the grid line for the first index (index 0). + +### offsetGridLines +**Type:** Boolean +**Default:** `false` +If true, labels are shifted to be between grid lines. This is used in the bar chart and should not generally be used. + +## Tick Configuration +The tick configuration is nested under the scale configuration in the `ticks` key. It defines options for the tick marks that are generated by the axis. + +### callback +**Type:** Function +Returns the string representation of the tick value as it should be displayed on the chart. See [callback](../axes/labelling.md#creating-custom-tick-formats). + +### display +**Type:** Boolean +**Default:** `true` +If true, show tick marks. + +### fontColor +**Type:** Color +**Default:** `'#666'` +Font color for tick labels. + +### fontFamily +**Type:** String +**Default:** `"'Helvetica Neue', 'Helvetica', 'Arial', sans-serif"` +Font family for the tick labels, follows CSS font-family options. + +### fontSize +**Type:** Number +**Default:** `12` +Font size for the tick labels. + +### fontStyle +**Type:** String +**Default:** `'normal'` +Font style for the tick labels, follows CSS font-style options (i.e. normal, italic, oblique, initial, inherit). + +### reverse +**Type:** Boolean +**Default:** `false` +Reverses order of tick labels. \ No newline at end of file diff --git a/docs/charts/README.md b/docs/charts/README.md new file mode 100644 index 00000000000..0c731fa75d4 --- /dev/null +++ b/docs/charts/README.md @@ -0,0 +1,3 @@ +# Charts + +Chart.js comes with built-in chart types for line, bar, radar, polar area and doughnut charts. To create a new chart type, see the [developer notes](../developers/charts.md#new-charts) \ No newline at end of file diff --git a/docs/charts/bar.md b/docs/charts/bar.md new file mode 100644 index 00000000000..b2624ea6d62 --- /dev/null +++ b/docs/charts/bar.md @@ -0,0 +1,218 @@ +# Bar +A bar chart provides a way of showing data values represented as vertical bars. It is sometimes used to show trend data, and the comparison of multiple data sets side by side. + +## Example Usage +```javascript +var myBarChart = new Chart(ctx, { + type: 'bar', + data: data, + options: options +}); +``` + +## Dataset Properties +The bar chart allows a number of properties to be specified for each dataset. These are used to set display properties for a specific dataset. For example, the colour of the bars is generally set this way. + +Some properties can be specified as an array. If these are set to an array value, the first value applies to the first bar, the second value to the second bar, and so on. + +### label +**Type:** String +The label for the dataset which appears in the legend and tooltips. + +### xAxisID +**Type:** String +The ID of the x axis to plot this dataset on. If not specified, this defaults to the ID of the first found x axis + +### yAxisID +**Type:** String +The ID of the y axis to plot this dataset on. If not specified, this defaults to the ID of the first found y axis. + +### backgroundColor +**Type:** Color or Color[] +The fill color of the bar. See [Colors](../general/colors.md#colors) + +### borderColor +**Type:** Color or Color[] +The color of the bar border. See [Colors](../general/colors.md#colors) + +### borderWidth +**Type:** Number or Number[] +The stroke width of the bar in pixels. + +### borderSkipped +**Type:** String +Which edge to skip drawing the border for. This setting is used to avoid drawing the bar stroke at the base of the fill. In general, this does not need to be changed except when creating chart types that derive from a bar chart. + +Options are: +* 'bottom' +* 'left' +* 'top' +* 'right' + +### hoverBackgroundColor +**Type:** Color or Color[] +The fill colour of the bars when hovered. + +### hoverBorderColor +**Type:** Color or Color[] +The stroke colour of the bars when hovered. + +### hoverBorderWidth +**Type:** Number of Number[] +The stroke width of the bars when hovered. + +## Configuration Options + +The bar chart defines the following configuration options. These options are merged with the global chart configuration options, `Chart.defaults.global`, to form the options passed to the chart. + +### barPercentage +**Type:** Number +**Default:** `0.9` +Percent (0-1) of the available width each bar should be within the category percentage. 1.0 will take the whole category width and put the bars right next to each other. [Read More](#bar-chart-barpercentage-vs-categorypercentage) + +This setting applies to the axis configuration for a bar chart. If axes are added to the chart, this setting will need to be set for each new axis. + +```javascript +options = { + scales: { + xAxes: [{ + barPercentage: 0.8 + }] + } +} +``` + +### categoryPercentage +**Type:** Number +**Default:** `0.8` +Percent (0-1) of the available width (the space between the gridlines for small datasets) for each data-point to use for the bars. [Read More](#bar-chart-barpercentage-vs-categorypercentage) + +This setting applies to the axis configuration for a bar chart. If axes are added to the chart, this setting will need to be set for each new axis. + +```javascript +options = { + scales: { + xAxes: [{ + categoryPercentage: 0.8 + }] + } +} +``` + +### barThickness +**Types:** Number + +Manually set width of each bar in pixels. If not set, the bars are sized automatically using [barPercentage](#barPercentage) and [categoryPercentage](#categoryPercentage); + +This setting applies to the axis configuration for a bar chart. If axes are added to the chart, this setting will need to be set for each new axis. + +```javascript +options = { + scales: { + xAxes: [{ + barThickness: 25 + }] + } +} +``` + +### offsetGridLines +**Type:** Boolean +**Default:** `true` +If true, the bars for a particular data point fall between the grid lines. If false, the grid line will go right down the middle of the bars. It is unlikely that this will ever need to be changed in practice. It exists more as a way to reuse the axis code by configuring the existing axis slightly differently. + +This setting applies to the axis configuration for a bar chart. If axes are added to the chart, this setting will need to be set for each new axis. + +```javascript +options = { + scales: { + xAxes: [{ + gridLines: { + offsetGridLines: true + } + }] + } +} +``` + +## Default Options + +It is common to want to apply a configuration setting to all created bar charts. The global bar chart settings are stored in `Chart.defaults.bar`. Changing the global options only affects charts created after the change. Existing charts are not changed. + +## barPercentage vs categoryPercentage + +The following shows the relationship between the bar percentage option and the category percentage option. + +```text +// categoryPercentage: 1.0 +// barPercentage: 1.0 +Bar: | 1.0 | 1.0 | +Category: | 1.0 | +Sample: |===========| + +// categoryPercentage: 1.0 +// barPercentage: 0.5 +Bar: |.5| |.5| +Category: | 1.0 | +Sample: |==============| + +// categoryPercentage: 0.5 +// barPercentage: 1.0 +Bar: |1.||1.| +Category: | .5 | +Sample: |==============| +``` + +## Data Structure + +The `data` property of a dataset for a bar chart is specified as a an array of numbers. Each point in the data array corresponds to the label at the same index on the x axis. + +```javascript +data: [20, 10] +``` + +# Stacked Bar Chart + +Bar charts can be configured into stacked bar charts by changing the settings on the X and Y axes to enable stacking. Stacked bar charts can be used to show how one data series is made up of a number of smaller pieces. + +```javascript +var stackedBar = new Chart(ctx, { + type: 'bar', + data: data, + options: { + scales: { + xAxes: [{ + stacked: true + }], + yAxes: [{ + stacked: true + }] + } + } +}); +``` + +## Dataset Properties + +The following dataset properties are specific to stacked bar charts. + +### Stack +**Type:** String +The ID of the group to which this dataset belongs to (when stacked, each group will be a separate stack) + +# Horizontal Bar Chart +A horizontal bar chart is a variation on a vertical bar chart. It is sometimes used to show trend data, and the comparison of multiple data sets side by side. + +## Example +```javascript +var myBarChart = new Chart(ctx, { + type: 'horizontalBar', + data: data, + options: options +}); +``` + +## Config Options +The configuration options for the horizontal bar chart are the same as for the [bar chart](../bar/config-options.md#config-options). However, any options specified on the x axis in a bar chart, are applied to the y axis in a horizontal bar chart. + +The default horizontal bar configuration is specified in `Chart.defaults.horizontalBar`. \ No newline at end of file diff --git a/docs/charts/bubble.md b/docs/charts/bubble.md new file mode 100644 index 00000000000..b93d8dcce52 --- /dev/null +++ b/docs/charts/bubble.md @@ -0,0 +1,81 @@ +# Bubble Chart + +A bubble chart is used to display three dimensions of data at the same time. The location of the bubble is determined by the first two dimensions and the corresponding horizontal and vertical axes. The third dimension is represented by the size of the individual bubbles. + +## Example Usage + +```javascript +// For a bubble chart +var myBubbleChart = new Chart(ctx,{ + type: 'bubble', + data: data, + options: options +}); +``` + +## Dataset Properties + +The bubble chart allows a number of properties to be specified for each dataset. These are used to set display properties for a specific dataset. For example, the colour of the bubbles is generally set this way. + +All properties, except `label` can be specified as an array. If these are set to an array value, the first value applies to the first bubble in the dataset, the second value to the second bubble, and so on. + +### label +**Type:** String +The label for the dataset which appears in the legend and tooltips. + +### backgroundColor +**Type:** Color or Color[] +The fill color for bubbles. + +### borderColor +**Type:** Color or Color[] +The border color for bubbles. + +### borderWidth +**Type:** Number Number[] +The width of the point bubbles in pixels. + +### hoverBackgroundColor +**Type:** Color or Color[] +Bubble background color when hovered. + +### hoverBorderColor +**Type:** Color or Color[] +Bubble border color when hovered. + +### hoverBorderWidth +**Type:** Number or Number[] +Border width of point when hovered. + +### hoverRadius +**Type:** Number or Number[] +Additional radius to add to data radius on hover. + +## Config Options + +The bubble chart has no unique configuration options. To configure options common to all of the bubbles, the [point element options](../configuration/elements/point.md#point-configuration) are used. + +## Default Options + +We can also change the default values for the Bubble chart type. Doing so will give all bubble charts created after this point the new defaults. The default configuration for the bubble chart can be accessed at `Chart.defaults.bubble`. + +## Data Structure + +For a bubble chart, datasets need to contain an array of data points. Each point must implement the [bubble data object](#bubble-data-object) interface. + +### Bubble Data Object + +Data for the bubble chart is passed in the form of an object. The object must implement the following interface. It is important to note that the radius property, `r` is **not** scaled by the chart. It is the raw radius in pixels of the bubble that is drawn on the canvas. + +```javascript +{ + // X Value + x: , + + // Y Value + y: , + + // Radius of bubble. This is not scaled. + r: +} +``` \ No newline at end of file diff --git a/docs/charts/doughnut.md b/docs/charts/doughnut.md new file mode 100644 index 00000000000..b757a99a81e --- /dev/null +++ b/docs/charts/doughnut.md @@ -0,0 +1,130 @@ +# Doughnut and Pie +Pie and doughnut charts are probably the most commonly used charts. They are divided into segments, the arc of each segment shows the proportional value of each piece of data. + +They are excellent at showing the relational proportions between data. + +Pie and doughnut charts are effectively the same class in Chart.js, but have one different default value - their `cutoutPercentage`. This equates what percentage of the inner should be cut out. This defaults to `0` for pie charts, and `50` for doughnuts. + +They are also registered under two aliases in the `Chart` core. Other than their different default value, and different alias, they are exactly the same. + +## Example Usage + +```javascript +// For a pie chart +var myPieChart = new Chart(ctx,{ + type: 'pie', + data: data, + options: options +}); +``` + +```javascript +// And for a doughnut chart +var myDoughnutChart = new Chart(ctx, { + type: 'doughnut', + data: data, + options: options +}); +``` + +## Dataset Properties + +The doughnut/pie chart allows a number of properties to be specified for each dataset. These are used to set display properties for a specific dataset. For example, the colour of a the dataset's arc are generally set this way. + +### label +**Type:** String +The label for the dataset which appears in the legend and tooltips. + +### backgroundColor +**Type:** Color[] +The fill color of the arcs in the dataset. See [Colors](../general/colors.md#colors) + +### borderColor +**Type:** Color[] +The border color of the arcs in the dataset. See [Colors](../general/colors.md#colors) + +### borderWidth +**Type:** Number[] +The border width of the arcs in the dataset. + +### hoverBackgroundColor +**Type:** Color[] +The fill colour of the arcs when hovered. + +### hoverBorderColor +**Type:** Color[] +The stroke colour of the arcs when hovered. + +### hoverBorderWidth +**Type:** Number[] +The stroke width of the arcs when hovered. + +## Config Options + +These are the customisation options specific to Pie & Doughnut charts. These options are merged with the global chart configuration options, and form the options of the chart. + +### cutoutPercentage +**Type:** Number +**Default:** `50` - for doughnut, `0` - for pie +The percentage of the chart that is cut out of the middle. + +### rotation +**Type:** Number +**Default:** `-0.5 * Math.PI` +Starting angle to draw arcs from + +### circumference +**Type:** Number +**Default:** `2 * Math.PI` +Sweep to allow arcs to cover + +### animateRotate +**Type:** Boolean +**Default:** `true` +If true, the chart will animate in with a rotation animation. This property is in the `options.animation` object. + +```javascript +options = { + animation: { + animateRotate: false + } +}; +``` + +### animateScale +**Type:** Boolean +**Default:** `false` +If true, will animate scaling the chart from the center outwards. This property is in the `options.animation` object. + +```javascript +options = { + animation: { + animateScale: true + } +}; +``` + +## Default Options + +We can also change these default values for each Doughnut type that is created, this object is available at `Chart.defaults.doughnut`. Pie charts also have a clone of these defaults available to change at `Chart.defaults.pie`, with the only difference being `cutoutPercentage` being set to 0. + +## Data Structure + +For a pie chart, datasets need to contain an array of data points. The data points should be a number, Chart.js will total all of the numbers and calculate the relative proportion of each. + +You also need to specify an array of labels so that tooltips appear correctly + +```javascript +data = { + datasets: [{ + data: [10, 20, 30] + }], + + // These labels appear in the legend and in the tooltips when hovering different arcs + labels: [ + 'Red', + 'Yellow', + 'Blue' + ] +}; +``` \ No newline at end of file diff --git a/docs/charts/line.md b/docs/charts/line.md new file mode 100644 index 00000000000..5848573c63d --- /dev/null +++ b/docs/charts/line.md @@ -0,0 +1,214 @@ +# Line +A line chart is a way of plotting data points on a line. Often, it is used to show trend data, or the comparison of two data sets. + +## Example Usage +```javascript +var myLineChart = new Chart(ctx, { + type: 'line', + data: data, + options: options +}); +``` + +## Dataset Properties + +The line chart allows a number of properties to be specified for each dataset. These are used to set display properties for a specific dataset. For example, the colour of a line is generally set this way. + +All point* properties can be specified as an array. If these are set to an array value, the first value applies to the first point, the second value to the second point, and so on. + +### label +**Type:** String +The label for the dataset which appears in the legend and tooltips. + +### xAxisID +**Type:** String +The ID of the x axis to plot this dataset on. If not specified, this defaults to the ID of the first found x axis + +### yAxisID +**Type:** String +The ID of the y axis to plot this dataset on. If not specified, this defaults to the ID of the first found y axis. + +### backgroundColor +**Type:** Color +The fill color under the line. See [Colors](../general/colors.md#colors) + +### borderColor +**Type:** Color +The color of the line. See [Colors](../general/colors.md#colors) + +### borderWidth +**Type:** Number +The width of the line in pixels. + +### borderDash +**Type:** Number[] +Length and spacing of dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash) + +### borderDashOffset +**Type:** Number +Offset for line dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset) + +### borderCapStyle +**Type:** String +Cap style of the line. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineCap) + +### borderJoinStyle +**Type:** String +Line joint style. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin) + +### cubicInterpolationMode +**Type:** String +Algorithm used to interpolate a smooth curve from the discrete data points. + +Options are: +* 'default' +* 'monotone'. + +The 'default' algorithm uses a custom weighted cubic interpolation, which produces pleasant curves for all types of datasets. + +The 'monotone' algorithm is more suited to `y = f(x)` datasets : it preserves monotonicity (or piecewise monotonicity) of the dataset being interpolated, and ensures local extremums (if any) stay at input data points. + +If left untouched (`undefined`), the global `options.elements.line.cubicInterpolationMode` property is used. + +### fill +**Type:** Boolean or String +If `true`, fill the area under the line. The line is filled to the baseline. If the y axis has a 0 value, the line is filled to that point. If the axis has only negative values, the line is filled to the highest value. If the axis has only positive values, it is filled to the lowest value. + +String values to fill to specific locations are: +* `'zero'` +* `'top'` +* `'bottom'` + +### lineTension +**Type** Number +Bezier curve tension of the line. Set to 0 to draw straightlines. This option is ignored if monotone cubic interpolation is used. + +### pointBackgroundColor +**Type:** Color or Color[] +The fill color for points. + +### pointBorderColor +**Type:** Color or Color[] +The border color for points. + +### pointBorderWidth +**Type:** Number Number[] +The width of the point border in pixels. + +### pointRadius +**Type:** Number Number[] +The radius of the point shape. If set to 0, the point is not rendered. + +### pointStyle +**Type:** String, String[], Image, Image[] +The style of point. Options are: +* 'circle' +* 'cross' +* 'crossRot' +* 'dash'. +* 'line' +* 'rect' +* 'rectRounded' +* 'rectRot' +* 'star' +* 'triangle' + +If the option is an image, that image is drawn on the canvas using [drawImage](https://developer.mozilla.org/en/docs/Web/API/CanvasRenderingContext2D/drawImage). + +### pointHitRadius +**Type:** Number or Number[] +The pixel size of the non-displayed point that reacts to mouse events. + +### pointHoverBackgroundColor +**Type:** Color or Color[] +Point background color when hovered. + +### pointHoverBorderColor +**Type:** Color or Color[] +Point border color when hovered. + +### pointHoverBorderWidth +**Type:** Number or Number[] +Border width of point when hovered. + +### pointHoverRadius +**Type:** Number or Number[] +The radius of the point when hovered. + +### showLine +**Type:** `Boolean` +If false, the line is not drawn for this dataset. + +### spanGaps +**Type:** `Boolean` +If true, lines will be drawn between points with no or null data. If false, points with `NaN` data will create a break in the line + +### steppedLine +**Type:** `Boolean` +If true, the line is shown as a stepped line and 'lineTension' will be ignored. + +## Configuration Options + +The line chart defines the following configuration options. These options are merged with the global chart configuration options, `Chart.defaults.global`, to form the options passed to the chart. + +### showLines +**Type:** Boolean +**Default:** `true` +If false, the lines between points are not drawn. + +### spanGaps +**Type:** Boolean +**Default:** `false` +If false, NaN data causes a break in the line. + +## Default Options + +It is common to want to apply a configuration setting to all created line charts. The global line chart settings are stored in `Chart.defaults.line`. Changing the global options only affects charts created after the change. Existing charts are not changed. + +For example, to configure all line charts with `spanGaps = true` you would do: +```javascript +Chart.defaults.line.spanGaps = true; +``` + +## Data Structure + +The `data` property of a dataset for a line chart can be passed in two formats. + +### Number[] +```javascript +data: [20, 10] +``` + +When the `data` array is an array of numbers, the x axis is generally a [category](../axes/cartesian/category.md#Category Axis). The points are placed onto the axis using their position in the array. + +### Point[] + +```javascript +data: [{ + x: 10, + y: 20 + }, { + x: 15, + y: 10 + }] +``` + +This alternate is used for sparse datasets, such as those in [scatter charts](./scatter.md#scatter-chart). Each data point is specified using an object containing `x` and `y` properties. + +# Stacked Area Chart + +Line charts can be configured into stacked area charts by changing the settings on the y axis to enable stacking. Stacked area charts can be used to show how one data trend is made up of a number of smaller pieces. + +```javascript +var stackedLine = new Chart(ctx, { + type: 'line', + data: data, + options: { + scales: { + yAxes: [{ + stacked: true + }] + } + } +}); + diff --git a/docs/charts/mixed.md b/docs/charts/mixed.md new file mode 100644 index 00000000000..72c3e40853b --- /dev/null +++ b/docs/charts/mixed.md @@ -0,0 +1,37 @@ +# Mixed Chart Types + +With Chart.js, it is possible to create mixed charts that are a combination of two or more different chart types. A common example is a bar chart that also includes a line dataset. + +Creating a mixed chart starts with the initialization of a basic chart. + +```javascript +var myChart = new Chart(ctx, { + type: 'bar', + data: data, + options: options +}); +``` + +At this point we have a standard bar chart. Now we need to convert one of the datasets to a line dataset. + +```javascript +var mixedChart = new Chart(ctx, { + type: 'bar', + data: { + datasets: [{ + label: 'Bar Dataset', + data: [10, 20, 30, 40] + }, { + label: 'Line Dataset', + data: [50, 50, 50, 50], + + // Changes this dataset to become a line + type: 'line' + }], + labels: ['January', 'February', 'March', 'April'] + }, + options: options +}); +``` + +At this point we have a chart rendering how we'd like. It's important to note that the default options for a line chart are not merged in this case. Only the options for the default type are merged in. In this case, that means that the default options for a bar chart are merged because that is the type specified by the `type` field. \ No newline at end of file diff --git a/docs/charts/polar.md b/docs/charts/polar.md new file mode 100644 index 00000000000..2f0289790aa --- /dev/null +++ b/docs/charts/polar.md @@ -0,0 +1,112 @@ +# Polar Area + +Polar area charts are similar to pie charts, but each segment has the same angle - the radius of the segment differs depending on the value. + +This type of chart is often useful when we want to show a comparison data similar to a pie chart, but also show a scale of values for context. + +## Example Usage + +```javascript +new Chart(ctx, { + data: data, + type: 'polarArea', + options: options +}); +``` + +## Dataset Properties + +The following options can be included in a polar area chart dataset to configure options for that specific dataset. + +### label +**Type:** String +The label for the dataset which appears in the legend and tooltips. + +### backgroundColor +**Type:** Color[] +The fill color of the arcs in the dataset. See [Colors](../general/colors.md#colors) + +### borderColor +**Type:** Color[] +The border color of the arcs in the dataset. See [Colors](../general/colors.md#colors) + +### borderWidth +**Type:** Number[] +The border width of the arcs in the dataset. + +### hoverBackgroundColor +**Type:** Color[] +The fill colour of the arcs when hovered. + +### hoverBorderColor +**Type:** Color[] +The stroke colour of the arcs when hovered. + +### hoverBorderWidth +**Type:** Number[] +The stroke width of the arcs when hovered. + +## Config Options + +These are the customisation options specific to Polar Area charts. These options are merged with the [global chart configuration options](#global-chart-configuration), and form the options of the chart. + +### startAngle +**Type:** Number +**Default:** `-0.5 * Math.PI` +Starting angle to draw arcs for the first item in a dataset. + +### animateRotate +**Type:** Boolean +**Default:** `true` +If true, the chart will animate in with a rotation animation. This property is in the `options.animation` object. + +```javascript +options = { + animation: { + animateRotate: false + } +}; +``` + +### animateScale +**Type:** Boolean +**Default:** `true` +If true, will animate scaling the chart from the center outwards. This property is in the `options.animation` object. + +```javascript +options = { + animation: { + animateScale: true + } +}; +``` + +## Default Options + +We can also change these defaults values for each PolarArea type that is created, this object is available at `Chart.defaults.polarArea`. Changing the global options only affects charts created after the change. Existing charts are not changed. + +For example, to configure all new polar area charts with `animateScale = false` you would do: +```javascript +Chart.defaults.polarArea.animation.animateScale = false; +``` + +## Data Structure + +For a polar area chart, datasets need to contain an array of data points. The data points should be a number, Chart.js will total all of the numbers and calculate the relative proportion of each. + +You also need to specify an array of labels so that tooltips appear correctly for each slice. + +```javascript +data = { + datasets: [{ + data: [10, 20, 30] + }], + + // These labels appear in the legend and in the tooltips when hovering different arcs + labels: [ + 'Red', + 'Yellow', + 'Blue' + ] +}; +``` \ No newline at end of file diff --git a/docs/charts/radar.md b/docs/charts/radar.md new file mode 100644 index 00000000000..e7234fde6f6 --- /dev/null +++ b/docs/charts/radar.md @@ -0,0 +1,151 @@ +# Radar +A radar chart is a way of showing multiple data points and the variation between them. + +They are often useful for comparing the points of two or more different data sets. + +## Example Usage +```javascript +var myRadarChart = new Chart(ctx, { + type: 'radar', + data: data, + options: options +}); +``` + +## Dataset Properties + +The radar chart allows a number of properties to be specified for each dataset. These are used to set display properties for a specific dataset. For example, the colour of a line is generally set this way. + +All point* properties can be specified as an array. If these are set to an array value, the first value applies to the first point, the second value to the second point, and so on. + +### Label +**Type:** String +The label for the dataset which appears in the legend and tooltips. + +### backgroundColor +**Type:** Color +The fill color under the line. See [Colors](../general/colors.md#colors) + +### borderColor +**Type:** Color +The color of the line. See [Colors](../general/colors.md#colors) + +### borderWidth +**Type:** Number +The width of the line in pixels. + +### borderDash +**Type:** Number[] +Length and spacing of dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash) + +### borderDashOffset +**Type:** Number +Offset for line dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset) + +### borderCapStyle +**Type:** String +Cap style of the line. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineCap) + +### borderJoinStyle +**Type:** String +Line joint style. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin) + +### fill +**Type:** Boolean +If true, fill the area under the line. The line is filled to the baseline. If the y axis has a 0 value, the line is filled to that point. If the axis has only negative values, the line is filled to the highest value. If the axis has only positive values, it is filled to the lowest value. + +### lineTension +**Type** Number +Bezier curve tension of the line. Set to 0 to draw straightlines. This option is ignored if monotone cubic interpolation is used. + +### pointBackgroundColor +**Type:** Color or Color[] +The fill color for points. + +### pointBorderColor +**Type:** Color or Color[] +The border color for points. + +### pointBorderWidth +**Type:** Number Number[] +The width of the point border in pixels. + +### pointRadius +**Type:** Number Number[] +The radius of the point shape. If set to 0, the point is not rendered. + +### pointStyle +**Type:** String, String[], Image, Image[] +The style of point. Options are: +* 'circle' +* 'cross' +* 'crossRot' +* 'dash'. +* 'line' +* 'rect' +* 'rectRounded' +* 'rectRot' +* 'star' +* 'triangle' + +If the option is an image, that image is drawn on the canvas using [drawImage](https://developer.mozilla.org/en/docs/Web/API/CanvasRenderingContext2D/drawImage). + +### pointHitRadius +**Type:** Number or Number[] +The pixel size of the non-displayed point that reacts to mouse events. + +### pointHoverBackgroundColor +**Type:** Color or Color[] +Point background color when hovered. + +### pointHoverBorderColor +**Type:** Color or Color[] +Point border color when hovered. + +### pointHoverBorderWidth +**Type:** Number or Number[] +Border width of point when hovered. + +### pointHoverRadius +**Type:** Number or Number[] +The radius of the point when hovered. + +## Configuration Options + +Unlike other charts, the radar chart has no chart specific options. + +## Scale Options + +The radar chart supports only a single scale. The options for this scale are defined in the `scale` property. + +```javascript +options = { + scale: { + // Hides the scale + display: false + } +}; +``` + +## Default Options + +It is common to want to apply a configuration setting to all created radar charts. The global radar chart settings are stored in `Chart.defaults.radar`. Changing the global options only affects charts created after the change. Existing charts are not changed. + +## Data Structure + +The `data` property of a dataset for a radar chart is specified as a an array of numbers. Each point in the data array corresponds to the label at the same index on the x axis. + +```javascript +data: [20, 10] +``` + +For a radar chart, to provide context of what each point means, we include an array of strings that show around each point in the chart. + +```javascript +data: { + labels: ['Running', 'Swimming', 'Eating', 'Cycling'], + datasets: [{ + data: [20, 10, 4, 2] + }] +} +``` \ No newline at end of file diff --git a/docs/charts/scatter.md b/docs/charts/scatter.md new file mode 100644 index 00000000000..ef4e6f71167 --- /dev/null +++ b/docs/charts/scatter.md @@ -0,0 +1,49 @@ +# Scatter Chart + +Scatter charts are based on basic line charts with the x axis changed to a linear axis. To use a scatter chart, data must be passed as objects containing X and Y properties. The example below creates a scatter chart with 3 points. + +```javascript +var scatterChart = new Chart(ctx, { + type: 'scatter', + data: { + datasets: [{ + label: 'Scatter Dataset', + data: [{ + x: -10, + y: 0 + }, { + x: 0, + y: 10 + }, { + x: 10, + y: 5 + }] + }] + }, + options: { + scales: { + xAxes: [{ + type: 'linear', + position: 'bottom' + }] + } + } +}); +``` + +## Dataset Properties +The scatter chart supports all of the same properties as the [line chart](./line.md#dataset-properties). + +## Data Structure + +Unlike the line chart where data can be supplied in two different formats, the scatter chart only accepts data in a point format. + +```javascript +data: [{ + x: 10, + y: 20 + }, { + x: 15, + y: 10 + }] +``` \ No newline at end of file diff --git a/docs/configuration/README.md b/docs/configuration/README.md new file mode 100644 index 00000000000..7b713905e2e --- /dev/null +++ b/docs/configuration/README.md @@ -0,0 +1,34 @@ +# Configuration + +The configuration is used to change how the chart behaves. There are properties to control styling, fonts, the legend, etc. + +## 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. + +Chart.js merges the options object passed to the chart with the global configuration using chart type defaults and scales defaults appropriately. This way you can be as specific as you would like in your individual chart configuration, while still changing the defaults for all chart types where applicable. The global general options are defined in `Chart.defaults.global`. The defaults for each chart type are discussed in the documentation for that chart type. + +The following example would set the hover mode to 'nearest' for all charts where this was not overridden by the chart type defaults or the options passed to the constructor on creation. + +```javascript +Chart.defaults.global.hover.mode = 'nearest'; + +// Hover mode is set to nearest because it was not overridden here +var chartHoverModeNearest = new Chart(ctx, { + type: 'line', + data: data, +}); + +// This chart would have the hover mode that was passed in +var chartDifferentHoverMode = new Chart(ctx, { + type: 'line', + data: data, + options: { + hover: { + // Overrides the global setting + mode: 'index' + } + } +}) +``` + diff --git a/docs/configuration/animations.md b/docs/configuration/animations.md new file mode 100644 index 00000000000..52f125d7f89 --- /dev/null +++ b/docs/configuration/animations.md @@ -0,0 +1,116 @@ +# Animations + +Chart.js animates charts out of the box. A number of options are provided to configure how the animation looks and how long it takes + +## Animation Configuration + +The following animation options are available. The global options for are defined in `Chart.defaults.global.animation`. + +### duration +**Type:** Number +**Default:** `1000` +The number of milliseconds an animation takes. + +### easing +**Type:** String +**Default:** `'easeOutQuart` +Easing function to use. Available options are: +* `'linear'` +* `'easeInQuad'` +* `'easeOutQuad'` +* `'easeInOutQuad'` +* `'easeInCubic'` +* `'easeOutCubic'` +* `'easeInOutCubic'` +* `'easeInQuart'` +* `'easeOutQuart'` +* `'easeInOutQuart'` +* `'easeInQuint'` +* `'easeOutQuint'` +* `'easeInOutQuint'` +* `'easeInSine'` +* `'easeOutSine'` +* `'easeInOutSine'` +* `'easeInExpo'` +* `'easeOutExpo'` +* `'easeInOutExpo'` +* `'easeInCirc'` +* `'easeOutCirc'` +* `'easeInOutCirc'` +* `'easeInElastic'` +* `'easeOutElastic'` +* `'easeInOutElastic'` +* `'easeInBack'` +* `'easeOutBack'` +* `'easeInOutBack'` +* `'easeInBounce'` +* `'easeOutBounce'` +* `'easeInOutBounce'` + +See [Robert Penner's easing equations](http://robertpenner.com/easing/). + +### onProgress +**Type:** Function +**Default:** `null` +Callback called on each step of an animation. Passed a single argument, an object, containing the chart instance and an object with details of the animation. + +### onComplete +**Type:** Function +**Default:** `null` +Callback called at the end of an animation. Passed the same arguments as `onProgress`. + +## Animation Callbacks + +The `onProgress` and `onComplete` callbacks are useful for synchronizing an external draw to the chart animation. The callback is passed an object that implements the following interface. An example usage of these callbacks can be found on [Github](https://github.com/chartjs/Chart.js/blob/master/samples/animation/progress-bar.html). This sample displays a progress bar showing how far along the animation is. + +```javascript +{ + // Chart object + chartInstance, + + // Contains details of the on-going animation + animationObject, +} +``` + + +The following example fills a progress bar during the chart animation. +```javascript +var chart = new Chart(ctx, { + type: 'line', + data: data, + options: { + animation: { + onProgress: function(animation) { + progress.value = animation.animationObject.currentStep / animation.animationObject.numSteps; + } + } + } +}); +``` + +### Animation Object + +The animation object passed to the callbacks is of type `Chart.Animation`. The object has the following parameters. + +```javascript +{ + // Current Animation frame number + currentStep: Number, + + // Number of animation frames + numSteps: Number, + + // Animation easing to use + easing: String, + + // Function that renders the chart + render: Function, + + // User callback + onAnimationProgress: Function, + + // User callback + onAnimationComplete: Function +} +``` \ No newline at end of file diff --git a/docs/configuration/elements/README.md b/docs/configuration/elements/README.md new file mode 100644 index 00000000000..c93a1e549c9 --- /dev/null +++ b/docs/configuration/elements/README.md @@ -0,0 +1,18 @@ +# Elements + +While chart types provide settings to configure the styling of each dataset, you sometimes want to style all datasets the same way. A common example would be to stroke all of the bars in a bar chart with the same colour but change the fill per dataset. + +Options can be configured for four different types of elements: arc, lines, points, and rectangles. When set, these options apply to all objects of that type unless specifically overridden by the configuration attached to a dataset. + +* [point](./point.md#point-configuratio ) +* [line](./line.md#line-configuration) +* [rectangle / bar](./bar.md#rectangle-configuration) +* [arc](./arc.md#arc-configuration) + +## Global Configuration + +The element options can be specified per chart or globally. The global options for elements are defined in `Chart.defaults.global.elements`. For example, to set the border width of all bar charts globally you would do: + +```javascript +Chart.defaults.global.elements.rectangle.borderWidth = 2; +``` \ No newline at end of file diff --git a/docs/configuration/elements/arc.md b/docs/configuration/elements/arc.md new file mode 100644 index 00000000000..f181b3ef3b0 --- /dev/null +++ b/docs/configuration/elements/arc.md @@ -0,0 +1,18 @@ +# Arc Configuration + +Arcs are used in the polar area, doughnut and pie charts. They can be configured with the following options. The global arc options are stored in `Chart.defaults.global.elements.arc`. + +## backgroundColor +**Type:** Color +**Default:** `'rgba(0, 0, 0, 0.1)'` +Default fill color for arcs. + +## borderColor +**Type:** Color +**Default:** `'#fff'` +Default stroke color for arcs. + +## borderWidth +**Type:** Number +**Default:** `2` +Default stroke width for arcs. \ No newline at end of file diff --git a/docs/configuration/elements/bar.md b/docs/configuration/elements/bar.md new file mode 100644 index 00000000000..1914f6123a1 --- /dev/null +++ b/docs/configuration/elements/bar.md @@ -0,0 +1,29 @@ +# Rectangle Configuration + +Rectangle elements are used to represent the bars in a bar chart. The global rectangle options are stored in `Chart.defaults.global.elements.rectangle`. + +## backgroundColor +**Type:** Color +**Default:** `'rgba(0,0,0,0.1)'` +Default bar fill color. + +## borderWidth +**Type:** Number +**Default:** `0` +Default bar stroke width. + +## borderColor +**Type:** Color +**Default:** `'rgba(0,0,0,0.1)'` +Default bar stroke color. + +##borderSkipped +**Type:** String +**Default:** `'bottom'` +Default skipped (excluded) border for rectangle. + +Options are: +* `'bottom'` +* `'left'` +* `'top'` +* `'right'` \ No newline at end of file diff --git a/docs/configuration/elements/line.md b/docs/configuration/elements/line.md new file mode 100644 index 00000000000..7b371c2cecc --- /dev/null +++ b/docs/configuration/elements/line.md @@ -0,0 +1,58 @@ +# Line Configuration + +Line elements are used to represent the line in a line chart. The global line options are stored in `Chart.defaults.global.elements.line`. + +## tension +**Type:** Number +**Default:** `0.4` +Default bezier curve tension. Set to `0` for no bezier curves. + +## backgroundColor +**Type:** Color +**Default:** `'rgba(0, 0, 0, 0.1)'` +Default line fill color. + +## borderWidth +**Type:** Number +**Default:** `3` +Default line stroke width. + +## borderColor +**Type:** Color +**Default:** `'rgba(0,0,0,0.1)'` +Default line stroke color. + +## borderCapStyle +**Type:** String +**Default:** `'butt'` +Default line cap style. See [MDN](https://developer.mozilla.org/en/docs/Web/API/CanvasRenderingContext2D/lineCap). + +## borderDash +**Type:** Array +**Default:** `[]` +Default line dash. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash). + +## borderDashOffset +**Type:** Number +**Default:** `0` +Default line dash offset. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset). + +## borderJoinStyle +**Type:** String +**Default:** `'miter` +Default line join style. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin). + +## capBezierPoints +**Type:** Boolean +**Default:** `true` +If true, bezier control points are kept inside the chart. If false, no restriction is enforced.. + +## fill +**Type:** Boolean or String +**Default:** `true` +If true, the fill is assumed to be to zero. String values are 'zero', 'top', and 'bottom' to fill to different locations. If `false`, no fill is added. + +## stepped +**Type:** Boolean +**Default:** `false` +If true, the line is shown as a stepped line and 'tension' will be ignored. \ No newline at end of file diff --git a/docs/configuration/elements/point.md b/docs/configuration/elements/point.md new file mode 100644 index 00000000000..ab695b8b281 --- /dev/null +++ b/docs/configuration/elements/point.md @@ -0,0 +1,43 @@ +# Point Configuration + +Point elements are used to represent the points in a line chart or a bubble chart. The global point options are stored in `Chart.defaults.global.elements.point`. + +## radius +**Type:** Number +**Default:** `3` +Default point radius. + +## pointStyle +**Type:** String +**Default:** `'circle'` +Style of the point + +## backgroundColor +**Type:** Color +**Default:** `'rgba(0, 0, 0, 0.1)'` +Default point fill color. + +## borderWidth +**Type:** Number +**Default:** `1` +Default point stroke width. + +## borderColor +**Type:** Color +**Default:** `'rgba(0, 0, 0, 0.1)'` +Default point stroke color. + +## hitRadius +**Type:** Number +**Default:** `1` +Extra radius added to point radius for hit detection. + +## hoverRadius +**Type:** Number +**Default:** `4` +Default point radius when hovered + +## hoverBorderWidth +**Type:** Number +**Default:** `1` +Default stroke width when hovered diff --git a/docs/configuration/layout.md b/docs/configuration/layout.md new file mode 100644 index 00000000000..ec34970a55d --- /dev/null +++ b/docs/configuration/layout.md @@ -0,0 +1,28 @@ +# Layout Configuration + +The layout configuration is passed into the `options.layout` namespace. The global options for the chart layout is defined in `Chart.defaults.global.layout`. + +## padding +**Type:** Number or Object +**Default:** 0 + +The padding to add inside the chart. If this value is a number, it is applied to all sides of the chart (left, top, right, bottom). If this value is an object, the `left` property defines the left padding. Similarly the `right`, `top`, and `bottom` properties can also be specified. + +Lets say you wanted to add 50px of padding to the left side of the chart canvas, you would do: + +```javascript +let chart = new Chart(ctx, { + type: 'line', + data: data, + options: { + layout: { + padding: { + left: 50, + right: 0, + top: 0, + bottom: 0 + } + } + } +}); +``` \ No newline at end of file diff --git a/docs/configuration/legend.md b/docs/configuration/legend.md new file mode 100644 index 00000000000..f99a7bf549d --- /dev/null +++ b/docs/configuration/legend.md @@ -0,0 +1,220 @@ +# Legend Configuration + +The chart legend displays data about the datasets that area appearing on the chart. + +## Configuration options +The legend configuration is passed into the `options.legend` namespace. The global options for the chart legend is defined in `Chart.defaults.global.legend`. + +### display +**Type:** Boolean +**Default:** `true` +Is the legend displayed. + +### position +**Type:** String +**Default:** `'top'` +Position of the legend. Options are: +* `'top'` +* `'left'` +* `'bottom'` +* `'right'` + +### fullWidth +**Type:** Boolean +**Default:** `true` +Marks that this box should take the full width of the canvas (pushing down other boxes). This is unlikely to need to be changed in day-to-day use. + +### onClick +**Type:** Function +**Default:** `function(event, legendItem) {}` +A callback that is called when a 'click' event is registered on top of a label item. + +### onHover +**Type:** Function +**Default:** `function(event, legendItem) {}` +A callback that is called when a 'mousemove' event is registered on top of a label item + +### labels +**Type:** Object +See the [Legend Label Configuration](#legend-label-configuration) section below. + +### reverse +**Type:** Boolean +**Default:** `false` +Legend will show datasets in reverse order. + +## Legend Label Configuration + +The legend label configuration is nested below the legend configuration using the `labels` key. + +### boxWidth +**Type:** Number +**Boolean:** `40` +Width of coloured box. + +### fontSize +**Type:** Number +**Boolean:** `12` +Font size of text in legend. + +### fontStyle +**Type:** String +**Boolean:** `'normal'` +Font style of text in the legend. + +### fontColor +**Type:** Color +**Boolean:** `'#666'` +Font color of text in legend. + +### fontFamily +**Type:** String +**Boolean:** `"'Helvetica Neue', 'Helvetica', 'Arial', sans-serif"` +Font family of legend text. + +### padding +**Type:** Number +**Boolean:** `10` +Padding between rows of colored boxes. + +### generateLabels +**Type:** Function +**Boolean:** `function(chart) { }` +Generates legend items for each thing in the legend. Default implementation returns the text + styling for the color box. See [Legend Item](#chart-configuration-legend-item-interface) for details. + +### filter +**Type:** Function +**Boolean:** `null` +Filters legend items out of the legend. Receives 2 parameters, a [Legend Item](#chart-configuration-legend-item-interface) and the chart data. + +### usePointStyle +**Type:** Boolean +**Boolean:** `false` +Label style will match corresponding point style (size is based on fontSize, boxWidth is not used in this case). + +## Legend Item Interface + +Items passed to the legend `onClick` function are the ones returned from `labels.generateLabels`. These items must implement the following interface. + +```javascript +{ + // Label that will be displayed + text: String, + + // Fill style of the legend box + fillStyle: Color, + + // If true, this item represents a hidden dataset. Label will be rendered with a strike-through effect + hidden: Boolean, + + // For box border. See https://developer.mozilla.org/en/docs/Web/API/CanvasRenderingContext2D/lineCap + lineCap: String, + + // For box border. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash + lineDash: Array[Number], + + // For box border. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset + lineDashOffset: Number, + + // For box border. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin + lineJoin: String, + + // Width of box border + lineWidth: Number, + + // Stroke style of the legend box + strokeStyle: Color + + // Point style of the legend box (only used if usePointStyle is true) + pointStyle: String +} +``` + +## Example + +The following example will create a chart with the legend enabled and turn all of the text red in color. + +```javascript +var chart = new Chart(ctx, { + type: 'bar', + data: data, + options: { + legend: { + display: true, + labels: { + fontColor: 'rgb(255, 99, 132)' + } + } +} +}); +``` + +## Custom On Click Actions + +It can be common to want to trigger different behaviour when clicking an item in the legend. This can be easily achieved using a callback in the config object. + +The default legend click handler is: +```javascript +function(e, legendItem) { + var index = legendItem.datasetIndex; + var ci = this.chart; + var meta = ci.getDatasetMeta(index); + + // See controller.isDatasetVisible comment + meta.hidden = meta.hidden === null? !ci.data.datasets[index].hidden : null; + + // We hid a dataset ... rerender the chart + ci.update(); +} +``` + +Lets say we wanted instead to link the display of the first two datasets. We could change the click handler accordingly. + +```javascript +var defaultLegendClickHandler = Chart.defaults.global.legend.onClick; +var newLegendClickHandler = function (e, legendItem) { + var index = legendItem.datasetIndex; + + if (index > 1) { + // Do the original logic + defaultLegendClickHandler(e, legendItem); + } else { + let ci = this.chart; + [ci.getDatasetMeta(0), + ci.getDatasetMeta(1)].forEach(function(meta) { + meta.hidden = meta.hidden === null? !ci.data.datasets[index].hidden : null; + }); + ci.update(); + } +}; + +var chart = new Chart(ctx, { + type: 'line', + data: data, + options: { + legend: { + + } + } +}); +``` + +Now when you click the legend in this chart, the visibility of the first two datasets will be linked together. + +## HTML Legends + +Sometimes you need a very complex legend. In these cases, it makes sense to generate an HTML legend. Charts provide a `generateLegend()` method on their prototype that returns an HTML string for the legend. + +To configure how this legend is generated, you can change the `legendCallback` config property. + +```javascript +var chart = new Chart(ctx, { + type: 'line', + data: data, + options: { + legendCallback: function(chart) { + // Return the HTML string here. + } + } +}); +``` \ No newline at end of file diff --git a/docs/configuration/title.md b/docs/configuration/title.md new file mode 100644 index 00000000000..13198be0e7c --- /dev/null +++ b/docs/configuration/title.md @@ -0,0 +1,67 @@ +# Title + +The chart title defines text to draw at the top of the chart. + +## Title Configuration +The title configuration is passed into the `options.title` namespace. The global options for the chart title is defined in `Chart.defaults.global.title`. + +### display +**Type:** Boolean +**Default:** `false` +If true, the title block is displayed. + +### position +**Type:** String +**Default:** `'top'` +Position of the title. Possible values are: +* `'top'` +* `'left'` +* `'bottom'` +* `'right'` + +### fontSize +**Type:** Number +**Default:** `12` +Font size of the title text. + +### fontFamily +**Type:** String +**Default:** `"'Helvetica Neue', 'Helvetica', 'Arial', sans-serif"` +Font family for the title text. + +### fontColor +**Type:** Color +**Default:** `'#666` +Font color inherited from global configuration. + +### fontStyle +**Type:** String +**Default:** `'bold` +Font styling of the title text. + +### padding +**Type:** Number +**Default:** `10` +Number of pixels to add above and below the title text. + +### text +**Type:** String +**Default:** `''` +The title text to display. + +## Example Usage + +The example below would enable a title of 'Custom Chart Title' on the chart that is created. + +```javascript +var chart = new Chart(ctx, { + type: 'line', + data: data, + options: { + title: { + display: true, + text: 'Custom Chart Title' + } + } +}) +``` diff --git a/docs/configuration/tooltip.md b/docs/configuration/tooltip.md new file mode 100644 index 00000000000..7bd93c8dae7 --- /dev/null +++ b/docs/configuration/tooltip.md @@ -0,0 +1,304 @@ +# Tooltips + +## Tooltip Configuration + +The tooltip configuration is passed into the `options.tooltips` namespace. The global options for the chart tooltips is defined in `Chart.defaults.global.tooltips`. + +### enabled +**Type:** Boolean +**Default:** `true` +Are tooltips enabled. + +### custom +**Type:** Function +**Default:** `null` +See [custom tooltip](#custom-tooltips) section. + +### mode +**Type:** String +**Default:** `'nearest'` +Sets which elements appear in the tooltip. See [Interaction Modes](../general/interactions/modes.md#interaction-modes) for details. + +### intersect +**Type:** Boolean +**Default:** `true` +if true, the tooltip mode applies only when the mouse position intersects with an element. If false, the mode will be applied at all times. + +### position +**Type:** String +**Default:** `'average'` +The mode for positioning the tooltip. Possible modes are: +* 'average' +* 'nearest' + +'average' mode will place the tooltip at the average position of the items displayed in the tooltip. 'nearest' will place the tooltip at the position of the element closest to the event position. + +New modes can be defined by adding functions to the Chart.Tooltip.positioners map. + +### itemSort +**Type:** Function +**Default:** `undefined` +Allows sorting of [tooltip items](#chart-configuration-tooltip-item-interface). Must implement at minimum a function that can be passed to [Array.prototype.sort](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort). This function can also accept a third parameter that is the data object passed to the chart. + +### filter +**Type:** Function +**Default:** `undefined` +Allows filtering of [tooltip items](#chart-configuration-tooltip-item-interface). Must implement at minimum a function that can be passed to [Array.prototype.filter](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Array/filter). This function can also accept a second parameter that is the data object passed to the chart. + +### backgroundColor +**Type:** Color +**Default:** `'rgba(0,0,0,0.8)'` +Background color of the tooltip. + +### titleFontFamily +**Type:** String +**Default:** `"'Helvetica Neue', 'Helvetica', 'Arial', sans-serif"` +Font family for tooltip title inherited from global font family. + +### titleFontSize +**Type:** Number +**Default:** `12` +Font size for tooltip title inherited from global font size + +### titleFontStyle +**Type:** String +**Default:** `'bold'` +Font style for the tooltip title. + +### titleFontColor +**Type:** Color +**Default:** `'#fff'` +Font color for tooltip title + +### titleSpacing +**Type:** Number +**Default:** `2` +Spacing to add to top and bottom of each title line. + +### titleMarginBottom +**Type:** Number +**Default:** `6` +Margin to add on bottom of title section. + +### bodyFontFamily +**Type:** String +**Default:** `"'Helvetica Neue', 'Helvetica', 'Arial', sans-serif"` +Font family for tooltip items inherited from global font family + +### bodyFontSize +**Type:** Number +**Default:** `12` +Font size for tooltip items inherited from global font size. + +### bodyFontStyle +**Type:** String +**Default:** `'normal'` +Font style for the body lines of the tooltip. + +### bodyFontColor +**Type:** Color +**Default:** `'#fff'` +Font color for tooltip items. + +### bodySpacing +**Type:** Number +**Default:** `2` +Spacing to add to top and bottom of each tooltip item. + +### footerFontFamily +**Type:** String +**Default:** `"'Helvetica Neue', 'Helvetica', 'Arial', sans-serif"` +Font family for tooltip footer inherited from global font family. + +### footerFontSize +**Type:** Number +**Default:** `12` +Font size for tooltip footer inherited from global font size. + +### footerFontStyle +**Type:** String +**Default:** `'bold'` +Font style for tooltip footer. + +### footerFontColor +**Type:** Color +**Default:** `'#fff'` +Font color for tooltip footer. + +### footerSpacing +**Type:** Number +**Default:** `2` +Spacing to add to top and bottom of each footer line. + +### footerMarginTop +**Type:** Number +**Default:** `6` +Margin to add before drawing the footer. + +### xPadding +**Type:** Number +**Default:** `6` +Padding to add on left and right of tooltip. + +### yPadding +**Type:** Number +**Default:** `6` +Padding to add on top and bottom of tooltip. + +### caretSize +**Type:** Number +**Default:** `5` +Size, in px, of the tooltip arrow. + +### cornerRadius +**Type:** Number +**Default:** `6` +Radius of tooltip corner curves. + +### multiKeyBackground +**Type:** Color +**Default:** `'#fff'` +Color to draw behind the colored boxes when multiple items are in the tooltip + +### displayColors +**Type:** Boolean +**Default:** `true` +if true, color boxes are shown in the tooltip + +## Tooltip Callbacks + +The tooltip label configuration is nested below the tooltip configuration using the `callbacks` key. The tooltip has the following callbacks for providing text. For all functions, 'this' will be the tooltip object created from the Chart.Tooltip constructor. + +All functions are called with the same arguments: a [tooltip item](#chart-configuration-tooltip-item-interface) and the data object passed to the chart. All functions must return either a string or an array of strings. Arrays of strings are treated as multiple lines of text. + +### beforeTitle +**Arguments:** `Array[tooltipItem], data` +Returns the text to render before the title. + +### title +**Arguments:** `Array[tooltipItem], data` +Returns text to render as the title of the tooltip. + +### afterTitle +**Arguments:** `Array[tooltipItem], data` +Returns text to render after the title. + +### beforeBody +**Arguments:** `Array[tooltipItem], data` +Returns text to render before the body section. + +### beforeLabel +**Arguments:** `tooltipItem, data` +Returns text to render before an individual label. This will be called for each item in the tooltip. + +### label +**Arguments:** `tooltipItem, data` +Returns text to render for an individual item in the tooltip. + +### labelColor +**Arguments:** `tooltipItem, chartInstance` +Returns the colors to render for the tooltip item. Return as an object containing two parameters: `borderColor` and `backgroundColor`. + +For example, to return a red box for each item in the tooltip you could do: +```javascript +var chart = new Chart(ctx, { + type: 'line', + data: data, + options: { + tooltips: { + callbacks: { + labelColor: function(tooltipItem, chartInstance) { + return { + borderColor: 'rgb(255, 0, 0)', + backgroundColor: 'rgb(255, 0, 0)' + } + } + } + } + } +}); +``` + +### afterLabel +**Arguments:** `tooltipItem, data` +Returns text to render after an individual label. + +### afterBody +**Arguments:** `Array[tooltipItem], data` +Returns text to render after the body section + +### beforeFooter +**Arguments:** `Array[tooltipItem], data` +Returns text to render before the footer section. + +### footer +**Arguments:** `Array[tooltipItem], data` +Returns text to render as the footer of the tooltip. + +### afterFooter +**Arguments:** `Array[tooltipItem], data` +Text to render after the footer section + +### Tooltip Item Interface + +The tooltip items passed to the tooltip callbacks implement the following interface. + +```javascript +{ + // X Value of the tooltip as a string + xLabel: String, + + // Y value of the tooltip as a string + yLabel: String, + + // Index of the dataset the item comes from + datasetIndex: Number, + + // Index of this data item in the dataset + index: Number, + + // X position of matching point + x: Number, + + // Y position of matching point + y: Number, +} +``` + +## External Tooltips + +You can enable custom tooltips in the global or chart configuration like so: + +```javascript +var myPieChart = new Chart(ctx, { + type: 'pie', + data: data, + options: { + tooltips: { + custom: function(tooltip) { + // tooltip will be false if tooltip is not visible or should be hidden + if (!tooltip) { + return; + } + + // Otherwise, tooltip will be an object with all tooltip properties like: + + // tooltip.caretSize + // tooltip.caretPadding + // tooltip.chart + // tooltip.cornerRadius + // tooltip.fillColor + // tooltip.font... + // tooltip.text + // tooltip.x + // tooltip.y + // tooltip.caretX + // tooltip.caretY + // etc... + } + } + } +}); +``` + +See `samples/tooltips/line-customTooltips.html` for examples on how to get started. \ No newline at end of file diff --git a/docs/developers/README.md b/docs/developers/README.md new file mode 100644 index 00000000000..211970a268b --- /dev/null +++ b/docs/developers/README.md @@ -0,0 +1,22 @@ +# Developers +Developer features allow extending and enhancing Chart.js in many different ways. + +# Browser support + +Chart.js offers support for all browsers where canvas is supported. + +Browser support for the canvas element is available in all modern & major mobile browsers (http://caniuse.com/#feat=canvas). + +Thanks to BrowserStack for allowing our team to test on thousands of browsers. + +# Previous versions + +Version 2 has a completely different API than earlier versions. + +Most earlier version options have current equivalents or are the same. + +Please use the documentation that is available on [chartjs.org](http://www.chartjs.org/docs/) for the current version of Chart.js. + +Please note - documentation for previous versions are available on the GitHub repo. + +- [1.x Documentation](https://github.com/chartjs/Chart.js/tree/v1.1.1/docs) \ No newline at end of file diff --git a/docs/developers/api.md b/docs/developers/api.md new file mode 100644 index 00000000000..bf002800a57 --- /dev/null +++ b/docs/developers/api.md @@ -0,0 +1,143 @@ +# Chart Prototype Methods + +For each chart, there are a set of global prototype methods on the shared `ChartType` which you may find useful. These are available on all charts created with Chart.js, but for the examples, let's use a line chart we've made. + +```javascript +// For example: +var myLineChart = new Chart(ctx, config); +``` + +## .destroy() + +Use this to destroy any chart instances that are created. This will clean up any references stored to the chart object within Chart.js, along with any associated event listeners attached by Chart.js. +This must be called before the canvas is reused for a new chart. + +```javascript +// Destroys a specific chart instance +myLineChart.destroy(); +``` + +## .update(duration, lazy) + +Triggers an update of the chart. This can be safely called after updating the data object. This will update all scales, legends, and then re-render the chart. + +```javascript +// duration is the time for the animation of the redraw in milliseconds +// lazy is a boolean. if true, the animation can be interrupted by other animations +myLineChart.data.datasets[0].data[2] = 50; // Would update the first dataset's value of 'March' to be 50 +myLineChart.update(); // Calling update now animates the position of March from 90 to 50. +``` + +> **Note:** replacing the data reference (e.g. `myLineChart.data = {datasets: [...]}` only works starting **version 2.6**. Prior that, replacing the entire data object could be achieved with the following workaround: `myLineChart.config.data = {datasets: [...]}`. + +## .reset() + +Reset the chart to it's state before the initial animation. A new animation can then be triggered using `update`. + +```javascript +myLineChart.reset(); +``` + +## .render(duration, lazy) + +Triggers a redraw of all chart elements. Note, this does not update elements for new data. Use `.update()` in that case. + +```javascript +// duration is the time for the animation of the redraw in milliseconds +// lazy is a boolean. if true, the animation can be interrupted by other animations +myLineChart.render(duration, lazy); +``` + +## .stop() + +Use this to stop any current animation loop. This will pause the chart during any current animation frame. Call `.render()` to re-animate. + +```javascript +// Stops the charts animation loop at its current frame +myLineChart.stop(); +// => returns 'this' for chainability +``` + +## .resize() + +Use this to manually resize the canvas element. This is run each time the canvas container is resized, but you can call this method manually if you change the size of the canvas nodes container element. + +```javascript +// Resizes & redraws to fill its container element +myLineChart.resize(); +// => returns 'this' for chainability +``` + +## .clear() + +Will clear the chart canvas. Used extensively internally between animation frames, but you might find it useful. + +```javascript +// Will clear the canvas that myLineChart is drawn on +myLineChart.clear(); +// => returns 'this' for chainability +``` + +## .toBase64Image() + +This returns a base 64 encoded string of the chart in it's current state. + +```javascript +myLineChart.toBase64Image(); +// => returns png data url of the image on the canvas +``` + +## .generateLegend() + +Returns an HTML string of a legend for that chart. The legend is generated from the `legendCallback` in the options. + +```javascript +myLineChart.generateLegend(); +// => returns HTML string of a legend for this chart +``` + +## .getElementAtEvent(e) + +Calling `getElementAtEvent(event)` on your Chart instance passing an argument of an event, or jQuery event, will return the single element at the event position. If there are multiple items within range, only the first is returned + +```javascript +myLineChart.getElementAtEvent(e); +// => returns the first element at the event point. +``` + +## .getElementsAtEvent(e) + +Looks for the element under the event point, then returns all elements at the same data index. This is used internally for 'label' mode highlighting. + +Calling `getElementsAtEvent(event)` on your Chart instance passing an argument of an event, or jQuery event, will return the point elements that are at that the same position of that event. + +```javascript +canvas.onclick = function(evt){ + var activePoints = myLineChart.getElementsAtEvent(evt); + // => activePoints is an array of points on the canvas that are at the same position as the click event. +}; +``` + +This functionality may be useful for implementing DOM based tooltips, or triggering custom behaviour in your application. + +## .getDatasetAtEvent(e) + +Looks for the element under the event point, then returns all elements from that dataset. This is used internally for 'dataset' mode highlighting + +```javascript +myLineChart.getDatasetAtEvent(e); +// => returns an array of elements +``` + +## .getDatasetMeta(index) + +Looks for the dataset that matches the current index and returns that metadata. This returned data has all of the metadata that is used to construct the chart. + +The `data` property of the metadata will contain information about each point, rectangle, etc. depending on the chart type. + +Extensive examples of usage are available in the [Chart.js tests](https://github.com/chartjs/Chart.js/tree/master/test). + +```javascript +var meta = myChart.getDatasetMeta(0); +var x = meta.data[0]._model.x +``` diff --git a/docs/developers/axes.md b/docs/developers/axes.md new file mode 100644 index 00000000000..8d120195ae9 --- /dev/null +++ b/docs/developers/axes.md @@ -0,0 +1,131 @@ +# New Axes + +Axes in Chart.js can be individually extended. Axes should always derive from Chart.Scale but this is not a mandatory requirement. + +```javascript +let MyScale = Chart.Scale.extend({ + /* extensions ... */ +}); + +// MyScale is now derived from Chart.Scale +``` + +Once you have created your scale class, you need to register it with the global chart object so that it can be used. A default config for the scale may be provided when registering the constructor. The first parameter to the register function is a string key that is used later to identify which scale type to use for a chart. + +```javascript +Chart.scaleService.registerScaleType('myScale', MyScale, defaultConfigObject); +``` + +To use the new scale, simply pass in the string key to the config when creating a chart. + +```javascript +var lineChart = new Chart(ctx, { + data: data, + type: 'line', + options: { + scales: { + yAxes: [{ + type: 'myScale' // this is the same key that was passed to the registerScaleType function + }] + } + } +}) +``` + +## Scale Properties + +Scale instances are given the following properties during the fitting process. + +```javascript +{ + left: Number, // left edge of the scale bounding box + right: Number, // right edge of the bounding box' + top: Number, + bottom: Number, + width: Number, // the same as right - left + height: Number, // the same as bottom - top + + // Margin on each side. Like css, this is outside the bounding box. + margins: { + left: Number, + right: Number, + top: Number, + bottom: Number, + }, + + // Amount of padding on the inside of the bounding box (like CSS) + paddingLeft: Number, + paddingRight: Number, + paddingTop: Number, + paddingBottom: Number, +} +``` + +## Scale Interface +To work with Chart.js, custom scale types must implement the following interface. + +```javascript +{ + // Determines the data limits. Should set this.min and this.max to be the data max/min + determineDataLimits: function() {}, + + // Generate tick marks. this.chart is the chart instance. The data object can be accessed as this.chart.data + // buildTicks() should create a ticks array on the axis instance, if you intend to use any of the implementations from the base class + buildTicks: function() {}, + + // Get the value to show for the data at the given index of the the given dataset, ie this.chart.data.datasets[datasetIndex].data[index] + getLabelForIndex: function(index, datasetIndex) {}, + + // Get the pixel (x coordinate for horizontal axis, y coordinate for vertical axis) for a given value + // @param index: index into the ticks array + // @param includeOffset: if true, get the pixel halway between the given tick and the next + getPixelForTick: function(index, includeOffset) {}, + + // Get the pixel (x coordinate for horizontal axis, y coordinate for vertical axis) for a given value + // @param value : the value to get the pixel for + // @param index : index into the data array of the value + // @param datasetIndex : index of the dataset the value comes from + // @param includeOffset : if true, get the pixel halway between the given tick and the next + getPixelForValue: function(value, index, datasetIndex, includeOffset) {} + + // Get the value for a given pixel (x coordinate for horizontal axis, y coordinate for vertical axis) + // @param pixel : pixel value + getValueForPixel: function(pixel) {} +} +``` + +Optionally, the following methods may also be overwritten, but an implementation is already provided by the `Chart.Scale` base class. + +```javascript + // Transform the ticks array of the scale instance into strings. The default implementation simply calls this.options.ticks.callback(numericalTick, index, ticks); + convertTicksToLabels: function() {}, + + // Determine how much the labels will rotate by. The default implementation will only rotate labels if the scale is horizontal. + calculateTickRotation: function() {}, + + // Fits the scale into the canvas. + // this.maxWidth and this.maxHeight will tell you the maximum dimensions the scale instance can be. Scales should endeavour to be as efficient as possible with canvas space. + // this.margins is the amount of space you have on either side of your scale that you may expand in to. This is used already for calculating the best label rotation + // You must set this.minSize to be the size of your scale. It must be an object containing 2 properties: width and height. + // You must set this.width to be the width and this.height to be the height of the scale + fit: function() {}, + + // Draws the scale onto the canvas. this.(left|right|top|bottom) will have been populated to tell you the area on the canvas to draw in + // @param chartArea : an object containing four properties: left, right, top, bottom. This is the rectangle that lines, bars, etc will be drawn in. It may be used, for example, to draw grid lines. + draw: function(chartArea) {}, +``` + +The Core.Scale base class also has some utility functions that you may find useful. +```javascript +{ + // Returns true if the scale instance is horizontal + isHorizontal: function() {}, + + // Get the correct value from the value from this.chart.data.datasets[x].data[] + // If dataValue is an object, returns .x or .y depending on the return of isHorizontal() + // If the value is undefined, returns NaN + // Otherwise returns the value. + // Note that in all cases, the returned value is not guaranteed to be a Number + getRightValue: function(dataValue) {}, +} +``` \ No newline at end of file diff --git a/docs/developers/charts.md b/docs/developers/charts.md new file mode 100644 index 00000000000..b03ecd76cd9 --- /dev/null +++ b/docs/developers/charts.md @@ -0,0 +1,76 @@ +# New Charts + +Chart.js 2.0 introduces the concept of controllers for each dataset. Like scales, new controllers can be written as needed. + +```javascript +Chart.controllers.MyType = Chart.DatasetController.extend({ + +}); + + +// Now we can create a new instance of our chart, using the Chart.js API +new Chart(ctx, { + // this is the string the constructor was registered at, ie Chart.controllers.MyType + type: 'MyType', + data: data, + options: options +}); +``` + +## Dataset Controller Interface + +Dataset controllers must implement the following interface. + +```javascript +{ + // Create elements for each piece of data in the dataset. Store elements in an array on the dataset as dataset.metaData + addElements: function() {}, + + // Create a single element for the data at the given index and reset its state + addElementAndReset: function(index) {}, + + // Draw the representation of the dataset + // @param ease : if specified, this number represents how far to transition elements. See the implementation of draw() in any of the provided controllers to see how this should be used + draw: function(ease) {}, + + // Remove hover styling from the given element + removeHoverStyle: function(element) {}, + + // Add hover styling to the given element + setHoverStyle: function(element) {}, + + // Update the elements in response to new data + // @param reset : if true, put the elements into a reset state so they can animate to their final values + update: function(reset) {}, +} +``` + +The following methods may optionally be overridden by derived dataset controllers +```javascript +{ + // Initializes the controller + initialize: function(chart, datasetIndex) {}, + + // Ensures that the dataset represented by this controller is linked to a scale. Overridden to helpers.noop in the polar area and doughnut controllers as these + // chart types using a single scale + linkScales: function() {}, + + // Called by the main chart controller when an update is triggered. The default implementation handles the number of data points changing and creating elements appropriately. + buildOrUpdateElements: function() {} +} +``` + +## Extending Existing Chart Types + +Extending or replacing an existing controller type is easy. Simply replace the constructor for one of the built in types with your own. + +The built in controller types are: +* `Chart.controllers.line` +* `Chart.controllers.bar` +* `Chart.controllers.radar` +* `Chart.controllers.doughnut` +* `Chart.controllers.polarArea` +* `Chart.controllers.bubble` + +### Bar Controller +The bar controller has a special property that you should be aware of. To correctly calculate the width of a bar, the controller must determine the number of datasets that map to bars. To do this, the bar controller attaches a property `bar` to the dataset during initialization. If you are creating a replacement or updated bar controller, you should do the same. This will ensure that charts with regular bars and your new derived bars will work seamlessly. \ No newline at end of file diff --git a/docs/developers/contributing.md b/docs/developers/contributing.md new file mode 100644 index 00000000000..67c391db5a5 --- /dev/null +++ b/docs/developers/contributing.md @@ -0,0 +1,34 @@ +# Contributing + +New contributions to the library are welcome, but we ask that you please follow these guidelines: + +- Use tabs for indentation, not spaces. +- Only change the individual files in `/src`. +- Check that your code will pass `eslint` code standards, `gulp lint` will run this for you. +- Check that your code will pass tests, `gulp test` will run tests for you. +- Keep pull requests concise, and document new functionality in the relevant `.md` file. +- Consider whether your changes are useful for all users, or if creating a Chart.js plugin would be more appropriate. + +# Building Chart.js + +Chart.js uses gulp to build the library into a single JavaScript file. + +Firstly, we need to ensure development dependencies are installed. With node and npm installed, after cloning the Chart.js repo to a local directory, and navigating to that directory in the command line, we can run the following: + +```bash +npm install +npm install -g gulp +``` + +This will install the local development dependencies for Chart.js, along with a CLI for the JavaScript task runner gulp. + +Now, we can run the `gulp build` task. + +```bash +gulp build +``` + +# Bugs & issues + +Please report these on the GitHub page - at github.com/chartjs/Chart.js. If you could include a link to a simple jsbin or similar to demonstrate the issue, that'd be really helpful. + diff --git a/docs/developers/plugins/README.md b/docs/developers/plugins/README.md new file mode 100644 index 00000000000..8a9e1d94648 --- /dev/null +++ b/docs/developers/plugins/README.md @@ -0,0 +1,9 @@ +# Plugins + +Starting with v2.1.0, you can create plugins for chart.js. To register your plugin, simply call `Chart.plugins.register` and pass your plugin in. + + +```javascript +var myplugin = { ... }; +Chart.plugins.register(myplugin); +``` \ No newline at end of file diff --git a/docs/developers/plugins/api.md b/docs/developers/plugins/api.md new file mode 100644 index 00000000000..78936ad6b6f --- /dev/null +++ b/docs/developers/plugins/api.md @@ -0,0 +1,186 @@ +# Plugin API + +Plugins must implement the `IPlugin` interface. +```javascript +{ + /** + * Plugin extension hooks. + * @interface IPlugin + * @since 2.1.0 + */ + + /** + * @method IPlugin#beforeInit + * @desc Called before initializing `chart`. + * @param {Chart} chart - The chart instance. + * @param {Object} options - The plugin options. + */ + beforeInit: function(chart, options) {}, + + /** + * @method IPlugin#afterInit + * @desc Called after `chart` has been initialized and before the first update. + * @param {Chart} chart - The chart instance. + * @param {Object} options - The plugin options. + */ + afterInit: function(chart, options) {}, + + /** + * @method IPlugin#beforeUpdate + * @desc Called before updating `chart`. If any plugin returns `false`, the update + * is cancelled (and thus subsequent render(s)) until another `update` is triggered. + * @param {Chart} chart - The chart instance. + * @param {Object} options - The plugin options. + * @returns {Boolean} `false` to cancel the chart update. + */ + beforeUpdate(chart, options) {}, + + /** + * @method IPlugin#afterUpdate + * @desc Called after `chart` has been updated and before rendering. Note that this + * hook will not be called if the chart update has been previously cancelled. + * @param {Chart} chart - The chart instance. + * @param {Object} options - The plugin options. + */ + afterUpdate: funciotn(chart, options) {}, + + /** + * @method IPlugin#beforeDatasetsUpdate + * @desc Called before updating the `chart` datasets. If any plugin returns `false`, + * the datasets update is cancelled until another `update` is triggered. + * @param {Chart} chart - The chart instance. + * @param {Object} options - The plugin options. + * @returns {Boolean} false to cancel the datasets update. + * @since version 2.1.5 + */ + beforeDatasetsUpdate: function(chart, options) {}, + + /** + * @method IPlugin#afterDatasetsUpdate + * @desc Called after the `chart` datasets have been updated. Note that this hook + * will not be called if the datasets update has been previously cancelled. + * @param {Chart} chart - The chart instance. + * @param {Object} options - The plugin options. + * @since version 2.1.5 + */ + afterDatasetsUpdate: function(chart, options) {}, + + /** + * @method IPlugin#beforeLayout + * @desc Called before laying out `chart`. If any plugin returns `false`, + * the layout update is cancelled until another `update` is triggered. + * @param {Chart} chart - The chart instance. + * @param {Object} options - The plugin options. + * @returns {Boolean} `false` to cancel the chart layout. + */ + beforeLayout: function(chart, options) {}, + + /** + * @method IPlugin#afterLayout + * @desc Called after the `chart` has been layed out. Note that this hook will not + * be called if the layout update has been previously cancelled. + * @param {Chart} chart - The chart instance. + * @param {Object} options - The plugin options. + */ + afterLayout: function(chart, options) {}, + + /** + * @method IPlugin#beforeRender + * @desc Called before rendering `chart`. If any plugin returns `false`, + * the rendering is cancelled until another `render` is triggered. + * @param {Chart} chart - The chart instance. + * @param {Object} options - The plugin options. + * @returns {Boolean} `false` to cancel the chart rendering. + */ + beforeRender: function(chart, options) {}, + + /** + * @method IPlugin#afterRender + * @desc Called after the `chart` has been fully rendered (and animation completed). Note + * that this hook will not be called if the rendering has been previously cancelled. + * @param {Chart} chart - The chart instance. + * @param {Object} options - The plugin options. + */ + afterRender: function(chart, options) {}, + + /** + * @method IPlugin#beforeDraw + * @desc Called before drawing `chart` at every animation frame specified by the given + * easing value. If any plugin returns `false`, the frame drawing is cancelled until + * another `render` is triggered. + * @param {Chart} chart - The chart instance. + * @param {Number} easingValue - The current animation value, between 0.0 and 1.0. + * @param {Object} options - The plugin options. + * @returns {Boolean} `false` to cancel the chart drawing. + */ + beforeDraw: function(chart, easingValue, options) {}, + + /** + * @method IPlugin#afterDraw + * @desc Called after the `chart` has been drawn for the specific easing value. Note + * that this hook will not be called if the drawing has been previously cancelled. + * @param {Chart} chart - The chart instance. + * @param {Number} easingValue - The current animation value, between 0.0 and 1.0. + * @param {Object} options - The plugin options. + */ + afterDraw: function(chart, easingValue, options) {}, + + /** + * @method IPlugin#beforeDatasetsDraw + * @desc Called before drawing the `chart` datasets. If any plugin returns `false`, + * the datasets drawing is cancelled until another `render` is triggered. + * @param {Chart} chart - The chart instance. + * @param {Number} easingValue - The current animation value, between 0.0 and 1.0. + * @param {Object} options - The plugin options. + * @returns {Boolean} `false` to cancel the chart datasets drawing. + */ + beforeDatasetsDraw: function(chart, easingValue, options) {}, + + /** + * @method IPlugin#afterDatasetsDraw + * @desc Called after the `chart` datasets have been drawn. Note that this hook + * will not be called if the datasets drawing has been previously cancelled. + * @param {Chart} chart - The chart instance. + * @param {Number} easingValue - The current animation value, between 0.0 and 1.0. + * @param {Object} options - The plugin options. + */ + afterDatasetsDraw: function(chart, easingValue, options) {}, + + /** + * @method IPlugin#beforeEvent + * @desc Called before processing the specified `event`. If any plugin returns `false`, + * the event will be discarded. + * @param {Chart} chart - The chart instance. + * @param {IEvent} event - The event object. + * @param {Object} options - The plugin options. + */ + beforeEvent: function(chart, event, options) {}, + + /** + * @method IPlugin#afterEvent + * @desc Called after the `event` has been consumed. Note that this hook + * will not be called if the `event` has been previously discarded. + * @param {Chart} chart - The chart instance. + * @param {IEvent} event - The event object. + * @param {Object} options - The plugin options. + */ + afterEvent: function(chart, event, options) {}, + + /** + * @method IPlugin#resize + * @desc Called after the chart as been resized. + * @param {Chart} chart - The chart instance. + * @param {Number} size - The new canvas display size (eq. canvas.style width & height). + * @param {Object} options - The plugin options. + */ + resize: function(chart, size, options) {}, + + /** + * @method IPlugin#destroy + * @desc Called after the chart as been destroyed. + * @param {Chart} chart - The chart instance. + * @param {Object} options - The plugin options. + */ + destroy: function(chart, options) {}, +} +``` \ No newline at end of file diff --git a/docs/developers/plugins/registry.md b/docs/developers/plugins/registry.md new file mode 100644 index 00000000000..dc02d9721eb --- /dev/null +++ b/docs/developers/plugins/registry.md @@ -0,0 +1,11 @@ +# Popular Plugins + +There are many plugins that add additional functionality to Chart.js. Some particularly notable ones are listed here. In addition, many plugins can be found on the [Chart.js GitHub organization](https://github.com/chartjs). + + - chartjs-plugin-annotation.js - Draw lines and boxes on chart area + - chartjs-plugin-deferred.js - Defer initial chart update until chart scrolls into viewport + - chartjs-plugin-draggable.js - Makes select chart elements draggable with the mouse + - chartjs-plugin-zoom.js - Enable zooming and panning on charts + - Chart.BarFunnel.js - Adds a bar funnel chart type + - Chart.LinearGauge.js - Adds a linear gauge chart type + - Chart.Smith.js - Adds a smith chart type \ No newline at end of file diff --git a/docs/general/README.md b/docs/general/README.md new file mode 100644 index 00000000000..2229f41b2b3 --- /dev/null +++ b/docs/general/README.md @@ -0,0 +1 @@ +# General \ No newline at end of file diff --git a/docs/general/colors.md b/docs/general/colors.md new file mode 100644 index 00000000000..56162b5575a --- /dev/null +++ b/docs/general/colors.md @@ -0,0 +1,49 @@ +# Colors + +When supplying colors to Chart options, you can use a number of formats. You can specify the color as a string in hexadecimal, RGB, or HSL notations. If a color is needed, but not specified, Chart.js will use the global default color. This color is stored at `Chart.defaults.global.defaultColor`. It is initially set to `'rgba(0, 0, 0, 0.1)'` + +You can also pass a [CanvasGradient](https://developer.mozilla.org/en-US/docs/Web/API/CanvasGradient) object. You will need to create this before passing to the chart, but using it you can achieve some interesting effects. + +## Patterns and Gradients + +An alternative option is to pass a [CanvasPattern](https://developer.mozilla.org/en-US/docs/Web/API/CanvasPattern) or [CanvasGradient[(https://developer.mozilla.org/en/docs/Web/API/CanvasGradient) object instead of a string colour. + +For example, if you wanted to fill a dataset with a pattern from an image you could do the following. + +```javascript +var img = new Image(); +img.src = 'https://example.com/my_image.png'; +img.onload = function() { + var ctx = document.getElementById('canvas').getContext('2d'); + var fillPattern = ctx.createPattern(img, 'repeat'); + + var chart = new Chart(ctx, { + data: { + labels: ['Item 1', 'Item 2', 'Item 3'], + datasets: [{ + data: [10, 20, 30], + backgroundColor: fillPattern + }] + } + }) +} +``` + +Using pattern fills for data graphics can help viewers with vision deficiencies (e.g. color-blindness or partial sight) to [more easily understand your data](http://betweentwobrackets.com/data-graphics-and-colour-vision/). + +Using the [Patternomaly](https://github.com/ashiguruma/patternomaly) library you can generate patterns to fill datasets. + +```javascript +var chartData = { + datasets: [{ + data: [45, 25, 20, 10], + backgroundColor: [ + pattern.draw('square', '#ff6384'), + pattern.draw('circle', '#36a2eb'), + pattern.draw('diamond', '#cc65fe'), + pattern.draw('triangle', '#ffce56'), + ] + }], + labels: ['Red', 'Blue', 'Purple', 'Yellow'] +}; +``` \ No newline at end of file diff --git a/docs/general/fonts.md b/docs/general/fonts.md new file mode 100644 index 00000000000..6d3aedbeed6 --- /dev/null +++ b/docs/general/fonts.md @@ -0,0 +1,41 @@ +# Fonts + +There are 4 special global settings that can change all of the fonts on the chart. These options are in `Chart.defaults.global`. The global font settings only apply when more specific options are not included in the config. + +For example, in this chart the text will all be red except for the labels in the legend. + +```javascript +Chart.defaults.global.defaultFontColor = 'red'; +let chart = new Chart(ctx, { + type: 'line', + data: data, + options: { + legend: { + labels: { + // This more specific font property overrides the global property + fontColor: 'black' + } + } + } +}); +``` + +## defaultFontColor +**Type:** Color +**Default:** `'#666'` +Default font color for all text. + +## defaultFontFamily +**Type:** String +**Default:** `"'Helvetica Neue', 'Helvetica', 'Arial', sans-serif"` +Default font family for all text. + +## defaultFontSize +**Type:** Number +**Default:** `12` +Default font size (in px) for text. Does not apply to radialLinear scale point labels. + +## defaultFontStyle +**Type:** String +**Default:** `'normal'` +Default font style. Does not apply to tooltip title or footer. Does not apply to chart title. \ No newline at end of file diff --git a/docs/general/interactions/README.md b/docs/general/interactions/README.md new file mode 100644 index 00000000000..c702910d9db --- /dev/null +++ b/docs/general/interactions/README.md @@ -0,0 +1,18 @@ +# Interactions + +The hover configuration is passed into the `options.hover` namespace. The global hover configuration is at `Chart.defaults.global.hover`. To configure which events trigger chart interactions, see [events](./events.md#events). + +## mode +**Type:** String +**Default:** `'nearest` +Sets which elements appear in the tooltip. See [Interaction Modes](./modes.md#interaction-modes) for details. + +## intersect +**Type:** Boolean +**Default:** `true` +if true, the hover mode only applies when the mouse position intersects an item on the chart. + +## animationDuration +**Type:** Number +**Default:** `400` +Duration in milliseconds it takes to animate hover style changes. \ No newline at end of file diff --git a/docs/general/interactions/events.md b/docs/general/interactions/events.md new file mode 100644 index 00000000000..dc2d704e3e2 --- /dev/null +++ b/docs/general/interactions/events.md @@ -0,0 +1,29 @@ +# Events +The following properties define how the chart interacts with events. + +## events +**Type:** String[] +**Default:** `["mousemove", "mouseout", "click", "touchstart", "touchmove", "touchend"]` +The `events` option defines the browser events that the chart should listen to for tooltips and hovering. + +For example, to have the chart only respond to click events, you could do +```javascript +var chart = new Chart(ctx, { + type: 'line', + data: data, + options: { + // This chart will not respond to mousemove, etc + events: ['click'] + } +}); +``` + +## onHover Callback +**Type:** Function +**Default:** `null` +Called when any of the events fire. Called in the context of the chart and passed the event and an array of active elements (bars, points, etc). + +# onClick Callback +**Type:** Function +**Default:** `null` +Called if the event is of type 'mouseup' or 'click'. Called in the context of the chart and passed the event and an array of active elements \ No newline at end of file diff --git a/docs/general/interactions/modes.md b/docs/general/interactions/modes.md new file mode 100644 index 00000000000..6775c590c3b --- /dev/null +++ b/docs/general/interactions/modes.md @@ -0,0 +1,104 @@ +# Interaction Modes + +When configuring interaction with the graph via hover or tooltips, a number of different modes are available. + +The modes are detailed below and how they behave in conjunction with the `intersect` setting. + +## point +Finds all of the items that intersect the point. + +```javascript +var chart = new Chart(ctx, { + type: 'line', + data: data, + options: { + tooltips: { + mode: 'point' + } + } +}) +``` + +## nearest +Gets the item that is nearest to the point. The nearest item is determined based on the distance to the center of the chart item (point, bar). If 2 or more items are at the same distance, the one with the smallest area is used. 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 +var chart = new Chart(ctx, { + type: 'line', + data: data, + options: { + tooltips: { + mode: 'nearest' + } + } +}) +``` + +## single (deprecated) +Finds the first item that intersects the point and returns it. Behaves like 'nearest' mode with intersect = true. + +## label (deprecated) +See `'index'` mode + +## index +Finds item at the same index. If the `intersect` setting is true, the first intersecting item is used to determine the index in the data. If `intersect` false the nearest item is used to determine the index. + +```javascript +var chart = new Chart(ctx, { + type: 'line', + data: data, + options: { + tooltips: { + mode: 'index' + } + } +}) +``` + +## x-axis (deprecated) +Behaves like `'index'` mode with `intersect = false`. + +## dataset +Finds items in the same dataset. If the `intersect` setting is true, the first intersecting item is used to determine the index in the data. If `intersect` false the nearest item is used to determine the index. + +```javascript +var chart = new Chart(ctx, { + type: 'line', + data: data, + options: { + tooltips: { + mode: 'dataset' + } + } +}) +``` + +## x +Returns all items that would intersect based on the `X` coordinate of the position only. Would be useful for a vertical cursor implementation. Note that this only applies to cartesian charts + +```javascript +var chart = new Chart(ctx, { + type: 'line', + data: data, + options: { + tooltips: { + mode: 'x' + } + } +}) +``` + +## y +Returns all items that would intersect based on the `Y` coordinate of the position. This would be useful for a horizontal cursor implementation. Note that this only applies to cartesian charts. + +```javascript +var chart = new Chart(ctx, { + type: 'line', + data: data, + options: { + tooltips: { + mode: 'y' + } + } +}) +``` \ No newline at end of file diff --git a/docs/general/responsive.md b/docs/general/responsive.md new file mode 100644 index 00000000000..0fecb486dca --- /dev/null +++ b/docs/general/responsive.md @@ -0,0 +1,49 @@ +# Responsive Charts + +Chart.js provides a few options for controlling resizing behaviour of charts. + +## responsive +**Type:** Boolean +**Default:** `true` +Resizes the chart canvas when its container does. + +```javascript +var options = { + responsive: false +}; +``` + +## responsiveAnimationDuration +**Type:** Number +**Default:** `0` +Duration in milliseconds it takes to animate to new size after a resize event. + +```javascript +var options = { + responsiveAnimationDuration: 100 +}; +``` + +## maintainAspectRatio +**Type:** Boolean +**Default:** `true` +Maintain the original canvas aspect ratio `(width / height)` when resizing. + +```javascript +var options = { + maintainAspectRatio: false +}; +``` + +## onResize +**Type:** Function +**Default:** `null` +Called when a resize occurs. Gets passed two arguments: the chart instance and the new size. + +```javascript +var options = { + onResize: function(chart, newSize) { + // the chart is now at the new size. If you need to change configurations you could do it here. + } +};) +``` \ No newline at end of file diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md new file mode 100644 index 00000000000..bb3e17f1f67 --- /dev/null +++ b/docs/getting-started/README.md @@ -0,0 +1,43 @@ +# Getting Started + +Let's get started using Chart.js! + +First, we need to have a canvas in our page. + +```html + +``` + +Now that we have a canvas we can use, we need to include Chart.js in our page. + +```html + + +``` + +## Common JS + +```javascript +var Chart = require('chart.js') +var myChart = new Chart(ctx, {...}) +``` + +## Require JS + +```javascript +require(['path/to/Chartjs/src/chartjs.js'], function(Chart){ + var myChart = new Chart(ctx, {...}) +}) +``` \ No newline at end of file diff --git a/docs/getting-started/usage.md b/docs/getting-started/usage.md new file mode 100644 index 00000000000..739c838596c --- /dev/null +++ b/docs/getting-started/usage.md @@ -0,0 +1,65 @@ +# Usage +Chart.js can be used with ES6 modules, plain JavaScript and module loaders. + +## Creating a Chart + +To create a chart, we need to instantiate the `Chart` class. To do this, we need to pass in the node, jQuery instance, or 2d context of the canvas of where we want to draw the chart. Here's an example. + +```html + +``` + +```javascript +// Any of the following formats may be used +var ctx = document.getElementById("myChart"); +var ctx = document.getElementById("myChart").getContext("2d"); +var ctx = $("#myChart"); +var ctx = "myChart"; +``` + +Once you have the element or context, you're ready to instantiate a pre-defined chart-type or create your own! + +The following example instantiates a bar chart showing the number of votes for different colors and the y-axis starting at 0. + +```html + + +``` \ No newline at end of file diff --git a/docs/notes/README.md b/docs/notes/README.md new file mode 100644 index 00000000000..2795faebc85 --- /dev/null +++ b/docs/notes/README.md @@ -0,0 +1 @@ +# Additional Notes \ No newline at end of file diff --git a/docs/notes/comparison.md b/docs/notes/comparison.md new file mode 100644 index 00000000000..aa7e25eec42 --- /dev/null +++ b/docs/notes/comparison.md @@ -0,0 +1,32 @@ +# Comparison with Other Charting Libraries + +Library Features + +| Feature | Chart.js | D3 | HighCharts | Chartist | +| ------- | -------- | --- | ---------- | -------- | +| Completely Free | ✓ | ✓ | | ✓ | +| Canvas | ✓ | | | | +| SVG | | ✓ | ✓ | ✓ | +| Built-in Charts | ✓ | | ✓ | ✓ | +| 8+ Chart Types | ✓ | ✓ | ✓ | | +| Extendable to Custom Charts | ✓ | ✓ | | | +| Supports Modern Browsers | ✓ | ✓ | ✓ | ✓ | +| Extensive Documentation | ✓ | ✓ | ✓ | ✓ | +| Open Source | ✓ | ✓ | ✓ | ✓ | + +Built in Chart Types + +| Type | Chart.js | HighCharts | Chartist | +| ---- | -------- | ---------- | -------- | +| Combined Types | ✓ | ✓ | | +| Line | ✓ | ✓ | ✓ | +| Bar | ✓ | ✓ | ✓ | +| Horizontal Bar | ✓ | ✓ | ✓ | +| Pie/Doughnut | ✓ | ✓ | ✓ | +| Polar Area | ✓ | ✓ | | +| Radar | ✓ | | | +| Scatter | ✓ | ✓ | ✓ | +| Bubble | ✓ | | | +| Gauges | | ✓ | | +| Maps (Heat/Tree/etc.) | | ✓ | | + diff --git a/docs/notes/extensions.md b/docs/notes/extensions.md new file mode 100644 index 00000000000..5fef6fd9a3e --- /dev/null +++ b/docs/notes/extensions.md @@ -0,0 +1,26 @@ +# Popular Extensions + +There are many extensions which are available for use with popular frameworks. Some particularly notable ones are listed here. + +## Angular + - angular-chart.js + - tc-angular-chartjs + - angular-chartjs + - Angular Chart-js Directive + +## React + - react-chartjs2 + - react-chartjs-2 + +## Django + - Django JChart + - Django Chartjs + +## Ruby on Rails + - chartjs-ror + +## Laravel + - laravel-chartjs + +#### Vue.js + - vue-chartjs diff --git a/docs/notes/license.md b/docs/notes/license.md new file mode 100644 index 00000000000..b933686df54 --- /dev/null +++ b/docs/notes/license.md @@ -0,0 +1,3 @@ +# License + +Chart.js is open source and available under the MIT license. \ No newline at end of file