# Using tooltips in your charts

Tooltip effect:

- Introduction
- What can they hold?
- How can I specify them?
- What can I specify?
- Can I show charts in tooltips?
- Can I customise the appearance of tooltips?
- What tooltip effects are available?
- Tooltips, the clipboard and Firefox
- Can I override the tooltip function?

#### Introduction

Tooltips are a very effective and straight forward way to extend your charts and add more information to them, without overloading the user.

#### What can they hold?

At the base level, tooltips are DIVs, so they can hold a multitude of HTML - images, videos etc. See below for information on showing charts in tooltips.

#### How can I specify them?

You can specify them by including the tooltips code and then using the chart.tooltips property. For example:

1. Include the OfficeExcel libraries.

       <script src="OfficeExcel.common.core.js"></script>
       <script src="OfficeExcel.common.tooltips.js"></script>
       <script src="OfficeExcel.line.js"></script>

2. Define your chart and set the tooltips property.

       <script>
           window.onload = function ()
           {
               var line = new OfficeExcel.Line('cvs', [64,34,26,35,51,24]);
               line.Set('chart.tooltips', ['<b>Winner!</b><br />John', 'Fred', 'Jane', 'Lou', 'Pete', 'Kev']);
               line.Set('chart.tooltips.effect', 'expand');
               line.Set('chart.hmargin', 10);
               line.Set('chart.linewidth', 2);
               line.Set('chart.shadow', true);
               line.Set('chart.shadow.offsetx', 0);
               line.Set('chart.shadow.offsety', 0);
               line.Set('chart.shadow.color', 'green');
               line.Set('chart.shadow.blur', 25);
               line.Set('chart.colors', ['green']);
               line.Set('chart.tickmarks', 'circle');
               line.Set('chart.labels', ['John', 'Fred', 'Jane', 'Lou', 'Pete', 'Kev']);
               line.Draw();
           }
       </script>

#### What can I specify?

The tooltips that you specify are usually strings (which can contain HTML). They can however also be functions which are called when they're about to be displayed. The function should return the text that is used as the tooltip. You have the option to either specify one function per data point, or just one function for all of the tooltips. You can mix functions and strings if you wish. These functions are passed the numerical, zero-indexed tooltip index and the return value is used as the tooltip text. So to summarise:

- An array of strings. The string is used as the tooltip. Eg:

      myGraph.Set('chart.tooltips', ['John', 'Fred', 'Lou']);

- An array of function objects. Each function is called and should return the text to be used. Eg:

      myGraph.Set('chart.tooltips', [getJohnTooltip, getFredTooltip, getLouTooltip]);

- A single function object. This is probably the most useful. This function is called whenever a tooltip is about to be displayed, and passed the numerical, zero-indexed tooltip index of the point on the chart. The function should return the text to be used as the tooltip. Note that the function you specify is called before the tooltip DIV has been created, so you cannot access it. If you wish to customise the appearance of the tooltip, you can use either the tooltip CSS class or a call to setTimeout(). Eg:

      myGraph.Set('chart.tooltips', getTooltip);

- An array of DIV ids. This will make working with large tooltips easier. You basically specify the id of a DIV whose .innerHTML is then used as the tooltip. Only the contents of the DIV are used, not the DIV itself, so you can hide the DIV by setting its display CSS value to none. For example:

      myBar.Set('chart.tooltips', ['id:myDiv', ...])

#### Can I show charts in tooltips?

You can, and with the custom event support that OfficeExcel has, it's reasonably easy. Simply attach your function that creates the chart to the ontooltip event. This allows the tooltip HTML to be created and added to the page so that the code that creates the chart can run. The sequence is:

1. Specify the HTML for the tooltip as normal (including the <canvas> tag).
2. Use the ontooltip OfficeExcel event so that a function is called when a tooltip is shown.
3. This function should subsequently create the chart.

