Bookmark and share:
Bookmark with delicious tweet this site Post to Google Buzz! Post to Facebook Share on FriendFeed Stumble! this site

RGraph: HTML5 canvas graph library - Miscellaneous documentation


Canvas fallback content and visually impaired users

When using the canvas element you should be aware of the accessibility of your graphs, for example where vision limited users are concerned. Screen readers, for example, may not be able to convert a graph into something that is reasonable, so you should consider doing this yourself, possibly using the canvas fallback content (ie the content in between canvas tags). A possible example would be to put a table of data inside the canvas tag that the graph on the canvas represents. Doing this goes a long way towards making the data available to everyone. You might also wish to consider using the full canvas zoom or the resizing feature to enable people to enlarge the graph.


Upper and lower limits for horizontal bars

If you don't wish to specify an upper or lower limit for horizontal bars, and you just want them to extend to the upper or lower limits of the graph, whatever they may be, you can specify null for the value determining how far they extend. For cases where the X axis is in the middle and you're specifying a negative start value, or you want the bar to extend all the way to the bottom, you can simply specify an arbitrary length (eg -999999). Eg:

myBar.Set('chart.background.hbars', [[0, null, 'green'], [0,-999999,'red']]);


Setting the canvas width and height

To set the canvas width and height you must use the HTML width/height attributes and NOT CSS. If you do use CSS, the canvas will be scaled, and not enlarged, to fit the new width/height. Eg:

<canvas id="myCanvas" width="200" height="100">[No canvas support]<canvas>


RGraph and older browsers

Older versions of browsers are supported (assuming they have canvas support), however, if they don't support the canvas text or shadow APIs these will naturally be unavailable. The graphs will still be drawn, though without shadows or text.


RGraph and Microsoft Internet Explorer

You can now use RGraph with Internet Explorer 8 in conjunction with ExCanvas, (which brings a degree of <canvas> support to MSIE). Bear in mind though that shadows are not available and thus are simulated. Microsoft Internet Explorer 9 has native <canvas> support. You can see some screenshots of it here.


Debugging tips

If you're having a hard time debugging your graph, try these:


Double click context menus

Windows Opera, Windows Safari, Mac Safari and Mac Firefox all attach the context menu to the double click event (left mouse button), not the right, in order to make it more reliable.


Adding your own event handlers

Because each RGraph object exposes the canvas element (the same as what you get from document.getElementById()), you can use normal procedures to add your own event handlers. Eg If you wanted to add your own onclick handler you could do this: myBar.canvas.onclick = function () {}. But what if, for example, you're using an RGraph feature which uses the event handler that you need? In this case you can use the standard DOM method addEventListener(). This will add your new event handler without replacing any existing one (ie the one installed by RGraph). For example: myBar.canvas.addEventListener('click', myFunc, false).


Carriage returns and newlines in labels

You can put carriage returns in your labels by using the string \r\n. This means your labels will span multiple lines. Like so:

myBar.Set('chart.labels', 'John\r\n(Winner!)', ...)


Why is the Traditional Radar chart so called?

Historical reasons. There used to be two Radar charts in RGraph - the TRadar and an older one called the Pseudo radar chart. The Pseudo Radar chart was converted into the Rose chart. Renaming the TRadar will only cause problems and there's no pressing reason to do so, so for the moment it remains the TRadar chart.


Character set issues

If you're seeing strange, unrecognised characters in your text labels or titles, you may need to specify the correct character set that the browser should use. In PHP you can do this with the header() function (which, as the name suggests, sends a HTTP header):

    header("Content-Type: text/html; charset=ISO-8859-1");

If you use Apache, you could use the header directive, though this may be overridden by other directives, eg AddDefaultCharset.


How to identify an RGraph object

Because identity can sometimes be a tricky affair, there are a few RGraph properties that you can use to check whether an object is an RGraph object:


Static Y axis

A static Y axis is useful if you have a wide chart but limited space. Whilst not part of the RGraph libraries itself, it can be achieved with a little HTML, like the graph shown. The HTML and the script to achieve this is documented in the source of this page. It involves placing an extra canvas above the graph with the Y axis drawn on it. This canvas doesn't move when the main canvas scrolls left and right.

Note: Because Firefox doesn't support the event.offsetX and event.offsetY properties, and they have to be simulated, scrolling and tooltips in this case and this browser doesn't work.


Reducing white space

If the labels that you have require a large gutter you can reduce the amount of wasted space by using the standard 2D context method translate(). This effectively moves the coordinate system so that (0,0) is no longer in the top left corner, but whereever you put it. For example if you translate by (15,-15), the origin will then be 15 pixels right and 15 pixels up compared to where it was.

Because the coordinate system is being changed things that rely on coordinates, eg tooltips, will be affected. For this reason there is the property chart.tooltips.coords.adjust which you can use to tell RGraph that you've translated and the tooltip coordinates will be adjusted appropriately.

// This moves the graph to the right by 15px, and up by 15px. Do this before the call to .Draw()


Shorthand for ingraph labels

Instead of providing a full array of null elements for ingraph labels which may get a little unwieldy, you can instead specify an integer that specifies how many elements to skip. Like this:

line.Set('chart.labels.ingraph', [6, 'July', 3, 'November']);


DOM2 Event handlers

Starting in August 2010, RGraph is moving towards using DOM2 event handlers. This will allow better integration with other code that uses the same event handler as the feature you want, both libraries and your own code. So far the following libraries have been converted:

The conversion process will happen gradually and is expected to take a number of months. Note that tooltips on the graph libraries that have been converted to the standard DOM2 event registration function will not be compatible with MSIE8. The graphs will still be shown, albeit without tooltips.


Gutter suggestion function

RGraph now contains a function (RGraph.getGutterSuggest()) that will provide a simple suggestion for the gutter setting. This function is based on the left gutter and labels and should be considered an approximate value.


Known issues

There's a few known issues documented here