Share: Bookmark with delicious tweet this site Post to Facebook

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 a few files required - the common libraries and the graph specific library. Eg: 

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

RGraph.common.core.js is a function library that contains a large set of functions that support the graph classes. Some functions, and sets of functions, have their own files. For example, the zoom functions reside in RGraph.common.zoom.js, so if you don't need zoom, you don't need this file. 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. There's also a skeleton example to make it easier to create new graph types.

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 it like this: 

<script>
    document.getElementById("myCanvas").onclick = function (e)
    {
        var src = (RGraph.isIE8() ? 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: Previously the coords array values sometimes included the margin values, and sometimes didn't. As of 17th April 2010 the values have all been unified to not include the margin values, so the values are as reported.

Note: The Line chart also has an object variable myObj.coords2, where the coordinates are indexed differerently - by line index.

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 filled 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 associate data variables are listed below1.

Graph type Data variable(s)
Bar obj.data
Bi-polar obj.left, obj.right
Donut This is now a variant of the Pie chart
Funnel obj.data
Gantt See the docs
Horizontal Bar obj.data
Horizontal Progress bar obj.max, obj.value
LED obj.text
Line obj.original_data3
Meter obj.min, obj.max, obj.value
Odometer obj.start, obj.end, obj.value
Pie obj.angles, obj.data
Radial Scatter chart obj.data
Rose obj.max, obj.data
Scatter obj.max, obj.data2
Scatter obj.min, obj.max, obj.value
Thermometer obj.min, obj.max, obj.value
Traditional Radar obj.data, obj.max
Vertical Progress bar obj.max, obj.value
  1. In the table, obj refers to your graph object.
  2. For the Scatter chart, each data point is an array of X/Y coordinates, the color and the tooltip for that point.
  3. The Line chart obj.original_data is an aggregation of all the datasets given to the Line chart, so the first dataset is held in obj.original_data[0], the second in obj.original_data[1] etc.

Updating your graphs dynamically

Note: It is important that you're careful with types when making AJAX requests. Since the response is initially a string, and your AJAX function/library may not do conversions for you, you may need to convert these strings to numbers. To do this you can use the Number() or parseInt() functions. For example: 

<script>
    num = Number('23');
    num = parseInt('43');
</script>

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. Also, it may be sufficient to simply recreate the entire object from scratch. This means that you won't have to alter and RGraph internal properties - just recreate the graph object and configuration. There's a simple function you can use for AJAX purposes here.

Setting properties

To set RGraph properties, ideally you should use each objects setter (there's also a corresponding getter). These functions accomodate some backwards compatibility changes, so by not using them you run the risk of your graphs not working entirely as expected. 

myObj.Set('chart.gutter', 25);
myObj.Get('chart.gutter');

 

References available on RGraph objects

RGraph stores various references to objects on the canvas (typically) to make getting hold of them easier. There's also a Registry object in which references are stored. Typically the objects are named with the format __xxx__, and you can inspect the objects by using a console(eg the inspector that's part of Google Chrome - CTRL+SHIFT+J). Some examples are:

These are just a sample of what's available, to find more you should use an introspection tool, look at the source, or ask on the support mailing list.

Scale information

For the Bar, Bipolar, HBar, Line and Scatter charts the scale that is used is stored in the scale class variable. Eg: 

<script>
    var myBar = new RGraph.Bar('cvs', [56,43,52,54,51,38,46,42,52]);
    myBar.Draw();
    
    var myScale = myBar.scale
</script>

Adding text to your graphs

If you want to add arbitrary text to your graph(s) you can use the API function RGraph.Text(). 

<script>
    // Draw a basic graph
    var myObj = new RGraph.Bar('myCanvas', [4,5,5,8,7,6,4,8,5,9]);
    myObj.Draw();
    
    // Draw some text
    myObj.context.beginPath();
        size = 12;
        font = 'Verdana';
        text = 'Some text!;
        x    = 10;
        y    = 10;

        RGraph.Text(myObj.context, font, size, x, y, text);
    myObj.context.fill();
</script>

RGraph functions

This is a list of some of the functions available to you in the RGraph common libraries. 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.core.js"></script>

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

Arrays

Strings

Numbers

Miscellaneous

Custom RGraph event related functions

Other

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

The skeleton file

The skeleton object (RGraph.skeleton.js) gives you a base for creating new graph types that match the RGraph object system (eg getters, setters, RGraph names etc). Example usage of the skeleton object would be: 

<script>
    var myObj = new RGraph.Skeleton('cvs', [3,3,4,5,3,8,3,2,1,9]);
    myObj.Set('chart.colors', ['red']);
    myObj.Draw();

    var colors = myObj.Get('chart.colors');
</script>

Questions

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