When using the canvas element you should be aware of the accessibility of your charts, for example where vision limited users are concerned. Screen readers, for example, may not be able to convert a chart into something that is reasonable, so you should 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 full canvas zoom or the resizing feature to enable people to enlarge the chart.
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:
myBar.Set('chart.background.hbars', [[0, null, 'green'], [0,-999999,'red']]);
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. You can see this effect on the animation page with the jQuery animation example.
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.
Older versions of browsers are supported (assuming they have canvas support), however, if they don't support the canvas text or shadow APIs these will naturally be unavailable. The charts will still be drawn, though without shadows or text.
You can now use OfficeExcel with Internet Explorer 8 in conjunction with ExCanvas, (which brings a degree of <canvas> support to MSIE). Bear in mind though that shadows are not available and thus are simulated. Microsoft Internet Explorer 9 has native <canvas> support.
If you're having a hard time debugging your chart, try these:
To help when debugging your OfficeExcel charts and canvas elements, you can use you 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 associated object can be found via the __object__ property.
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.
Because each OfficeExcel 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 myBar = new OfficeExcel.Bar('cvs', [7,4,2,6,3,4,8]);
myBar.Draw();
myBar.canvas.onclick = function ()
{
}
</script>
But what if, for example, you're using an OfficeExcel feature which uses the event handler that you need? In this case you can use the standard DOM2 method addEventListener(). This will add your new event handler without replacing any existing one (ie the one installed by OfficeExcel). For example:
<script>
var myBar = new OfficeExcel.Bar('cvs', [7,4,2,6,3,4,8]);
myBar.Draw();
function myFunc ()
{
}
myBar.canvas.addEventListener('click', myFunc, false)
</script>
You can put carriage returns in your labels by using the string \r\n. This means your labels will span multiple lines. Like so:
myBar.Set('chart.labels', 'John\r\n(Winner!)', ...)
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.
Because identity can sometimes be a tricky affair, there are a few OfficeExcel properties that you can use to check whether an object is an OfficeExcel object:
<div style="position: relative; float: right; margin-right: 10px; margin-top: 10px">
<!-- The width here is set further down the page in script -->
<canvas id="axes" width="0" height="175" style="position: absolute; top: 0; left: 0; z-index: 100"></canvas>
<div style="width: 600px; overflow: auto">
<canvas id="cvs" width="1000" height="200"></canvas>
</div>
</div>
<script>
window.onload = function ()
{
/**
* This is the script that draws the chart
*/
line = new OfficeExcel.Line('cvs', [3,15,22,26,28,24,22,25,23,24,26,23,24,25,27,28,29,26,23,22,24,21,24,25]);
line.Set('chart.noaxes', true); // We draw the Y axis ourselves
line.Set('chart.gutter.top', 25);
line.Set('chart.gutter.bottom', 35);
line.Set('chart.gutter.left', 50);
line.Set('chart.hmargin', 5);
line.Set('chart.linewidth', 3);
line.Set('chart.shadow', true);
line.Set('chart.shadow.offsetx', 0);
line.Set('chart.shadow.offsety', 0);
line.Set('chart.shadow.blur', 15);
line.Set('chart.shadow.color', 'red');
line.Set('chart.tooltips', [
'January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December',
'January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'
]);
line.Set('chart.labels', [
'Jan 09','\r\nFeb 09', 'Mar 09','\r\nApr 09','May 09','\r\nJun 09','Jul 09','\r\nAug 09','Sep 09','\r\nOct 09','Nov 09', '\r\nDec 09',
'Jan 10', '\r\nFeb 10', 'Mar 10','\r\nApr 10','May 10','\r\nJun 10','Jul 10','\r\nAug 10','Sep 10','\r\nOct 10','Nov 10', '\r\nDec 10'
]);
line.Draw();
/**
* And this is the script that draws the left axis, on the other canvas (that doesn't move)
*/
ca = document.getElementById("axes")
co = ca.getContext('2d');
/**
* This sets the smaller canvas to cover the whole of the charts left gutter
*/
ca.width = line.Get('chart.gutter.left') + 1;
OfficeExcel.Clear(ca, 'white');
/**
* This draws the static axis
*/
co.beginPath();
co.moveTo(line.Get('chart.gutter.left'), line.Get('chart.gutter.top'));
co.lineTo(line.Get('chart.gutter.left'), line.canvas.height - line.Get('chart.gutter.bottom'));
// Draw the tickmarks on the axis
var numTicks = 10;
for (var i=0; i<=numTicks; ++i) {
co.moveTo(line.Get('chart.gutter.left'), line.Get('chart.gutter.top') + (((ca.height - line.Get('chart.gutter.top') - line.Get('chart.gutter.bottom')) / numTicks) * i));
co.lineTo(line.Get('chart.gutter.left') - 3, line.Get('chart.gutter.top') + (((ca.height - line.Get('chart.gutter.top') - line.Get('chart.gutter.bottom')) / numTicks) * i));
}
co.stroke();
/**
* This draws the labels for the static axis
*/
co.beginPath();
var color = 'black';
var size = 10;
for (var i=0; i<5; ++i) {
co.fillStyle = color;
co.textAlign = 'right';
co.textBaseline = 'middle';
var h = line.canvas.height - line.Get('chart.gutter.top') - line.Get('chart.gutter.bottom');
OfficeExcel.Text(co,
'Verdana',
size,
line.Get('chart.gutter.left') - 4,
line.Get('chart.gutter.top') + (h * (i/5)),
line.max - (line.max * (i/5)));
}
co.fill();
}
</script>
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:
As well as an array of strings, like this:
obj.Set('chart.labels.ingraph', ['First label','Second label']);
The string can also be an array, consisting of color and placement information, like this:
obj.Set('chart.labels.ingraph', ['First label',['Second label', 'red', 'yellow', -1, 50] ]);
You can read more information about this here.
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('chart.labels.ingraph', [6, 'July', 3, 'November']);
All the charts have now (1st October 2010) been converted to DOM2 for tooltips event registration. This allows them to be far more co-operative if you're using events. Tooltips will not be compatible with MSIE8 - the charts will still be drawn, albeit without tooltips.
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.
If you wish to create your own chart type, there is a skeleton file here that you can use as a starting point. This file contains the bare bones of an OfficeExcel object, such as the .Get() and .Set() methods, as well as examples of common properties.
There is no function in OfficeExcel 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/
You can add arbitrary text to your charts by using the OfficeExcel API. For example you could use this code after the call to .Draw():
function DrawSubTitle (obj)
{
var context = obj.context;
context.beginPath();
context.fillStyle = 'gray';
OfficeExcel.Text(context,
'Verdana',
7,
obj.canvas.width / 2,
obj.Get('chart.gutter.top') - 6,
'The subtitle',
'center',
'center');
context.fill();
}
DrawSubTitle(myLine);
Some charts type 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.
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;
}
OfficeExcel.AddCustomEventListener(scatter, 'oncrosshairs', myFunc);
It's possible to get a logarithmic scale in OfficeExcel by using chart.scale.specific. The actual scale that is used when drawing the chart is 0-5 (for example), and the scale that is displayed is 10/100/1000/10,000/100,000. This example is shown.
There's a few known issues documented here