User Guide

Installation

First things first, you'll need to download the GWT Highcharts release jar file, and add it to your project's class path. E.g.:

You'll also need to add the JS files for either the Highcharts or Highstock library to your project. Note that the Highstock library includes all of the capabilities of the Highcharts library. So if your page will include a mix of both regular charts and stock charts, you can safely include just the Highstock library. We include the version of those libraries that we tested the GWT Highcharts release against on our download page, but if a more recent version has been released on the Highcharts.com site it should work fine as well.

In addition to the Highcharts or Highstock JS library, you also need to include your choice of a JS framework in the page. If you're comfortable with jQuery, that's the easiest, as the necessary adapters for jQuery are built right into the core Highcharts JS file. However, if jQuery isn't your cup of tea, Highcharts also supports several alternative options by including an additional adapter JS file in your page (see these docs for more details).

Therefore, if you're using jQuery, a typical setup for including support for Highcharts in your page would look something like the following:

Or, if you're going to be rendering stock charts in additional to regular charts, you'd instead do something like the following:

Finally, before you begin using the API within your project you'll need to update your GWT module XML configuration file to import the GWT Highcharts module. E.g.:

Themes and the Export Module

Highcharts supports theming for styling the charts to match a desired color scheme. By default the charts will be rendered with a generic style, but you can change the theme by simply including a theme file from the Highcharts distribution in your page (or, copy one of the standard themes to create your own style):

Highcharts also supports the ability to automatically enable buttons on each chart that will allow a user to print or export the chart to a PNG, JPEG, PDF, or SVG image. By default the exporting module is disabled, but you can enable it by simply including the module in your page.

Note that if you do include this module in your page all charts will have the export buttons enabled by default. You can then disable the export buttons on an individual chart as desired through its configuration.

Special Extensions

As of Highcharts version 2.3.0 some features are only available if you include the "highcharts-more.js" library in your page as well. Where this is necessary it is indicated in the GWT Highcharts API documentation, but essentially if you're making using of any of the "range" chart types (e.g. column range, area range, or area spline range) or any of the "polar" rendering options you'll need to include that additional file in your page as well. E.g.

Note that that same file can be used if you're using either the Highcharts or Highstock library.

The Chart Widgets

If you check out the API documentation you'll notice the "org.moxieapps.gwt.highcharts.client" package is the core package of the library, and it contains two classes that extend the standard GWT "Widget" class, specifically the "Chart" and "StockChart" classes. If you're using the Highstock library you have the option of using the "StockChart" widget, otherwise the "Chart" widget is all you'll need. Because both of those types are standard GWT widgets, they can simply be created and added to any GWT layout container, just like any other GWT widget works. E.g., here's an example of setting up a chart as the root widget of your GWT panel:

Or, add a chart to any other GWT layout container, such as a HorizontalPanel:

If you're using a GWT widget library, you can also add a chart directly to any of their layout containers. E.g., in SmartGWT, here's how you would add a chart as the first component in a vertical layout:

Chart Configuration

GWT Highcharts provides fully qualified methods for every configuration option that the core Highcharts JS library supports. So, if you're already familiar with the Highcharts reference documentation, you should find equivalent setter methods for each option in the GWT Highcharts API documentation. These fully qualified method names become especially useful when you're using a Java IDE which offers code completion.

A goal of the GWT Highcharts library is to try and keep the syntax for creating charts as tight and clean as possible, and therefore one key strategy used throughout the API is the idea of method chaining. So, instead of doing this:

The power of the method chaining becomes even more obvious when setting up sub type configurations on the chart, as it cuts back dramatically on the number of objects that need to be declared separately. E.g. the following is how you'd configure a chart and its legend, all behind one semi-colon:

Adding a Data Series

Each chart instance can support multiple data series added to it. By default each series added takes on the default rendering style of the chart (set via the "Chart.setType()" method), but it's possible to fix multiple rendering styles in the same chart by setting each series to its own type (via the "Series.setType()") method. Internally, a series is connected to the chart that it is associated with, so a series can only be added to same chart instance that created it.

So, to add a series to a chart you first need to create the series from the Chart instance that it will be a part of. You can then configure the series, and finally add it to the chart. E.g.:

