Miscellaneous information
- Upper and lower limits for horizontal bars
- Setting the canvas width and height
- The canvas coordinate system
- Debugging tips
- Inspecting an RGraph chart
- Double click context menus
- Adding your own event handlers
- Carriage returns and newlines in labels
- Character set issues
- How to identify an RGraph object
- Static Y-axis
- Reducing white space
- Ingraph labels
- Shorthand for ingraph labels
- Data types
- Adding text to your charts
- Crosshairs
- Crosshairs and the Scatter chart
- Logarithmic scale
- Clearing/Resetting the canvas
- CSV data
- How to convert degrees to radians
- Internet Explorer pseudo-constants
- RGraph pseudo-constants
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:
- Ensure you have only one chart on the page
- Make sure you have disabled your web browsers cache (the Firefox Web Developer toolbar can do this for Firefox)
- Try using Firebug for Firefox or the Webkit developer tools for Google Chrome (CTRL_SHIFT+J) and Safari (CTRL+ALT+C). There's a video about using the Chrome developer tools here. These are very useful tools that make development much easier.
- Reduce the page to the bare minimum.
- Start with a very basic chart and build it up slowly.
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 browser's built-in debugging tools.
An example is the WebKit developer tools that 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, 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], options: { textAccessible: false } }).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 an 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:
obj.isrgraph
- This is a boolean that you can use to identify an RGraph object.obj.type
- This identifies the type of an RGraph object. It is a string that contains a one-word description of the object's type, eg bar/line/pie.
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 straightforward. The new properties are:
marginLeft
marginRight
marginTop
marginBottom
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 that 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 that may be classed as strings, such as JSON or AJAX requests.
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
Some chart types can use crosshairs. The supported charts are:
- Bar charts
- Line charts
- Scatter charts
- Waterfall charts
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:
- Line chart (line-crosshairs-snap.html in the download archive)
- Scatter chart (scatter-crosshairs-snap.html in the download archive)
Crosshairs and the Scatter chart
Because the X-axis is scaled, the Scatter chart has the extra ability to have a readout for the coordinates when the crosshairs are in use. This is shown in the example above. The appropriate properties are:
obj.canvas.__crosshairs_x__
obj.canvas.__crosshairs_y__
obj.canvas.__crosshairs_labels__
(this is the coordinates readout)
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
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: {
textAccessible: false,
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 that 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:
-
RGraph.ObjectRegistry.clear()
This clears the entireObjectRegistry
allowing you to "start from scratch" again with a clean slate. -
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 fromdocument.getElementById()
) passed as the first argument. Only objects that are registered to use this canvas will be cleared. -
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. -
RGraph.ObjectRegistry.remove(obj)
This method removes a single object from theObjectRegistry
. -
RGraph.reset(canvas)
This method clears theObjectRegistry
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 standarddocument.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 also a CSV reader that's a 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>
RGraph pseudo-constants
For a few common arrays RGraph provides some pseudo-constants that you can make use of (they're actually just normal variables that use upper-case for their names). The variables that are available are:
RGraph.MONTHS_SHORT = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']; RGraph.MONTHS_LONG = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']; RGraph.DAYS_SHORT = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']; RGraph.DAYS_LONG = ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday']; RGraph.HOURS24 = ['00:00', '01:00', '02:00', '03:00', '04:00', '05:00', '06:00', '07:00', '08:00', '09:00', '10:00', '11:00', '12:00', '13:00', '14:00', '15:00', '16:00', '17:00', '18:00', '19:00', '20:00', '21:00', '22:00', '23:00']; RGraph.HOURS12 = ['00:00', '01:00', '02:00', '03:00', '04:00', '05:00', '06:00', '07:00', '08:00', '09:00', '10:00', '11:00'];
To make use of them you can do this:
<script>
new RGraph.Bar({
id:'cvs',
data: [4,8,6,3,5,4,8],
options: {
textAccessible: false,
colors:['red'],
xaxisLabels: RGraph.DAYS_SHORT,
yaxis: false,
backgroundGridVlines: false,
backgroundGridBorder: false
}
}).draw();
</script>