As developers, we often deal with scenarios where some task needs to be accomplished programmatically. When speaking about Highcharts, these scenarios can be either inserting a new series into an already initialized chart, updating an axis, or destroying a chart on a user-generated event. This is where Highcharts APIs come in handy as they provide us with methods, properties, and events to have full control over our code.
We have used some of the API features in earlier chapters such as setting a theme via the Highcharts.setOptions() method and using its properties on series to get values on x and y axes. In this chapter, we will examine Highcharts APIs more closely to arm ourselves with necessary skills that will prove useful when working with Highcharts.
However, before pressing on to Highcharts APIs and events, we shall first familiarize ourselves with the Highcharts class model as it's crucial to have a deep understanding of APIs. The class model defines how objects are structured inside a chart, thus letting us maneuver APIs by referring to these objects. And finally, we will look at ways to extend Highcharts to add extra functionality.
In this chapter, we will cover the following topics:
- Familiarizing ourselves with the Highcharts class structure
- Getting to know the essential Highcharts API methods and events
- Looking at how various tasks can be accomplished programmatically
- Learning how to extend Highcharts to add extra functionality
A Highcharts chart is composed of five different classes namely Chart, Axis, Series, Point, and Renderer. Each object contains methods to accomplish different tasks and properties that contain vital information about that object. They also contain properties to reference back to higher-level objects, thus allowing access to properties and methods of other objects.
The purpose of each class is listed as follows:
Chart: It is the top-level class that represents the chart. It contains methods, such asaddAxis(),addSeries(),destroy(), andgetSVG()to carry out operations on the chart as a whole. Within this class, there are arrays that contain objects for x axis, y axis, and series. You can find out more about theChartclass, its methods, and properties at http://api.highcharts.com/highcharts#Chart.Axis: This class represents the chart axes. It has methods to deal with axis-specific operations includinggetExtremes()to get extreme values on the axis,addPlotBand()to add a plot band, andsetCategories()to set categories after the chart has been rendered. Thechartproperty can be used to refer back to the parent chart object. More information can be found at http://api.highcharts.com/highcharts#Axis.Series: TheSeries class is responsible for managing data points inside a particular series. Thedataarray contains all data point objects that are specific to this series. This class includes methods such asaddPoint()to add a data point after the render time as well as thehide()andshow()methods to hide and show the series, respectively. It also has achartproperty to refer back to the parent chart object. You can find more aboutSeriesat http://api.highcharts.com/highcharts#Series.Point: ThePointclass represents a single data point. Its property list includesxandyproperties representing its values on each of the axes. Theseriesproperty is used to refer back to the parent series object. The documentation aboutPointobject can be found at http://api.highcharts.com/highcharts#Point.Renderer: This class does all the heavy lifting of rendering a chart using SVG or VML in legacy browsers. It has a one-to-one correspondence with each chart and contains methods to draw various shapes. It can also be accessed independently for drawing outside a chart. You can find out more about its methods and properties at http://api.highcharts.com/highcharts#Renderer.
Apart from these classes, an Element class is used in combination with the Renderer class to render SVG elements. Then, there is the Highcharts namespace, under which some API functions and variables are assembled.
As mentioned previously, each class object has properties to transverse through the object hierarchy. Consider the example from Chapter 5, Pie, Polar, and Spider Web Charts, modified to include a callback function to execute after the chart has been initialized:
(function() {
$( '#chart_container' ).highcharts({
title: {
text: 'Fuel Consumption by Type for the Year 2012'
},
subtitle: {
...
},
xAxis: {
...
},
yAxis: {
...
},
plotOptions: {
...
},
tooltip: {
...
},
series: [
...
]
}, function() {
console.log( this );
});
})();Inside the callback function, the this keyword refers to the top-level chart object. Hence, by logging the this variable we are executing the contents of the chart object:
The preceding screenshot shows the contents of the chart object logged in Chrome's Developer Tools.
Note
Developer tools provide a great deal of help when debugging web applications within the browser. Every major browser comes with its own plugins; third-party plugins, such as Firebug for Mozilla Firefox are also available. We are using Chrome's Developers Tools, about which you can find more at https://developer.chrome.com/devtools.
When inspecting the chart object with developer tools, we can access all the methods and properties right within the console. This provides us with a convenient way to play around with APIs without having the need to switch back and forth between the JavaScript (or HTML) file and the browser. To access the chart object, we first need to set it as a global variable. To do so, right-click on the top-level object and select the Store as global variable option from the context menu:
By doing so, Chrome will copy a reference to the chart object to a newly created variable in the global context and output the name of that global variable in the next line, in this case, temp1:
We can now access the properties and methods on the chart object by referring to the temp1 global variable.
The chart animation property, chart.animation, is set to true by default. We can use the newly created global variable to turn the animation off by typing the following code in the Developer Tools console:
temp1.animation = false;
We can verify the change either by toggling series by their legends or by outputting the value of the temp1.animation property, which will return false:
This is one way by which we can navigate through the Highcharts class structure. In the next section, we will look at another way through which we can obtain an axis, series, or a point of a chart.