Tooltips on your charts

Introduction to tooltips

Tooltips are a very effective and straightforward 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 div tags, so they can hold a multitude of HTML - images, videos etc. See below for information about showing charts in tooltips.

How can I specify them?

You can specify them by including the tooltips and dynamic library files - RGraph.common.tooltips.js and RGraph.common.dynamic.js - and then using the tooltips property. For example:

  1. Include the RGraph libraries.
    <script src="RGraph.common.core.js"></script>
    <script src="RGraph.common.dynamic.js"></script>
    <script src="RGraph.common.tooltips.js"></script>
    <script src="RGraph.line.js"></script>
    
  2. Define your chart and set the tooltips property.
    <script>
        new RGraph.Line({
            id: 'cvs',
            data: [64,34,26,35,51,24],
            options: {
                marginInner: 10,
                linewidth: 2,
                shadowOffsetx: 0,
                shadowOffsety: 0,
                shadowColor: 'green',
                shadowBlur: 25,
                color: ['green'],
                tickmarksStyle: 'endcircle',
                xaxisLabels: ['John', 'Fred', 'Jane', 'Lou', 'Pete', 'Kev'],
                tooltips: ['<b>Winner!</b><br />John','Fred','Jane','Lou','Pete','Kev']
            }
        }).draw();
    </script>
    

What can I specify?

The tooltips that you specify are usually strings (which can contain HTML tags). They can, however, also be functions that are called when they're about to be displayed. The function should return the text that's to be 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:

New in version 5.22 is the ability to also just specify a single string of text that has various macros (bits of text) that are then substituted for the relevant value. An example of this is:

tooltips: 'The value was: %{value_formatted}'

Can I show charts in tooltips?

You can, and with the custom event support that RGraph has, it's reasonably easy. Simply attach your function that creates the chart to the tooltip 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 tooltip RGraph 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 RGraph registry - RGraph.Registry.get('tooltip'). And if you want it the numerical zero indexed count of the tooltip is to be found in the __index__ property: RGraph.Registry.get('tooltip').__index__

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

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

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

<script>
    labels = ['Gary','Pete','Lou','Ned','Kev','Fred'];

    bar = new RGraph.Bar({
        id: 'cvs',
        data: [4.5,28,13,26,35,36],
        options: {
            tooltips: '%{property:xaxisLabels[%{dataset}]}s stats <br/> <canvas id="__tooltip_canvas__" width="400" height="150">[No canvas support]</canvas>',
            tooltipsPointer: false,
            marginInner: 10,
            tickmarksStyle: 'endcircle',
            colors: ['blue'],
            yaxisScaleMax: 100,
            xaxisLabels: labels,
            xaxis: false,
            yaxis: false
        }
    }).draw();
    
    line.ontooltip = CreateTooltipGraph;
      

    
    //
    // This is the function that is called by the tooltip event to
    // create the tooltip charts
    // 
    // @param obj object   The chart object
    //
    function CreateTooltipGraph(obj)
    {
        // This data could be dynamic
        var line  = new RGraph.Line({
            id: '__tooltip_canvas__',
            data: [5,8,7,6,9,5,4,6,3,5,4,4],
            options: {
                xaxisLabels: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
                marginInner: 5,
                tickmarksStyle: 'endcircle'
            }
        }).draw();
    }
</script>

Can I customise the appearance of tooltips?

Yes. You can either use the default CSS class RGraph_tooltip, or you can specify a specific CSS class that a charts tooltips should use with the property tooltipsCssClass. Two charts on the same page can have significantly different-looking tooltips by using this method. For example:

obj.set({
    tooltipsCssClass: 'bar_chart_tooltips'
});
<style>
    .bar_chart_tooltips {
        background-color: white ! important;
        border: 2px solid black ! important;
        padding: 3px;
    }
</style>

Customising the appearance of tooltips in your charts configuration

New in version 5.22 was the addition of the tooltipsCss property. This allows you to specify the style of a chart's tooltips in the charts configuration code. These styles will only be applied to that chart's tooltips (instead of the tooltips for every chart on the page). For example (remember to use the JavaScript versions of the CSS property names):

tooltipsCss: {
    backgroundColor: 'black',
    color:'white',
    fontSize: '18pt'
}

Customising the default appearance of tooltips in JavaScript

If you want to set the default style that's used for tooltips you can do so in your JavaScript code. All of the styles are applied to the tooltip by copying them from the RGraph.tooltips.style object. Remember to use the JavaScript names of the CSS properties (capitals instead of hyphens). You only need to set this once (eg after your call to draw ) and then these defaults are used for every tooltip after that.

RGraph.tooltips.style.fontFamily      = 'Arial';
RGraph.tooltips.style.fontSize        = '10pt';
RGraph.tooltips.style.fontWeight      = 'normal';
RGraph.tooltips.style.textAlign       = 'center';
RGraph.tooltips.style.backgroundColor = 'rgb(255,255,239)';
RGraph.tooltips.style.color           = 'black';
RGraph.tooltips.style.borderRadius    = '5px';
RGraph.tooltips.style.boxShadow       = 'rgba(96,96,96,0.5) 0 0 5px';