The previous example showed a simple data series where only one axis of each point was specified. You can also set both the X and Y values of each point with syntax like the following:

Or, each point of a series can also have its own configuration options, such as changing the color of one point:

Aspects of a series can also be changed after it is rendered, most notable of which is the ability to update the data of the series. So, either based on user behavior or additional data you're receiving asynchronously, you can simply interact with the "Series" instance you created as needed. E.g. the following shows updating the data of series every second via a GWT timer:

Note that the three optional boolean parameters that the "addPoint" method supports control the way the chart will animate the change of the point being added to the series. See the API docs on the "Series" class for more details on controlling the animations.

Managing an Axis

The axis of the chart are configured by utilizing the "getXAxis()" and "getYAxis()" methods of the Chart to retrieve a reference to the axis that you're interested in managing, and then calling various setter methods on the returned XAxis or YAxis instance. E.g. the following shows how to configure some details of the X axis of the chart:

In the case that your chart needs to support multiple axis, you can invoke the "getXAxis(int axisIndex)" or "getYAxis(int axisIndex)" method instead. Each series added to the chart can then specify which axis it should be associated with. E.g. the following creates chart with two series that are both attached to a separate Y axis:

By default an axis is treated as-if the data in the series should be plotted linearly. You can instead specify that the data should be plotted as time based series, and optionally customize the format of how the date and time strings will be formatted:

Controlling Chart Components

The API includes a collection of objects that you can use to control aspects of the chart. You'll want to checkout out the showcase application and use the "View Source" button to get a feel for the kinds of configurations available, and certainly the API documentation provides the best detail. But, here are a couple of examples to give you a general idea.

Controlling the display of the chart legend:

Or, to set a couple of plot bands on an axis:

Series Plot Options

Every series type (area, line, pie, bar, etc.) supports a large collection of options that control the way the series will be rendered. These are called the "plot options" of the series, and the default plot options for each type can be set directly on the Chart instance using the corresponding setter method. E.g. to set the default plot options for all area spline series, you could do the following:

You can also then control or override the plot options on an individual series:

Custom Formatters

There are several aspects of the chart that allow you to customize the way the raw data of the chart will be textually displayed by providing a "formatter". The text that appears in tool tips, the legend area, and along the axis are three good examples of this. For example, the following code would override the default tool tip format to display the name of the series the user was hovering over, along with some details of the X and Y value of the data point:

Responding to Events

Highcharts generates various events as the user is interacting with the chart, and the GWT Highchart's library provides convenient event handler interfaces that you can use to respond to those events in your GWT code. E.g., the following code shows how you could respond to events on the plot area of the chart in order to add a point in the series at each point the user clicks on:

Or, the following is an example that shows retrieving the range of data that a user has selected on the chart:

Equivalent mechanisms can be used to respond to events that occur on a series via the methods on the SeriesPlotOptions class such as setSeriesClickEventHandler(), setSeriesMouseOverEventHandler(), setSeriesLegendItemClickHandler(), etc. In addition, similar methods are available for responding to events on the individual points of a series, such as setPointClickEventHandler(), setPointSelectEventHandler(), etc. E.g. the following code shows how you might respond to point click events:

See the API for the SeriesPlotOptions class for more details on the event handlers available for series and the points within each series.

Manual Configuration

As described in the previous "Chart Configuration" section, you are encouraged to use the fully qualified method names when setting configuration options on the chart and its various components. If you run into a situation where you believe some option is missing, try posting a question on the forums. If it turns out it really is missing someone will likely be able to get it fixed relatively quickly! However, you also have the option to set the options manually on the chart (or any of its components) via the "setOption(String, Object)" method, which is used extensively internally within the API. For example, this code:

Could be equivalently written with this code:

Which would result in initializing Highcharts like the following:

See the JavaDoc for the "Configurable" base class for more details on this approach, as well as the core Highcharts reference documentation for details on the specific options available.

Where to Go From Here

The best place to go next is to checkout the various code examples in the showcase application. You can browse through the dozens of example charts using the menu on the left, and then click the "View Source" button to see the GWT Java code behind each. We also hope you'll find the API documentation to be useful, as quite a bit of effort has gone into ensuring the JavaDoc is thorough and useful. If you're still stuck though, the best place to go is to run a search or post a question on the forums.