Miscellaneous documentation

Share RGraph:   

 

Canvas fallback content and visually impaired users

When using the canvas element you should be aware of the accessibility of your charts, for example where visually impaired users are concerned. Screen readers, for example, may not be able to convert a chart into something that is reasonable, so you might want to consider doing this yourself, possibly using the canvas fallback content (ie the content in between the canvas tags). A possible example would be to put a table of data inside the canvas tag that the chart 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 zoom or the resizing features to enable people to enlarge the chart.

As of April 2016 there's also a textAccessible option that makes the text on the chart real text that can be read by screen readers. It also appears at a better quality than native canvas text.

 

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 chart, 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:

bar.set({
    backgroundHbars: [[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>

Note: When you resize the canvas using CSS, not only will it be scaled (not enlarged), but it will also NOT be cleared.

 

The canvas coordinate system

The canvas coordinate system starts in the top left of the canvas (at [0,0] - the X value increasing as you go right and the Y value as you go down), much like the CSS coordinates for the entire page. The gutter goes around the canvas (ie top/bottom/left/right - where the labels and titles are placed), and the actual chart sits in the middle.

 

Debugging tips

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

There is a HOWTO for debugging with Chrome here. It also links to a video about the Chrome dev tools from Google I/O 2010.

 

Inspecting an RGraph chart

To help when debugging your RGraph charts and canvas elements, you can use your browsers built in debugging tools. An example is the WebKit developer tools which are available in Google Chrome and Apple Safari. There is a screenshot of these tools (in docked mode) here. To view these tools in Google Chrome press CTRL+SHIFT+J. Inspect the canvas, and then the last object that you created can be found via the __object__ property.

 

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:

<script>
    var bar = new RGraph.Bar({
        id: 'cvs',
        data: [7,4,2,6,3,4,8]
    }).draw();

    bar.canvas.onclick = function ()
    {
    }
</script>

 

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:

bar.set({
    labels: 'John\r\n(Winner!)', ...
});

 

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):

<?php
    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

The example of a static Y axis has been updated and you can now find it here.



 

Reducing white space

New in June 2011 is the ability to set the gutters independently. This removes the necessity to translate and adjust the coordinates to get more space and is far more straight-forward. The new properties are:

You can read more about this change here.


 

In-graph labels

As well as an array of strings, like this:

obj.set({
    labelsIngraph: ['First label','Second label']
});

The string can also be an array, consisting of color and placement information, like this:

obj.set({
    labelsIngraph: ['First label',['Second label', 'red', 'yellow', -1, 50] ]
});

You can read more information about this here.

 

Shorthand for in-graph labels

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

line.set({
    labelsIngraph: [6, 'July', 3, 'November']
});


 

Data types

If your data values aren't the correct type - ie numbers - it can cause problems. Pay particular attention to this when you're getting your data from data sources which may be classed as strings, such as JSON or AJAX requests.

 

World map

There is no function in RGraph to do mapping, either of the World or a smaller region. If this is what you want then you may be interested in this HTML5 canvas based mapping system: http://joncom.be/code/excanvas-world-map/

 

Adding text to your charts

You can add arbitrary text to your charts by using the RGraph drawing API text object. Another way is to use the ondraw custom event and the RGraph.Text2() API function, but the drawing object is by far the easiest and requires the least time and coding. It also allows you to add tooltips and click/mousemove events to the text.

 

Crosshairs

[No canvas support]

Some chart types have the ability to use crosshairs. The supported charts are:

There are various options that control the crosshairs, though because some apply to the readout, they are only applicable to the Scatter chart. The crosshairs can be customised by stipulating the linewidth, the color and whether only the horizontal, vertical or both lines are shown.

There are two demo pages - one Line and one Scatter - that show the snap option (that restricts the crosshairs to data points) and how you can then get the dataset/point out of the chart:

Crosshairs and the Scatter chart

Because the X axis is scaled, the Scatter chart has the extra ability of having a coordinates readout when the crosshairs are in use. This is shown in the example above. The appropriate properties are:

In the above example the coordinates are put in the text input by using the custom event oncrosshairs. This is as follows:

function myFunc (obj)
{
    var x = obj.canvas.__crosshairs_x__;
    var y = obj.canvas.__crosshairs_y__;

    document.getElementById("crosshairs.out").value = x + ',' + y;
}
RGraph.AddCustomEventListener(scatter, 'oncrosshairs', myFunc);

 

Logarithmic scale

[No canvas support]

It's possible to get a logarithmic scale in RGraph by using scale.specific. The actual scale that is used when drawing the chart is 0 - 1, and the scale that is displayed is 10/100/1000/10,000/100,000 (for example). This example is shown.


<script>
    var data = [10,10,100,100,1000,1000,10000,10000,100000,100000,1000000,1000000];
    
    // Put the data into log(100000) format
    // The RGraph.log() function is part of the common library
    for (var i=0; i<data.length; ++i) {
        data[i] = RGraph.log(data[i], 10);
    }
    
    var line = new RGraph.Line({
        id: 'log_scale_example',
        data: data,
        options: {
            textAccessible: true
            gutterLeft: 60,
            ymax: 6,
            ylabelsSpecific: ['1,000,000', '100,000','10,000','1000','100','10'],
            numyticks: 10,
            numxticks: 11,
            backgroundGridAutofitNumhlines: 6,
            backgroundGridAutofitNumvlines: 12
        }
    })
</script>

 

Clearing/Resetting the canvas

With the addition of the ObjectRegistry objects are always registered in their constructor, regardless of whether they use dynamic features, to allow them to be redrawn when necessary. This means that if you use one canvas to draw multiple charts on then you may get previous charts appearing if you use features such as tooltips which redraw the canvas.

To get around this you not only need to clear the canvas (with RGraph.Clear()) but you will also need to remove previous objects from the ObjectRegistry. You can do this in a few ways:

  1. RGraph.ObjectRegistry.clear() This clears the entire ObjectRegistry allowing you to "start from scratch" again with a clean slate.
  2. RGraph.ObjectRegistry.clear(canvas) A slight variation on the above, this is the same method but with a canvas object (the same as what you get from document.getElementById() ) passed as the first argument. Only objects that are registered to use this canvas will be cleared.
  3. RGraph.ObjectRegistry.clear(id) The same as the above but instead of passing it the canvas object you can pass it the ID (a string) of the canvas.
  4. RGraph.ObjectRegistry.remove(obj) This method removes a single object from the ObjectRegistry.
  5. RGraph.reset(canvas) This method clears the ObjectRegistry of objects applicable to the canvas, clears the antialiasing translate fix and clears the canvas.

    Note: If you use the same canvas for multiple charts you will need to use this function instead of the RGraph.Clear() function.


 

CSV data

If your data is intially in CSV form a simple way to pass it to RGraph is to print it as part of the page in a hidden DIV tag. You can then use the standard document.getElementById() to retrieve it and the .split() function to convert it to an array. Keep in mind that if you do this you will end up with an array of strings - so you will need to loop through the array converting the strings to numbers. There's an example of this here.

As of October 2013 there's now a new CSV file reader that is part of RGraph. You can read more by following the link.


 

How to convert degrees to radians

To convert degrees, which everyone knows and understands, to radians - which is what angles are measured in when working with <canvas> you can use this formula:

radians = (Pi / 180) * degrees

Which would translate to this JavaScript code:

<script>
    var degrees = 78;
    var radians = (Math.PI / 180) * degrees;
<script>

 

Internet Explorer pseudo-constants

For conditionally enabling or disabling features in Internet Explorer there are constants available for you to use: RGraph.ISIE, RGraph.ISIE6, RGraph.ISIE8, RGraph.ISIE9, RGraph.ISIE9UP, RGraph.ISIE10, RGraph.ISIE10UP You can use them like this:

<script>
    if (RGraph.ISIE9UP) {
        // ...
    }
</script>

 

Known issues

There's a few known issues documented here

Comments

Add a new comment...