Merge 'Documentation updates' #3110

chartjs · Aug 10, 2016 · 6e9ee1f · 6e9ee1f
2 parents 8837152 + 57f2d7d
commit 6e9ee1f
Show file tree

Hide file tree

Showing 6 changed files with 155 additions and 36 deletions.
diff --git 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 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
@@ -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
 
@@ -446,3 +447,32 @@ var chartData = {
 	labels: ['Red', 'Blue', 'Purple', 'Yellow']
 };
 ```
+
+### 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
@@ -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],
 		}
 	]
@@ -123,13 +123,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
@@ -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.
+
+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
@@ -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,81 @@ Please report these on the GitHub page - at <a href="https://github.com/chartjs/
 
 
 ### Contributing
-New contributions to the library are welcome, just a couple of guidelines:
 
-- Tabs for indentation, not spaces please.
-- Please ensure you're changing the individual files in `/src`, not the concatenated output in the `Chart.js` file in the root of the repo.
-- Please check that your code will pass `jshint` code standards, `gulp jshint` will run this for you.
-- Please 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 extension would be more appropriate.
+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 `jshint` code standards, `gulp jshint` 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 <a href="http://opensource.org/licenses/MIT" target="_blank">MIT license</a>.
+
+Chart.js is <a href="https://github.com/chartjs/Chart.js" target="_blank">open source</a> and available under the <a href="http://opensource.org/licenses/MIT" target="_blank">MIT license</a>.
+
+### 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).
+
+ - <a href="https://github.com/chartjs/Chart.Zoom.js" target="_blank">Chart.Zoom.js</a> - Enable zooming and panning on charts
+ - <a href="https://github.com/chartjs/Chart.Annotation.js" target="_blank">Chart.Annotation.js</a> - Draw lines and boxes on chart area
+ - <a href="https://github.com/chartjs/Chart.BarFunnel.js" target="_blank">Chart.BarFunnel.js</a> - Adds a bar funnel chart type
+ - <a href="https://github.com/chartjs/Chart.Deferred.js" target="_blank">Chart.Deferred.js</a> - Defer initial chart update until chart scrolls into viewport
+ - <a href="https://github.com/chartjs/Chart.smith.js" target="_blank">Chart.Smith.js</a> - Adds a smith chart type
+ - <a href="https://github.com/chartjs/Chart.LinearGauge.js" target="_blank">Chart.LinearGauge.js</a> - 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.
+
+#### Angular
+ - <a href="https://github.com/jtblin/angular-chart.js" target="_blank">angular-chart.js</a>
+ - <a href="https://github.com/carlcraig/tc-angular-chartjs" target="_blank">tc-angular-chartjs</a>
+ - <a href="https://github.com/petermelias/angular-chartjs" target="_blank">angular-chartjs</a>
+ - <a href="https://github.com/earlonrails/angular-chartjs-directive" target="_blank">Angular Chart-js Directive</a>
+
+#### React
+ - <a href="https://github.com/earlonrails/angular-chartjs-directive" target="_blank">react-chartjs</a>
+
+#### Django
+ - <a href="https://github.com/novafloss/django-chartjs" target="_blank">Django Chartjs</a>
+
+#### Ruby on Rails
+ - <a href="https://github.com/airblade/chartjs-ror" target="_blank">chartjs-ror</a>
+
+#### Laravel
+ - <a href="https://github.com/fxcosta/laravel-chartjs" target="_blank">laravel-chartjs</a>
diff --git 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();
         });
     </script>
 </body>