Skip to main content
Previous section   Next section

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

Adding Highcharts to the Page Class

Adding Required Highcharts Files

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.zip and jQuery at https://code.jquery.com/jquery/.

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.

Registering the Highcharts 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:highCharts-4.0.4-Helper/>
  </mojo:mojoDefaultPageManager>
Copy code to clipboard

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

Other Options and Requirements

For more information on this plugin, see %ZEN.Mojo.Plugin.highCharts404Helper in the class reference.

Note:
Support for Highcharts version 4.0.1

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/>
Copy code to clipboard

Using Highcharts in a Template Class

Highcharts Layout Objects

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.

Custom Highcharts Layout Object Methods

The following method is available within all appropriate layout objects:

  • $refresh() — Re-renders the HTML for the layout object.

Highcharts Helper Plugin Methods

This helper plugin does not include any utility methods other than those inherited from %ZEN.Mojo.Plugin.baseHelperPlugin.

Direct Access to the Highcharts Library

This plugin does not provide direct access to Highcharts library functions.

Event Handling

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 http://api.highcharts.com/highcharts#plotOptions.series.point.events.click 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 http://api.highcharts.com/highcharts#chart.events.click 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.