From: Zach Panzarino Date: Mon, 8 Aug 2016 03:08:13 +0000 (+0000) Subject: Documentation updates X-Git-Tag: v2.2.2~14^2~2 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=660c3850d7b7137988314e269dc37bd35624d3f8;p=thirdparty%2FChart.js.git 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) --- diff --git a/docs/00-Getting-Started.md b/docs/00-Getting-Started.md index a36229652..155b40c72 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 43bf5ab39..a6d62480e 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 6f0e2a707..241f8efa9 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 58dd50da9..b1e1b65bc 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 b3183cae5..2c055b17e 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 31926f352..08739e109 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(); });