Highcharts offers a small set of APIs designed for plotting charts with dynamic interactions. In order to understand how the APIs work, we must first familiarize ourselves with the chart's internal objects and how they are organized inside a chart. In this chapter, we will learn about the chart class model and how to call the APIs by referencing the objects. Then we build a simple stock price application with PHP, jQuery, and jQuery UI to demonstrate the use of Highcharts APIs. After that, we turn our attention to four different ways of updating a series. We experiment with all the series update methods with the purpose of building an application to illustrate variations in visual effects, and the difference in CPU performance between them. Finally, we investigate performance when updating a series with popular web browsers, in terms of different sizes of datasets. In this chapter, we will cover the following topics:
Chart.addSeries
Chart.getSVG
to format SVG data into an image fileChart.renderer
methodsThe relationship between Highcharts classes is very simple and obvious. A chart is composed of five different classes—Chart
, Axis
, Series
, Point
, and Renderer
. Some of these classes contain an array of lower-level components and an object property to back-reference to a higher level-owner component. For example, the Point
class has the series
property pointing back to the owner Series
class. Each class also has a set of methods for managing and displaying its own layer. In this chapter, we will focus on the set of APIs for dynamically modifying charts. The following class diagram describes the association between these classes:
The Chart
class is the top level class representing the whole chart object. It contains method calls to operate the chart as a whole—for example, exporting the chart into SVG or other image formats and setting the dimension of the chart. The Chart
class has multiple arrays of Axis
and Series
objects; that is, a chart can have one or more x axes, y axes, and series. The Renderer
class is a utility class that has a one-to-one relationship per chart and provides a common interface for drawing in SVG and VML-based browsers.
The Series
class has an array of Point
objects. The class has back-reference properties towards the Chart
and Axis
objects (see the dotted lines in the previous diagram) and provides functions for managing its list of Point
objects. The yAxis
and xAxis
properties in the Series
class are necessary, as a chart can have multiple axes.
The Point
class is just a simple object containing x and y values and a back-reference to its series object (see the dotted line). The APIs are for managing the data points in the chart.
Needless to say, the most important method in the APIs is the Highcharts.Chart
method, with which we have seen plenty of action so far. However, there is more to this constructor call. Highcarts.Chart
creates and returns a chart object but it also has a second optional parameter known as callback
:
Chart(Object options, [ Function callback ])
The callback function is called when a chart is created and rendered. Inside the function, we can either call the component methods or access the properties inside the chart object. The newly created chart object is passed via the only callback function parameter. We can also use the 'this
' keyword inside the callback function, which also refers to the chart object. Instead of using the Highcharts.Chart
callback parameter, we can achieve the same result by declaring our code inside the chart.events.load
handler, which will be explored in the next chapter.
In order to use the Highcharts API, we must navigate to the right object inside the class hierarchy. There are several ways to traverse within the chart object: through the chart hierarchy model, retrieving the component directly with the Chart.get
method, or a mixture of both.
Suppose that the chart object is created, as follows:
<script type="text/javascript"> $(document).ready(function() { var chart = new Highcharts.Chart({ chart: { renderTo: "container" }, yAxis: [{ min: 10, max: 30 }, { min: 40, max: 60 }], series: [{ data: [ 10, 20 ] }, { data: [ 50, 70 ], yAxis: 1 }], subtitle: { text: "Experiment Highcharts APIs" } }); }, function() { ... }); </script>
We can then access the first position of the series' object with the index 0 from the chart. Inside the callback handler, we use the this
keyword to refer to the chart object as follows:
var series = this.series[0];
Suppose there are two y axes in the configuration. To retrieve the second y axis, we can do as follows:
var yAxis = this.yAxis[1];
To retrieve the third data point object from the second series of the chart, type the following:
var point = this.series[1].data[2];
Supposing multiple charts are created on the page, a chart object can be accessed via the Highcharts namespace:
var chart = Highcharts.charts[0];
We can also retrieve the chart's container element through the container option:
var container = chart.container;
To examine the options structure of a created chart, use the options property:
// Get the chart subtitle var subtitle = chart.options.subtitle.text;
Instead of cascading down the object hierarchy, we can directly retrieve the component using the Chart.get
method (the get
method is only available at the chart level, not in each component class). Assigning components with IDs will allow you to access them directly using the get
method instead of traversing nodes in the object's hierarchical structure. The configuration uses the option key id
, so this value must be unique.
Suppose we have created a chart with the following configuration code:
xAxis: { id: 'xAxis', categories: [ ... ] }, series: [{ name: 'UK', id: 'uk', data: [ 4351, 4190, { y: 4028, id: 'thirdPoint' }, ... ] }]
We can retrieve the components as follows:
var series = this.get('uk'), var point = this.get('thirdPoint'), var xAxis = this.get('xAxis'),
If the id
option is not previously configured, we can use the JavaScript filter
method to search for the item based on the property:
this.series.filter(function(elt) {return elt.name == 'uk';})[0];
18.225.149.238