README.md in chartjs-ror-1.1.1 vs README.md in chartjs-ror-2.0.0
- old
+ new
@@ -1,11 +1,10 @@
# chartjs-ror
Simplifies using [Chart.js][] in Rails views.
* All of Chart.js's features via one line of Ruby.
-* Legends for your charts.
* Renders charts on page load rather than DOMContentReady ([reason][browsersupport]).
* Animates unless you have Modernizr and it doesn't detect canvas support ([reason][browsersupport]). You can manually override this.
* Optional alternative (better?) abscissa scale calculations.
* Utility method for filling in gaps in integer series.
@@ -25,15 +24,13 @@
```javascript
//= require Chart
//= require excanvas
```
-Add [Modernizr][] if you need it to your app's assets.
+You only need [excanvas][ExplorerCanvas] for IE7 and IE8. Add [Modernizr][] if you need it to your app's assets.
-Ensure your browsers will display `<figure/>` and `<figcaption/>` correctly.
-
## Usage
Each chart type has a corresponding helper for your views. The helper methods take the same arguments as their Javascript counterparts. The `options` are always optional.
### Charts with multiple datasets
@@ -170,62 +167,75 @@
### Options
You can put anything in the `options` hash that Chart.js recognises. It also supports these non-Chart.js settings:
-* `:class` - class of the enclosing `<figure/>` - default is `chart`.
+* `:class` - class of the enclosing `<figure/>` - default is `chart`.
* `:element_id` - id of the `<canvas/>` - default is `chart-n` where `n` is the 0-based index of the chart on the page.
-* `:width` - width of the canvas in px - default is `400`.
-* `:height` - height of the canvas in px - default is `400`.
-* `:legend` - an array of names for the datasets.
+* `:width` - width of the canvas in px - default is `400`.
+* `:height` - height of the canvas in px - default is `400`.
### Sample output:
```html
<figure class="chart">
<canvas id="chart-0" width=400 height=400></canvas>
- <!-- if :legend option is given -->
- <figcaption>
- <ol>
- <li class="chart-0 dataset-0"><span></span>Apples</li>
- <li class="chart-0 dataset-1"><span></span>Bananas</li>
- <li class="chart-0 dataset-2"><span></span>Cherries</li>
- </ol>
- </figcaption>
+ <!-- legend rendered here -->
</figure>
<script type="text/javascript">
- var initChart = function() {
- var data = {labels: ["Apples","Bananas","Cherries"], datasets: [{"data":[42,153,...],...}, ...]};
- var opts = {"scaleFontSize":10};
- if (!('animation' in opts)) {
- opts['animation'] = (typeof Modernizr == 'undefined') || Modernizr.canvas;
+ (function() {
+ var initChart = function() {
+ var data = {labels: ["Apples","Bananas","Cherries"], datasets: [{"data":[42,153,...],...}, ...]};
+ var opts = {"scaleFontSize":10};
+ if (!("animation" in opts)) {
+ opts['animation'] = (typeof Modernizr == "undefined") || Modernizr.canvas;
+ }
+ var canvas = document.getElementById("chart-0");
+ var ctx = canvas.getContext('2d');
+ var chart = new Chart(ctx).Bar(data, opts);
+ window.Chart["chart-0"] = chart;
+
+ var legend = chart.generateLegend();
+ if (legend.trim().length > 0) {
+ var legendHolder = document.createElement("div");
+ legendHolder.innerHTML = legend;
+ canvas.parentNode.insertBefore(legendHolder.firstChild, canvas.nextSibling);
+ }
+ };
+ if (window.addEventListener) {
+ window.addEventListener('load', initChart, false);
}
- var ctx = document.getElementById("chart-0").getContext('2d');
- new Chart(ctx).Bar(data, opts);
- };
- if (window.addEventListener) { // W3C standard
- window.addEventListener('load', initChart, false);
- }
- else if (window.attachEvent) { // IE
- window.attachEvent('onload', initChart);
- }
+ else if (window.attachEvent) {
+ window.attachEvent('onload', initChart);
+ }
+ })();
</script>
```
-### Legend
+The Javascript is actually written out on a single line but you get the idea.
-Each item in the legend array is given two classes:
-* `dataset-m` where `m` is the 0-based index of the item.
-* The id value of the canvas.
+### Templates (tooltips and legends)
-This lets you style legends in general but override the styles for specific charts.
+If you specify a custom template, e.g. in `legendTemplate` or `tooltipTemplate`, you must escape opening tags in the Javascript-template string, i.e. use `<%%= value %>` instead of `<%= value %>`.
+You need to add an escape `%` character for each level of rendering. For exampe:
+- If your view calls the chart helper directly, use `<%%= value %>`.
+- If your view renders a partial which calls the chart helper, use `<%%%= value %>`.
+
+
+### Legend
+
+A legend will be rendered using `chart.generateLegend()` ([docs][advanced]).
+
+If you don't want a legend, supply `legendTemplate: " "` in the options for your chart. For some reason an empty string causes an exception inside Chart.js so use a single space.
+
+
### Scale calculations
-The plugin implements its own abscissa scale calculations which I prefer to Chart.js's. You can opt-in to these calculations by passing `scaleOverride: true` in the `options` hash, without any of the other scale override keys (`scaleSteps`, `scaleStepWidth`, `scaleStartValue`).
+The plugin implements its own abscissa scale calculations which I prefer to Chart.js's (see [Chart.js#132][calculations]). You can opt-in to these calculations by passing `scaleOverride: true` in the `options` hash, without any of the other scale override keys (`scaleSteps`, `scaleStepWidth`, `scaleStartValue`).
## Inspiration
* [Chart.js][] (obviously)
@@ -236,11 +246,13 @@
Copyright Andrew Stewart, AirBlade Software. Released under the MIT licence.
[Chart.js]: http://www.chartjs.org/
- [Chartkick]: http://ankane.github.io/chartkick/
- [browsersupport]: http://www.chartjs.org/docs/#generalIssues-browserSupport
+ [Chartkick]: https://ankane.github.io/chartkick/
+ [browsersupport]: http://www.chartjs.org/docs/#notes-browser-support
[linechart]: http://www.chartjs.org/docs/#lineChart-exampleUsage
[piechart]: http://www.chartjs.org/docs/#pieChart-exampleUsage
[Modernizr]: http://modernizr.com
[ExplorerCanvas]: https://code.google.com/p/explorercanvas
+ [advanced]: http://www.chartjs.org/docs/#advanced-usage-prototype-methods
+ [calculations]: https://github.com/nnnick/Chart.js/issues/132