Helper Plugin for Chart.js
The Chart.js helper plugin provides support for the Chart.js library. This plugin is best suited for use on mobile devices. For detailed information about Chart.js, see http://www.chartjs.org.
Adding Chart.js to the Page Class
If the following required file has not already been installed, you can get it from the Chart.js version 1.0.1 source available at https://github.com/nnnick/Chart.js/releases:
These instructions assume that this file is in <install-dir>/csp/broker (see “Adding Plugins to the Page Class” for details). Add the following filename string to the JSINCLUDES parameter of your page class. Caché assumes that /csp/broker is the root directory for all relative paths:
Bear in mind that files are loaded in the order that they are listed in the parameters. If you also use the Dojo 2D Chart helper plugin, be sure to list the Chart.js library before the Dojo library in the JSINCLUDES parameter.
The following example demonstrates how the Chart.js helper can be registered in your pageContents XData block (as described in “Adding Plugins to the Page Class”). This example uses the Default page manager, but any page manager will work:
<mojo:mojoDefaultPageManager> <mojo:charts-1.0.1-Helper/> </mojo:mojoDefaultPageManager>
The Chart.js helper plugin can be used with other page manager and helper plugins. If the Highcharts helper plugin is also used, some plugin conflicts will occur (see “Chart.js Layout Objects” in the following section for details).
For more information on this plugin, see %ZEN.Mojo.Plugin.charts101Helper in the class reference.
Using Chart.js in a Template Class
The following list is intended as a quick reference to the layout options offered by the Chart.js helper plugin. For complete reference information, use the Plugin Documentation app (see “Using the Plugin Documentation and Widget Reference Apps”):
$chart displays a chart specified by type ($barchart by default). The other layout objects display specific chart types:
If both the Chart.js helper and the Highcharts helper are registered in the same pageContents XData block, plugin conflicts should be resolved for the following objects: $chart, $barchart, $linechart, $piechart. To resolve all conflicts in favor of Chart.js, just list it before Highcharts in pageContents. See “Detecting and Resolving Plugin Conflicts” for more information.
The following methods are available within all appropriate layout objects:
$hide() — Hides the layout object.
$refresh() — Re-renders the HTML for the layout object.
$show() — Shows the layout object.
See “Custom Chart.js Helper Plugin Methods” later in this chapter for a list of Chart.js utility methods.
This plugin does not provide direct access to Chart.js library functions.
The onselect() event handler must be implemented for each Chart.js chart type that your application will use. For details, see “Implementing onselect() for Chart.js Events” later in this chapter.
Custom Chart.js Helper Plugin Methods
In addition to methods inherited from %ZEN.Mojo.Plugin.baseHelperPlugin, the Chart.js helper plugin provides the following utility methods. Each of these methods will call the corresponding Chart.js library prototype method for the appropriate chart type.
Adds data to the chart specified by key. The labelOrIndex parameter is expected to be a dataset index in doughnut, pie, and polar charts.
Removes data from the chart specified by key. The index parameter only applies to doughnut, pie, and polar chart types. If index is not specified for those chart types, the last data element is removed. The other chart types simply remove the first variable.
Updates and re-renders the chart specified by key.
Implementing onselect() for Chart.js Events
The Chart.js helper plugin supports event handling for each chart type. To handle a selection event, your template must implement an override of the contentTemplate.onselect() method (see “Event Handling” in Using Zen Mojo). When a chart layout object is selected, the plugin passes the following arguments to onselect():
key — the key of the selected layout object
value — an array of values
docViewId — the id of the documentView
The chart is driven by the value data object. The value argument passed to onselect() is an array returned by a Chart.js library prototype method of the chart instance, and has a structure that varies according to the chart type:
$linechart and $radarchart — value is an array returned by the getPointsAtEvent() method (see http://www.chartjs.org/docs/#line-chart-prototype-methods).
$barchart — value is an array returned by the getBarsAtEvent() method (see http://www.chartjs.org/docs/#bar-chart-prototype-methods).
$piechart, $doughnutchart, and $polarareachart — value is an array returned by the getSegmentsAtEvent() method (see http://www.chartjs.org/docs/#polar-area-chart-prototype-methods).
$chart — value is an array returned by the method appropriate to the specified chart type.
Using Chart.js Plugin Sample Code
The Widget Reference offers interactive widget samples for the Chart.js helper. The reference includes working examples, detailed descriptions, and source code that you can cut and paste into your own applications.