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:
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 as addAxis()
, addSeries()
, destroy()
, and getSVG()
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 the Chart
class, 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 including getExtremes()
to get extreme values on the axis, addPlotBand()
to add a plot band, and setCategories()
to set categories after the chart has been rendered. The chart
property can be used to refer back to the parent chart object. More information can be found at http://api.highcharts.com/highcharts#Axis.Series
: The Serie
s class is responsible for managing data points inside a particular series. The data
array contains all data point objects that are specific to this series. This class includes methods such as addPoint()
to add a data point after the render time as well as the hide()
and show()
methods to hide and show the series, respectively. It also has a chart
property to refer back to the parent chart object. You can find more about Series
at http://api.highcharts.com/highcharts#Series.Point
: The Point
class represents a single data point. Its property list includes x
and y
properties representing its values on each of the axes. The series
property is used to refer back to the parent series object. The documentation about Point
object 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.
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.