These defaults are used for ALL tooltips - if you want to customise just one charts tooltips (and you have multiple charts with tooltips on the page) then use the CSS class method mentioned above.

Using formatting macros in your CSS values

What if you want some of your tooltips to have one color for their border but other tooltips to use a different color? This isn't catered for by just CSS alone, so RGraphs formatting options can do this for you. This means that when you use the CSS options that are available to you (ie the tooltipsCss configuration option and when you use JavaScript to customise tooltips) you can use formatting identifiers in the CSS values like this:

new RGraph.Bar({
    id: 'cvs',
    data: [[4,2,2],[4,8,6],[3,5,8],[4,8,5],[4,1,2],[1,9,5],[7,8,6]],
    options: {
        tooltips: 'Result of the competition:<br /><span style="font-size: 26pt">%{property:names[%{dataset}]}',
        borderColors: ['red','#0f0','blue'],
        colors: ['green','pink','orange'],
        tooltipsCss: {
            border: '3px solid %{property:borderColors[%{index}]}'
        }
    }
}).draw();

RGraph.tooltips.style.backgroundColor = '%{property:colors[%{index}]}';

So when you use the tooltipsCss property you can put formatting macros in the values and also when you use the RGraph.tooltips.style or RGraph.tooltips.css objects you can use macros too.

Obviously, some of the macros (the %{key} macro, for example) simply have no use when used inside CSS values - so there's no point trying to use them here.

For an example of this in action, you can look at the source code of the line-tooltips-dataset.html demo which is in the download (in the demos/ folder).

Note

Formatting macros can also be used in svg chart tooltips as well as canvas.

What tooltip effects are available?

The default effect is slide, which causes the tooltip to slide to the new position from the previous tooltips' position or if it's the first tooltip that's shown on the page then it will slide from from the top left corner of the page.

Other available tooltip effects are fade and also none - both of which are self explanatory.

Can I override the tooltip function?

You can, by stipulating tooltipsOverride. This should be a function that handles everything to do with 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:

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

<script>
    function tooltip_override (obj, text, x, y, idx)
    {
        alert('In tooltip override function...');
    }
    myObj.set({
        tooltipsOverride: tooltip_override
    });
</script>

Formatted tooltips

Formatted tooltips are a new addition to RGraph version 5.22 and make building dynamic tooltips much easier.

Instead of giving an array of tooltips like this:

tooltips: ['Richard: 48%','Neil: 95%','Jill: 88%','Milly: 69%','Lucy: 76%','John: 90%']

You can give a single tooltip (a string) that has certain macros in it which get replaced with the relevant value by RGraph just before the tooltip is displayed. So less coding for you and the code that you do have to write looks prettier! The example above would be transformed into this:

myNames: ['Richard','Neil','Jill','Milly','Lucy','John'], // A custom property
myScores: [48,95,38,69,76,90],                            // A custom property
tooltips: '%{property:myNames[%{dataset}]}: %{property:myScores[%{dataset}]}%'

You may be thinking: "But that's actually more code!" And yes, that's true in this example, but there's more structure, less "hard-coding" of values and it's easier to write and maintain.

In fact, your tooltips could be as simple as this (which is replaced with the label and the value of the data-point formatted with a decimal point and thousand separators of your choosing along with units):

tooltips: '${property:xaxisLabels[%{dataset}]}: %{value_formatted}'

Example code that uses tooltip macros

Example code for formatted tooltips is shown above.
And there's a demo page that has been converted to use the macros here.

What macros are available for me to use?

The macros that are available for you to use are as follows. These macros are expanded to the relevant values when they're shown:

There are a few examples in the demos/ folder of the download archive that show tooltip templates:

Using custom properties with your tooltips

By using custom properties in your chart configuration you can pass in more data to your chart which the tooltips can then use. This is shown in the chart above with the myNames property - the full chart code is:

new RGraph.Bar({
    id: 'cvs_tooltip_templates',
    data: [[5,3],[9,1],[6,6],[5,9],[5,5],[4,3],[5,9]],
    options: {
        colors: ['Gradient(#faa:red)','Gradient(#aaf:blue)'],
        xaxisLabels: ['Monday','Tuesday','Wednesday','Thursday','Friday','Saturday','Sunday'],
        xaxis: false,
        yaxis: false,
        backgroundGridBorder: false,
        backgroundGridVlines: false,
        myNames: ['Dave','Richard'],
        tooltips: 'Score for %{property:myNames[%{index}]} on %{property:xaxisLabels[%{dataset}]}: %{value}kg'
    }
}).draw();

The custom properties can be strings, numbers or arrays. The example above shows an array.

Formatted tooltips will help you generate tooltips that have the data from your chart embedded in them and enhance the abilities of RGraph significantly.