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.orgOpens in a new tab.

Adding Chart.js to the Page Class

Adding Required Chart.js Files

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/releasesOpens in a new tab:

Chart.min.js

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:

JSINCLUDES filenames:
"Chart.min.js"

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.

Registering the Chart.js Helper Plugin

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).

Other Options and Requirements

For more information on this plugin, see %ZEN.Mojo.Plugin.charts101HelperOpens in a new tab in the class reference.

Using Chart.js in a Template Class

Chart.js Layout Objects

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:

$barchart
$doughnutchart
$linechart
$piechart
$polarareachart
$radarchart

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.

Custom Chart.js Layout Object Methods

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.

Chart.js Helper Plugin Methods

See “Custom Chart.js Helper Plugin Methods” later in this chapter for a list of Chart.js utility methods.

Direct Access to the Chart.js Library

This plugin does not provide direct access to Chart.js library functions.

Event Handling

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.baseHelperPluginOpens in a new tab, 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.

addData()
```
  method addData(key, data, labelOrIndex) [ Language = javascript ]
```
Adds data to the chart specified by key. The labelOrIndex parameter is expected to be a dataset index in doughnut, pie, and polar charts.
removeData()
```
  method (key, index) [ Language = javascript ]
```
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.
update()
```
  method update(key) [ Language = javascript ]
```
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-methodsOpens in a new tab).
$barchart — value is an array returned by the getBarsAtEvent() method (see http://www.chartjs.org/docs/#bar-chart-prototype-methodsOpens in a new tab).
$piechart, $doughnutchart, and $polarareachart — value is an array returned by the getSegmentsAtEvent() method (see http://www.chartjs.org/docs/#polar-area-chart-prototype-methodsOpens in a new tab).
$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.