Miscellaneous information

Summary: Miscellaneous documentation and other information - such as reducing white-space in your charts and adding custom text

Canvas fall-back 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 fall-back 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.

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="cvs" 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 margins go 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 click listener you could do this: 

<script>
    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({
    xaxisLabels: '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 margins 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:


Ingraph 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 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({
    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 draw custom event and the RGraph.text() API function, but the drawing object is by far the easiest and it 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 example 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 readout for the coordinates 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 crosshairs. 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, 'crosshairs', myFunc);

Logarithmic scale

[No canvas support]

It's possible to get a logarithmic scale in RGraph by using yaxisScaleSpecific. 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>
    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);
    }
    
    line = new RGraph.Line({
        id: 'log_scale_example',
        data: data,
        options: {
            marginLeft: 60,
            yaxisScaleMax: 6,
            yaxisLabelsSpecific: ['1,000,000', '100,000','10,000','1000','100','10'],
            yaxisTickmarksCount: 10,
            xaxisTickmarksCount: 11,
            backgroundGridHlinesCount: 6,
            backgroundGridVlinesCount: 12
        }
    })
</script>

Clearing/Resetting the canvas

With the addition of the ObjectRegistry, objects are always registered in their constructors, regardless of whether they use dynamic features or not, 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 anti-aliasing 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 initially 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.

As of October 2013 there's now a new CSV 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>
    degrees = 78;
    radians = (Math.PI / 180) * degrees;
<script>

There are also some shortcut functions that are available to make things easier: 

<script>
    // Convert degrees to radians
    radians = RGraph.toRadians(degrees);
    
    // Convert radians to degrees
    degrees = RGraph.toDegrees(radians);
</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>