From 660c3850d7b7137988314e269dc37bd35624d3f8 Mon Sep 17 00:00:00 2001 From: Zach Panzarino Date: Mon, 8 Aug 2016 03:08:13 +0000 Subject: [PATCH 1/3] Documentation updates Adds a lot of new information to the docs that will help developers better utilize the entire Chart.js library List of implemented changes: - Reverse option for legends (resolves #3102) - Information about chart resizing (resolves #3023) - Mixed chart types (resolves #2825) (resolves #2431) - Chart library comparison table (resolves #2605) - getDetasetMeta function information (resolves #2521) - Popular Extensions (resolves #2365) --- docs/00-Getting-Started.md | 5 ++- docs/01-Chart-Configuration.md | 32 +++++++++++++- docs/04-Bar-Chart.md | 41 +++++++++--------- docs/09-Advanced.md | 13 ++++++ docs/10-Notes.md | 78 ++++++++++++++++++++++++++++++---- samples/combo-bar-line.html | 10 ++--- 6 files changed, 143 insertions(+), 36 deletions(-) diff --git a/docs/00-Getting-Started.md b/docs/00-Getting-Started.md index a362296523c..155b40c7222 100644 --- a/docs/00-Getting-Started.md +++ b/docs/00-Getting-Started.md @@ -5,7 +5,8 @@ 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. +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 @@ -134,3 +135,5 @@ var myChart = new Chart(ctx, { ``` 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](https://github.com/chartjs/Chart.js/tree/master/samples) of the GitHub repository. diff --git a/docs/01-Chart-Configuration.md b/docs/01-Chart-Configuration.md index 43bf5ab3976..a6d62480e99 100644 --- a/docs/01-Chart-Configuration.md +++ b/docs/01-Chart-Configuration.md @@ -77,7 +77,7 @@ The following options are applicable to all charts. The can be set on the [globa Name | Type | Default | Description --- | --- | --- | --- -responsive | Boolean | true | Resizes when the canvas container does. +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 @@ -144,6 +144,7 @@ fontFamily | String | "'Helvetica Neue', 'Helvetica', 'Arial', sans-serif" | Fon 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. usePointStyle | Boolean | false | Label style will match corresponding point style (size is based on fontSize, boxWidth is not used in this case). +reverse | Boolean | false | Legend will show datasets in reverse order #### Legend Item Interface @@ -426,3 +427,32 @@ img.onload = function() { } ``` + +### Mixed Chart Types + +When creating a chart, you have the option to overlay different chart types on top of eachother 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/04-Bar-Chart.md b/docs/04-Bar-Chart.md index 6f0e2a707ea..241f8efa91c 100644 --- a/docs/04-Bar-Chart.md +++ b/docs/04-Bar-Chart.md @@ -59,22 +59,22 @@ var data = { { 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)' + '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 + '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], } ] @@ -121,13 +121,12 @@ new Chart(ctx, { data: data, options: { scales: { - xAxes: [{ - stacked: true - }], - yAxes: [{ - stacked: true - }] - } + xAxes: [{ + stacked: true + }], + yAxes: [{ + stacked: true + }] } } }); diff --git a/docs/09-Advanced.md b/docs/09-Advanced.md index 58dd50da996..b1e1b65bcaf 100644 --- a/docs/09-Advanced.md +++ b/docs/09-Advanced.md @@ -125,6 +125,19 @@ 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, and can be used to share data between charts. + +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: diff --git a/docs/10-Notes.md b/docs/10-Notes.md index b3183cae52a..2c055b17edb 100644 --- a/docs/10-Notes.md +++ b/docs/10-Notes.md @@ -4,7 +4,13 @@ anchor: notes --- ### Previous versions -Please note - documentation for previous versions are available on the GitHub repo. Version 1.x may continue to receive updates for bug fixes or high priority items. +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) @@ -23,13 +29,69 @@ Please report these on the GitHub page - at MIT 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 Extensions + +There are many extensions which are available for use with popular frameworks. Some particularly notable ones are listed here: + +#### Angular + - https://github.com/carlcraig/tc-angular-chartjs + - https://github.com/petermelias/angular-chartjs + - https://github.com/earlonrails/angular-chartjs-directive + +#### React + - https://github.com/jhudson8/react-chartjs/tree/chartjs-v2 + +#### Django + - https://github.com/novafloss/django-chartjs + +#### Ruby on Rails + - https://github.com/airblade/chartjs-ror + +#### Laravel + - https://github.com/fxcosta/laravel-chartjs diff --git a/samples/combo-bar-line.html b/samples/combo-bar-line.html index 31926f3526d..08739e1090e 100644 --- a/samples/combo-bar-line.html +++ b/samples/combo-bar-line.html @@ -27,7 +27,7 @@ return Math.round(Math.random() * 255); }; - var barChartData = { + var chartData = { labels: ["January", "February", "March", "April", "May", "June", "July"], datasets: [{ type: 'bar', @@ -53,9 +53,9 @@ }; window.onload = function() { var ctx = document.getElementById("canvas").getContext("2d"); - window.myBar = new Chart(ctx, { + window.myMixedChart = new Chart(ctx, { type: 'bar', - data: barChartData, + data: chartData, options: { responsive: true, title: { @@ -67,12 +67,12 @@ }; $('#randomizeData').click(function() { - $.each(barChartData.datasets, function(i, dataset) { + $.each(chartData.datasets, function(i, dataset) { dataset.backgroundColor = 'rgba(' + randomColorFactor() + ',' + randomColorFactor() + ',' + randomColorFactor() + ',.7)'; dataset.data = [randomScalingFactor(), randomScalingFactor(), randomScalingFactor(), randomScalingFactor(), randomScalingFactor(), randomScalingFactor(), randomScalingFactor()]; }); - window.myBar.update(); + window.myMixedChart.update(); }); From 52667a3d0ceafc5beb661ccd2b0f19c34687659e Mon Sep 17 00:00:00 2001 From: Zach Panzarino Date: Mon, 8 Aug 2016 03:31:15 +0000 Subject: [PATCH 2/3] Update link pattern for popular extensions --- docs/10-Notes.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/10-Notes.md b/docs/10-Notes.md index 2c055b17edb..8cc10385118 100644 --- a/docs/10-Notes.md +++ b/docs/10-Notes.md @@ -80,18 +80,19 @@ Built in Chart Types There are many extensions which are available for use with popular frameworks. Some particularly notable ones are listed here: #### Angular - - https://github.com/carlcraig/tc-angular-chartjs - - https://github.com/petermelias/angular-chartjs - - https://github.com/earlonrails/angular-chartjs-directive + - angular-chart.js + - tc-angular-chartjs + - angular-chartjs + - Angular Chart-js Directive #### React - - https://github.com/jhudson8/react-chartjs/tree/chartjs-v2 + - react-chartjs #### Django - - https://github.com/novafloss/django-chartjs + - Django Chartjs #### Ruby on Rails - - https://github.com/airblade/chartjs-ror + - chartjs-ror #### Laravel - - https://github.com/fxcosta/laravel-chartjs + - laravel-chartjs From 57f2d7de58427a413c406ef0a5a4e120e3351620 Mon Sep 17 00:00:00 2001 From: Zach Panzarino Date: Tue, 9 Aug 2016 14:34:59 +0000 Subject: [PATCH 3/3] Update docs and add plugin section (suggested by @simonbrunel) --- docs/00-Getting-Started.md | 2 +- docs/09-Advanced.md | 2 +- docs/10-Notes.md | 13 ++++++++++++- 3 files changed, 14 insertions(+), 3 deletions(-) diff --git a/docs/00-Getting-Started.md b/docs/00-Getting-Started.md index 155b40c7222..d6e9f0f2716 100644 --- a/docs/00-Getting-Started.md +++ b/docs/00-Getting-Started.md @@ -136,4 +136,4 @@ var myChart = new Chart(ctx, { 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](https://github.com/chartjs/Chart.js/tree/master/samples) of the GitHub repository. +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/09-Advanced.md b/docs/09-Advanced.md index b1e1b65bcaf..7c96883ba48 100644 --- a/docs/09-Advanced.md +++ b/docs/09-Advanced.md @@ -127,7 +127,7 @@ myLineChart.getDatasetAtEvent(e); #### .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, and can be used to share data between charts. +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. diff --git a/docs/10-Notes.md b/docs/10-Notes.md index 8cc10385118..fbeed85fd7b 100644 --- a/docs/10-Notes.md +++ b/docs/10-Notes.md @@ -75,9 +75,20 @@ Built in Chart Types | 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). + + - Chart.Zoom.js - Enable zooming and panning on charts + - Chart.Annotation.js - Draw lines and boxes on chart area + - Chart.BarFunnel.js - Adds a bar funnel chart type + - Chart.Deferred.js - Defer initial chart update until chart scrolls into viewport + - Chart.Smith.js - Adds a smith chart type + - Chart.LinearGauge.js - Adds a linear gauge chart type + ### Popular Extensions -There are many extensions which are available for use with popular frameworks. Some particularly notable ones are listed here: +There are many extensions which are available for use with popular frameworks. Some particularly notable ones are listed here. #### Angular - angular-chart.js