User Guide

Go deep. Here's the whole story.

Table of Contents:

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

lib/org.moxieapps.gwt.highcharts-1.7.0.jar

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:

<script type="text/javascript"
   src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js">
</script>
<script type="text/javascript" src="js/highcharts.js"></script>

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

<script type="text/javascript"
   src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js">
</script>
<script type="text/javascript" src="js/highstock.js"></script>

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

<inherits name="org.moxieapps.gwt.highcharts.Highcharts"/>

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

<script type="text/javascript" src="js/themes/dark-blue.js"></script>

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.

<script type="text/javascript" src="js/modules/exporting.js"></script>

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.

<script type="text/javascript" src="js/highcharts-more.js"></script>

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:

Chart chart = new Chart();
RootPanel.get().add(chart);

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

Chart chart = new Chart();
HorizontalPanel panel = new HorizontalPanel();
panel.add(chart);

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 chart = new Chart();
VLayout layout = new VLayout();
layout.addMember(chart);

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:

Chart chart = new Chart();
chart.setType(Series.Type.SPLINE);
chart.setChartTitleText("Lawn Tunnels");
chart.setMarginRight(10);
You can instead do this:
Chart chart = new Chart()
   .setType(Series.Type.SPLINE)
   .setChartTitleText("Lawn Tunnels")
   .setMarginRight(10);

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:

Chart chart = new Chart()
   .setType(Series.Type.AREA)
   .setChartTitleText("Dead Grass Surface Area")
   .setLegend(new Legend()
      .setAlign(Legend.Align.RIGHT)
      .setBackgroundColor("#CCCCCC")
      .setShadow(true)
   );

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

Series series = chart.createSeries()
   .setName("Moles per Yard")
   .setPoints(new Number[] { 163, 203, 276, 408, 547, 729, 628 });
chart.addSeries(series);

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:

Series series = chart.createSeries()
   .setName("Moles per Yard per Day")
   .setPoints(new Number[][] {
      {163, 45}, {203, 33}, {276, 50}, {408, 13}, {547, 63}, {729, 48}
   });
chart.addSeries(series);

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

Series series = chart.createSeries()
   .setName("Common Mole Nicknames")
   .setPoints(new Point[] {
      new Point("Digger", 45.0).setColor("#4572A7"),
      new Point("Greedy", 26.8).setColor("#AA4643"),
      new Point("Torpedo", 12.8).setColor("#89A54E")
   });
chart.addSeries(series);

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:

Timer timer = new Timer() {
   public void run() {
      series.addPoint(
         com.google.gwt.user.client.Random.nextDouble(),
         true, true, true
      );
   }
};
timer.scheduleRepeating(1000);

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:

chart.getXAxis()
   .setCategories(
      "1750", "1800", "1850", "1900", "1950", "1999", "2010"
   )
   .setTickmarkPlacement(XAxis.TickmarkPlacement.ON)
   .setAxisTitleText("Mole Birth Year");

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:

chart.getYAxis(0)
   .setAxisTitleText("Mole Sightings");
chart.getYAxis(1)
   .setAxisTitleText("Grub Sightings")
   .setOpposite(true);
chart.addSeries(chart.createSeries()
   .setYAxis(0)
   .setPoints(new Number[] {
      49, 71, 106, 129, 144, 176, 135, 148, 216, 194, 95, 54
   })
);
chart.addSeries(chart.createSeries()
   .setYAxis(1)
   .setPoints(new Number[] {
      1016, 1016, 1015, 1015, 1012, 1009, 1009, 1010, 1013, 1016, 1018, 1016
   })
);

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:

chart.getXAxis()
   .setType(Axis.Type.DATE_TIME)
   .setDateTimeLabelFormats(new DateTimeLabelFormats()
      .setMonth("%e. %b")
      .setYear("%b")
   );

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:

Chart chart = new Chart()
   .setLegend(new Legend()
      .setLayout(Legend.Layout.VERTICAL)
      .setAlign(Legend.Align.RIGHT)
      .setVerticalAlign(Legend.VerticalAlign.TOP)
      .setX(-10)
      .setY(100)
      .setBorderWidth(0)
   );

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

Chart chart = new Chart();
YAxis axis = chart.getYAxis();
axis.setPlotBands(
   axis.createPlotBand()
      .setFrom(0.3)
      .setTo(1.5)
      .setColor(new Color(68, 170, 213, 0.1))
      .setLabel(new PlotBandLabel()
         .setText("Nice Critters")
         .setStyle(new Style()
            .setColor("#606060")
         )
      ),
   axis.createPlotBand()
      .setFrom(1.5)
      .setTo(3.3)
      .setColor(new Color(200, 50, 50, 0.2))
      .setLabel(new PlotBandLabel()
         .setText("Ugly Critters")
         .setStyle(new Style()
            .setColor("#606060")
         )
      )
);

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:

Chart chart = new Chart()
   .setAreaSplinePlotOptions(new AreaSplinePlotOptions()
      .setFillOpacity(0.5)
      .setFillColor("#CC0000")
   );

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

chart.addSeries(chart.createSeries()
   .setPlotOptions(new AreaSplinePlotOptions()
      .setFillColor("#000099")
   )
);

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:

Chart chart = new Chart()
   .setToolTip(new ToolTip()
   .setFormatter(new ToolTipFormatter() {
      public String format(ToolTipData toolTipData) {
         return "<b>" + toolTipData.getSeriesName() + "</b><br/>" +
            toolTipData.getXAsString() + ": " + toolTipData.getYAsDouble() + " cm";
      }
   })
);

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:

Chart chart = new Chart();
Series series = chart.createSeries()
   .setPoints(new Number[][]{{20, 20}, {80, 80}});
chart.addSeries(series);
chart.setClickEventHandler(new ChartClickEventHandler() {
   public boolean onClick(ChartClickEvent clickEvent) {
      series.addPoint(clickEvent.getXAxisValue(), clickEvent.getYAxisValue());
      return true;
   }
});

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

Chart chart = new Chart()
   .setZoomType(Chart.ZoomType.X);
chart.setSelectionEventHandler(new ChartSelectionEventHandler() {
   public boolean onSelection(ChartSelectionEvent e) {
      Window.alert("Selected " + e.getXAxisMin() + " to " + e.getXAxisMax());
      return true;
   }
});

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:

Chart chart = new Chart()
   .setSeriesPlotOptions(new SeriesPlotOptions()
      .setPointClickEventHandler(new PointClickEventHandler() {
         public boolean onClick(PointClickEvent e) {
            Window.alert("Clicked " + e.getXAsLong());
            return true;
         }
      })
   );

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:

Chart chart = new Chart()
   .setType(Series.Type.SPLINE)
   .setChartTitleText("Lawn Tunnels")
   .setMarginRight(10);

Could be equivalently written with this code:

Chart chart = new Chart()
   .setOption("/chart/type", "spline")
   .setOption("/title/text", "Lawn Tunnels")
   .setOption("/chart/marginRight", 10);

Which would result in initializing Highcharts like the following:

new HighCharts.Chart({
   chart: {
      type: "spline",
      marginRight: 10
   },
   title: {
      text: "Lawn Tunnels"
   }
});

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.

GWT charting visualizations.
See what it can do.
Get the library or source.
The one pager.
It's free, but check this.
Learn how to use it.
The nitty gritty.
Suggest an idea, get answers.
Show your support by making a donation!