Video walk-through of a customised Bar chart

`

Video transcript

Here's the transcript of the video that you can see above. It takes you through the bar-balearic-population.html demo page.

In this video, I'm going to explain how the bar-population-balearic.html demo is created and the configuration that's required to generate it. It's mostly standard RGraph configuration though there's a custom mousemove event listener to customise the behaviour of the tooltips.

To start with there are four RGraph library files included in the page - the core library, the dynamic library, the tooltips library and of course the Bar chart library. Then we have the HTML that's needed for the chart. This consists of the canvas tag - which is pretty normal - wrapped inside a container DIV tag.

The Bar chart RGraph object is created in the standard way, with the data being four simple numbers, representing the populations of each of the Balearic islands. The data is hard-coded but could easily be separated out into a JavaScript variable the source of which could be the result of an AJAX call or generated by a server-side script (for example ASP or PHP).

Then we come on to the configuration of the chart. The first thing that's done is two of the margin sizes are set. The margininner is increased from the default value which spaces the bars out and the marginleft setting is set to 100 pixels in order to accommodate the Y-axis labels and the Y-axis title.

Then, there's the axes configuration. The X-axis tickmarks are turned off, the X-axis labels are set, the Y-axis is turned off and the Y-axis title is set and made to be bold. Even though the Y-axis is turned off the Y-axis labels and the title are still shown - only the axis itself and its tickmarks are not drawn.

The default size of the text on the chart is set to 10 points - slightly smaller than the default value of 12 and the color of the bars is set to blue. There's only one color given in the colors property which is used for all of the bars. Multiple colors are used when a stacked or grouped chart is being shown - in that case the colors are then used on a per-group (or per-stack) basis. This behaviour, though, can be changed by setting the colorsSequential option to true - and then the colors are used one after the other for each bar on the chart.

Then there's the configuration settings of the tooltips. They've been customised to look quite different from the default and the mousemove event, which we'll get to in a second, changes their behaviour when they're being displayed as well.

To start with, the tooltips are defined by using an RGraph template string which contains a couple of macros that allow you to easily show various bits of data from the chart. In this case the property macro retrieves the relevant label from the xaxisLabels property and the value_formatted macro allows you to show the value, but in a formatted way so it has appropriate commas and decimals. In between the macros, there are some HTML tags which format the tooltips (remember - the tooltips are just DIV tags so they can contain a wide variety of HTML).

Then there's some CSS values that get applied to the tooltips when they're shown. These change the background and foreground colors, set the border-radius of the tooltip (the rounding of the corners), set the text of the tooltip to be bold, set the padding of the tooltip, set the border style and color and turn pointer events off. This last one is important to ensure that the tooltip always follows the mouse pointer when its moved and doesn't stop when the pointer goes over the tooltip (because with the setting enabled - the tooltip DIV acts like it's "see-through").

Then we have some more configuration properties that control how the tooltips appear. The small tooltips pointer is turned off, the event that triggers the tooltips to be shown is set to mousemove, the tooltipsPositionStatic property is set to false (so the tooltips are not always positioned above the bars), the tooltipsEffect property is set to false to disable the small fade-in effect and the tooltipsHotspotXOnly property is set to true so that only the horizontal position of the mouse is taken into account for the triggering of the tooltips.

Then there are a few properties that configure the background grid. These simply turn off the vertical grid-lines and the border so you're just left with the horizontal background grid lines.

The final part of the chart configuration is the addition of the labels that sit on top of the bars by using the labelsAbove properties. There are a few configuration properties here which are all pretty self-explanatory. Firstly, the labelsAbove are enabled, their distance from the bars is increased slightly, the font size is set and they're set to be bold.

That's all of the configuration properties that are used, but it's not the end of the code. By default, the behaviour of the tooltips is for them to be static once they're displayed. Normally, with the tooltips positioned at the top of the bars this is fine. But for this chart we want them to follow the pointer as it moves around so a custom mousemove event-listener has to be added. Since it's not critical for the display of the chart it can be added after the call to the draw function.

The mousemove event of the canvas tag itself is used to add the event listener - not the mousemove event with the RGraph on() function. This means that the event is run whenever the mouse is moved over any part of the canvas tag - not just the bars which are drawn by the bar chart.

The first thing that the event listener does is retrieve the tooltip DIV element from the RGraph registry. If there's no tooltip currently being shown then this will be null and the test of this value on the next line will fail and the code that sits inside the if condition will not be run.

The mouse coordinates are then retrieved using the RGraph.getMouseXY() API function. These coordinates are in relation to the canvas tag - so the [0,0] coordinate is in the top left corner of the canvas tag - mimicking the coordinate system of the canvas.

The coordinates of the canvas tag are then retrieved using the RGraph.getCanvasXY() function. These coordinates are in relation to the whole page - so the [0,0] coordinate in this case is in the top left corner of the page.

These values are then used to position the tooltip by setting the CSS top and left properties of the tooltip DIV tag. The tooltip height is subtracted from the Y-coordinate so that the tooltip sits above the pointer and half of the tooltip width is subtracted from the X-coordinate so that it's horizontally centered on the pointer.

The last bit of code uses an RGraph API function to get the relevant chart object based on the position of the mouse pointer. If the pointer is over the margins of the chart it doesn't count. In this case, there's only one chart being drawn - the bar chart - so if the pointer is not over it then any tooltip that might be being shown at that point is hidden and the chart is redrawn to change the highlighted bar color back to normal.

And that's all there is to this Bar chart. It shows you that RGraph charts can be customized quite easily if need be. If you have a question about anything that you've seen here or about any of the options simply add a message to the RGraph support forum and I'll get back to you with an answer.

See you in the next video!