RGraph: HTML5 canvas graph library - API documentation


Overview

Working with RGraph objects is purposefully easy, to make them straight forward to integrate into your own scripts if you want to. For any particular graph type there are only two files required - the common library and the graph specific library. Eg: 

<script src="RGraph.common.js"></script>
<script src="RGraph.bar.js"></script>

RGraph.common.js is a function library that contains a large set of functions that support the graph classes. Each of the graph libraries (RGraph.*.js) contains that particular graphs class. If you'd like to see a "bare bones" implementation, you can look at the basic example.

Canvas and context references

Each graph object maintains references to the context and canvas as properties. So to get hold of them all you need to do is this: 

<script>
    window.onload = function ()
    {
        // 1/2 First draw the chart
        var myBar = new RGraph.Bar('myCanvas', [1,5,8,4,6,3,1,5,7,8,4,6]);
        myBar.Set('chart.labels', ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']);
        myBar.Draw();
    
        // 2/2 Now get hold of the references
        var context = myBar.context; // Get hold of a reference to the context
        var canvas  = myBar.canvas;  // Get hold of a reference to the canvas
    }
</script>

Working with events

When working with events, you may come across the situation where you have a reference to the canvas, but also need to access the graph object. For this reason the constructor of each object adds a reference to the object to the canvas and you can access them like this: 

<script>
    document.getElementById("myCanvas").onclick = function (e)
    {
        var src = (document.all ? event.srcElement : e.target);
    
        // The RGraph object constructors add __object__ to the canvas.
        var myBar = src.__object__;
    }
</script>

Working with graph coordinates

For most graph types, the coordinates of elements (eg bars, lines etc) are to be found in the class variable obj.coords. This is usually a multi-dimensional array consisting of the coordinates of those shapes, or of points. As an example the bar chart maintains the X, Y, width and height of each bar (or sections of bars in a stacked bar chart). The coords array is usually a flat array, even when you have multiple sets of data.

By using the RGraph.getMouseXY() function and this array you can determine if a bar was clicked on, or if the mouse is near a line point etc. 

var myCoords = myBar.coords;

Note: For backwards compatibility reasons, the values in the coords array sometimes include the horizontal margin (chart.hmargin) and sometimes don't.

Working with graph data

Another variable you may need is the data variable. For most graph types, this is where the data is stored. It is usually untouched, so it is as you supplied to the graph objects constructor. A notable exception to this is line charts. Here the original data is stored in the class variable original_data. The data supplied is modified to produce the stacking effect. If you need to modify a filled line charts data you will need to change this variable instead.

Not all graph types use the data variable. For some the name is different so that it makes a little more sense. The graph types and their associated data variables are listed below*.

Graph type Data variable(s)
Bar obj.data
Bi-polar obj.left, obj.right
Donut obj.data, obj.pies
Funnel obj.data
Gantt See the docs
Horizontal Bar obj.data
LED obj.text
Line obj.original_data
Meter obj.min, obj.max, obj.value
Odometer obj.Get('chart.start'), obj.Get('chart.end'), obj.Get('chart.value')
Pie obj.angles, obj.data
Progress obj.Get('chart.max'), obj.Get('chart.value')
Pseudo-Radar obj.max, obj.data
Scatter obj.max, obj.data**
Traditional Radar obj.data, obj.max

* In the table, obj refers to your graph object.
** For the Scatter chart, each data point is an array of X/Y coordinates, the color and the tooltip for that point.

Updating your graphs dynamically

A common request is to be able to update graphs dynamically. This is quite simple and consists of three steps:

  1. Get the new data from the server (with an AJAX request for example).
  2. Set the data in your graph object. See the above table for the appropriate property to use.
  3. Call the .Draw() method again.

If you don't need to get data from your server (ie it's all client-side) then you can omit the first step.

RGraph functions

This is a list of some of the functions available to you in RGraph.common.js. It's not every single one that's available, but is a list of the common ones that you're likely to want to use. Arguments in square brackets are optional. 

<script src="RGraph.common.js"></script>

<script>
    // Returns 9
    myArray = [3,2,5,4,9,7,8];
    max = RGraph.array_max(myArray);
</script>

Arrays

Strings

Numbers

Miscellaneous

Other

These are functions which are less generic, and used to build the graphs. You may still wish to use them however.

Questions

If you have a question regarding the API, you can ask it on the mailing list