The tooltip DIV is to be found in the OfficeExcel registry - OfficeExcel.Registry.Get('chart.tooltip'). And if you want it the numerical zero indexed count of the tooltip is to be found in the __index__ property: OfficeExcel.Registry.Get('chart.tooltip').__index__

    <script src="OfficeExcel.common.core.js" ></script>
    <script src="OfficeExcel.common.tooltips.js" ></script>
    <script src="OfficeExcel.bar.js" ></script>
    <script src="OfficeExcel.line.js" ></script>

    <style>
        .OfficeExcel_tooltip {
            background-color: white ! important;
        }
    </style>

    <canvas id="cvs" width="600" height="250">[No canvas support]</canvas>

    <script>
        window.onload = function ()
        {
            labels = ['Gary','Pete','Lou','Ned','Kev','Fred'];

            bar = new OfficeExcel.Bar("cvs", [4.5,28,13,26,35,36]);
            bar.Set('chart.tooltips', function (idx) {return labels[idx] + 's stats<br/><canvas id="__tooltip_canvas__" width="400" height="150">[No canvas support]</canvas>';});
            bar.Set('chart.hmargin', 10);
            bar.Set('chart.tickmarks', 'endcircle');
            bar.Set('chart.colors', ['blue']);
            bar.Set('chart.ymax', 100);
            bar.Set('chart.labels', labels);
            bar.Draw();

            OfficeExcel.AddCustomEventListener(line, 'ontooltip', CreateTooltipGraph);
        }

        /**
        * This is the function that is called by the ontooltip event to create the tooltip charts
        *
        * @param obj object   The chart object
        */
        function CreateTooltipGraph(obj)
        {
            // This data could be dynamic
            var line  = new OfficeExcel.Line('__tooltip_canvas__', [5,8,7,6,9,5,4,6,3,5,4,4]);
            line.Set('chart.labels', ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']);
            line.Set('chart.hmargin', 5);
            line.Set('chart.tickmarks', 'endcircle');
            line.Set('chart.background.grid.autofit', true);
            line.Draw();
        }

    </script>

If you want to see more source code, simply view the source of this page and look at the code that creates the bar chart. There's also a basic stripped-down example here.

#### Can I customise the appearance of tooltips?

Yes. You can either use the default CSS class OfficeExcel_tooltip, or you can specify a specific CSS class that a charts tooltips should use with the property chart.tooltips.css.class. The two charts on this page have different looking tooltips by using this method - the line chart uses the default look, whilst the bar chart overrides the CSS class name and sets it to bar_chart_tooltips_css. For example:

    bar.Set('chart.tooltips.css.class', 'bar_chart_tooltips_css');

    <style>
        .bar_chart_tooltips_css {
            background-color: white ! important;
            border: 2px solid black ! important;
            padding: 3px;
        }
    </style>

You can read more about OfficeExcel CSS classes here.

#### What tooltip effects are available?

These effects are available to you:

- fade
- expand
- contract
- snap
- none

All of them are as their names imply. fade is a straight forward fade in effect, expand is another effect which expands outward from the center of the tooltip, contract is like the expand effect but in reverse, snap is an effect which can be used in a limited set of circumstances and "snaps" to the current mouse position and none is simply no effect at all. The default effect used by all chart types is fade. Note: If you're showing canvases in your tooltips then the expand, contract and snap effects will not work - you must use fade or none.

Note: The snap effect is only available to chart types where the tooltip is triggered using the onmousemove event. Currently this means the Line chart, Rscatter chart, Scatter chart and Radar chart. It can also be negatively effected when using multiple charts on one page.

#### Tooltips, the clipboard and Firefox

If you're using Firefox, there's a note about tooltips and the clipboard (ie copying text) on the issues page.

#### Can I override the tooltip function?

You can by stipulating chart.tooltips.override. This should be a function object that handles everything with regard to showing the tooltip. Highlighting the chart is still done for you - the override function is only concerned with showing the tooltip. The override function is passed these arguments:

- canvas - The HTML canvas element, the same as what you get from document.getElementById()
- text - The tooltip text (id:xxx strings are NOT expanded)
- x - The X coordinate in relation to the entire page
- y - The Y coordinate in relation to the entire page
- index - The numerical index of the tooltip in the original tooltip array

Note: Although "id:xxx" strings are not expanded for you, you can easily do this yourself by using the OfficeExcel.getTooltipText('id:xxx') function.

    <script>
        function tooltip_override (canvas, text, x, y, idx)
        {
            alert('In tooltip override function...');
        }
        myObj.Set('chart.tooltips.override', tooltip_override);
    </script>

Foo