Mention RGraph on Twitter

RGraph: HTML5 Javascript charts 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 chart type there are a few files required - the common libraries and the chart 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 chart 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 chart libraries (RGraph.*.js) contains that particular charts 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 chart types.

Canvas and context references

Each chart 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 chart 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 chart coordinates

For most chart 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 differently - by line index.

Working with chart data

Another variable you may need is the data variable. For most chart types, this is where the data is stored. It is usually untouched, so it is as you supplied to the chart 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 chart types use the data variable. For some the name is different so that it makes a little more sense. The chart types and their associate data variables are listed below1.

Chart type Data variable(s)
Bar obj.data
Bi-polar obj.left, obj.right
Donut This is now a variant of the Pie chart
Fuel obj.min, obj.max, obj.value
Funnel obj.data
Gantt See the docs
Gauge obj.min, obj.max, obj.value
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
Thermometer obj.min, obj.max, obj.value
Traditional Radar obj.data, obj.max
Vertical Progress bar obj.max, obj.value
Waterfall chart obj.max, obj.data
  1. In the table, obj refers to your chart 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 charts 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 charts 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 chart 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 chart 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 charts not working entirely as expected. 

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

 

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 or look at the source.

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 charts

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

<script>
    // Draw a basic chart
    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 charts. You may still wish to use them however.

The skeleton file

The skeleton object (RGraph.skeleton.js) gives you a base for creating new chart 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>