Helper Plugin for Highcharts
The Highcharts helper plugin provides support for the Highcharts library. This plugin is best suited for use on mobile devices. For detailed information about Highcharts, see http://www.highcharts.com/Opens in a new tab.
Adding Highcharts to the Page Class
The files listed in this section are contained in the Highcharts 4.0.4 release and the jQuery 2.0.3 release. If they are not already installed on your system, you can get Highcharts at http://code.highcharts.com/zips/Highcharts-4.0.4.zipOpens in a new tab and jQuery at https://code.jquery.com/jquery/Opens in a new tab.
These instructions assume that the Highcharts files are in a subdirectory of <install-dir>/csp/broker named highcharts-4-0-4 (see “Adding Plugins to the Page Class” for details). The following file must be available:
-
/js/highcharts.js
Highcharts also requires the jQuery 2.0.3 library. The following file must be in /csp/broker:
-
jquery-2.0.3.min.js
Add the following filename strings to the JSINCLUDES parameter of your page class. Caché assumes that /csp/broker is the root directory for all relative paths:
-
JSINCLUDES filenames:
"jquery-2.0.3.min.js, js/highcharts.js"
Bear in mind that files are loaded in the order that they are listed in the parameters. In this case, the jQuery library must be listed first because the Highcharts library depends on it.
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:highCharts-4.0.4-Helper/>
</mojo:mojoDefaultPageManager>
The Highcharts helper plugin can be used with other page manager and helper plugins. If the Chart.js helper plugin is also used, some plugin conflicts will occur (see “Highcharts Helper Layout Objects” later in this chapter for details).
For more information on this plugin, see %ZEN.Mojo.Plugin.highCharts404Helper in the class reference.
The %ZEN.Mojo.Plugin.highCharts401Helper plugin class is also available, providing support for earlier Highcharts version 4.0.1. Usage is identical to version 4.0.4 except that version 4.0.1 of highcharts.js is used, and the following element is used to register the plugin in the pageContents XData block:
<mojo:highCharts-4.0.1-Helper/>
Using Highcharts in a Template Class
The $chart layout object displays a chart specified by type ($barchart by default). See “Highcharts Helper Layout Objects” for a list of layout objects that display specific chart types.
The following method is available within all appropriate layout objects:
-
$refresh() — Re-renders the HTML for the layout object.
This helper plugin does not include any utility methods other than those inherited from %ZEN.Mojo.Plugin.baseHelperPluginOpens in a new tab.
This plugin does not provide direct access to Highcharts library functions.
See “Implementing onselect() for Highcharts Events” later in this chapter.
Highcharts Helper Layout Objects
The $chart layout object displays a chart specified by type ($barchart by default). The Highcharts helper plugin also provides layout objects for the individual chart types in the following list. This list is intended as a quick reference to the layout options offered by the Highcharts helper plugin. For complete reference information, use the Plugin Documentation app (see “Using the Plugin Documentation and Widget Reference Apps”).
| $areachart | $boxplotchart | $errorbarchart | $piechart | $splinechart |
| $arearangechart | $bubblechart | $funnelchart | $pyramidchart | $waterfallchart |
| $areasplinechart | $chart | $gaugechart | $scatterchart | |
| $areasplinerangechart | $columnchart | $heatmapchart | $serieschart | |
| $barchart | $columnrangechart | $linechart | $solidgaugechart |
If both the Highcharts helper and the Chart.js 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 Highcharts, just list it before Chart.js in pageContents. See “Detecting and Resolving Plugin Conflicts” for more information.
Implementing onselect() for Highcharts Events
Every HighCharts layout object is assigned default event handlers for click events. You can change these defaults by implementing an override of the contentTemplate.onselect() method to handle the event (see “Event Handling” in Using Zen Mojo).
When a chart layout object is clicked, 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 default value argument passed to onselect() varies according to where the layout object was clicked:
-
If a point in the chart was clicked, value has the properties seriesIndex and dataIndex, which contain the indexes of the series and data points, respectively.
To override this behavior, define the options.plotOptions.series.point.events property of the layout object (see https://api.highcharts.com/highcharts#plotOptions.series.point.events.clickOpens in a new tab for option details).
-
If the chart background was clicked (rather than a point on the chart), value has the properties chartX and chartY, which contain the X and Y position of the clicked spot.
To override this behavior, define the options.chart.events.click property of the layout object (see https://api.highcharts.com/highcharts#chart.events.clickOpens in a new tab for option details).
The Highcharts code in the Widget Reference contains working examples of these event overrides.
Using Highcharts Plugin Sample Code
The Widget Reference offers interactive widget samples for the Highcharts helper. The reference includes working examples, detailed descriptions, and source code that you can cut and paste into your own applications.
