# Miscellaneous documentation

- Canvas fallback content and visually impaired users
- Upper and lower limits for horizontal bars
- Setting the canvas width and height
- The canvas coordinate system
- OfficeExcel and older browsers
- OfficeExcel and Microsoft Internet Explorer
- Debugging tips
- Inspecting an OfficeExcel chart
- Double click context menus
- Adding your own event handlers
- Carriage returns and newlines in labels
- Character set issues
- How to identify an OfficeExcel object
- Static Y axis
- Reducing white space
- In-graph labels
- Shorthand for in-graph labels
- DOM2 Event handlers
- Data types
- Creating your own chart type
- World map
- Adding text to your charts
- Crosshairs
- Logarithmic scale
- Known issues

#### 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 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.

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

    myBar.Set('chart.background.hbars', [[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. You can see this effect on the animation page with the jQuery animation example.

#### 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.

#### OfficeExcel and older browsers

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.

#### OfficeExcel and Microsoft Internet Explorer

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.

#### 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.

#### Inspecting an OfficeExcel chart

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.

#### 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 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>

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

    myBar.Set('chart.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 OfficeExcel object

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:

- obj.isOfficeExcel - This is a boolean that you can use to clearly identify an OfficeExcel object.
- obj.type - This identifies the type of an OfficeExcel object. It is a string which contains a one word description of the objects chart type, eg bar/line/pie.

#### Static Y axis

A static Y axis is useful if you have a wide chart but limited space. Whilst not part of the OfficeExcel libraries itself, it can be achieved with a little HTML, like the chart shown. The HTML and the script to achieve this is shown below. It involves placing an extra canvas above the chart with the Y axis drawn on it. This canvas doesn't move when the main canvas scrolls left and right.

Note: Because Firefox doesn't support the event.offsetX and event.offsetY properties and they have to be simulated, scrolling in conjunction with tooltips in this case and this browser doesn't work.

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

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

- chart.gutter.left
- chart.gutter.right
- chart.gutter.top
- chart.gutter.bottom

You can read more about this change here.

#### In-graph labels

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.

#### 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('chart.labels.ingraph', [6, 'July', 3, 'November']);

#### DOM2 Event handlers

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.

#### 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.

#### Creating your own chart type

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.

#### World map

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/

#### Adding text to your charts

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

#### Crosshairs

Some charts type have the ability to 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.

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

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

#### Logarithmic scale

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.

#### Known issues

There's a few known issues documented here