source: Dev/trunk/RGraph/docs/tooltips.html @ 217

Last change on this file since 217 was 77, checked in by fpvanagthoven, 14 years ago

RGraph
File size: 23.3 KB
RevLine 
[77]1<?php ob_start('ob_gzhandler') ?>
2<!DOCTYPE html >
3<html>
4<head>
5    <meta http-equiv="X-UA-Compatible" content="chrome=1">
6    <!--
7        /**
8        * o------------------------------------------------------------------------------o
9        * | This file is part of the RGraph package - you can learn more at:             |
10        * |                                                                              |
11        * |                          http://www.rgraph.net                               |
12        * |                                                                              |
13        * | This package is licensed under the RGraph license. For all kinds of business |
14        * | purposes there is a small one-time licensing fee to pay and for non          |
15        * | commercial  purposes it is free to use. You can read the full license here:  |
16        * |                                                                              |
17        * |                      http://www.rgraph.net/LICENSE.txt                       |
18        * o------------------------------------------------------------------------------o
19        */
20    -->
21    <title>RGraph: Javascript charts and graph library - Tooltips</title>
22
23    <link rel="stylesheet" href="../css/website.css" type="text/css" media="screen" />
24    <link rel="icon" type="image/png" href="../favicon.png">
25   
26    <meta property="og:title" content="RGraph: Javascript charts and graph library" />
27    <meta property="og:description" content="A chart library based on the HTML5 canvas tag" />
28    <meta property="og:image" content="http://www.rgraph.net/images/logo.jpg"/>
29
30    <script src="../libraries/RGraph.common.core.js"></script>
31    <script src="../libraries/RGraph.common.tooltips.js"></script>
32    <script src="../libraries/RGraph.line.js"></script>
33    <script src="../libraries/RGraph.bar.js"></script>
34    <script src="../libraries/RGraph.pie.js"></script>
35    <!--[if IE 8]><script src="../excanvas/excanvas.original.js"></script><![endif]-->
36   
37    <style>
38        .bar_chart_tooltips_css {
39            background-color: white ! important;
40            border: 2px solid black ! important;
41            padding: 3px;
42            padding-top: 5px ! important;
43            font-size: 14pt ! important;
44            text-align: center;
45            -webkit-box-shadow: 0 0 15px gray ! important;
46            -moz-box-shadow: 0 0 15px gray ! important;
47            box-shadow: 0 0 15px gray ! important;
48        }
49    </style>
50
51    <script>
52      var _gaq = _gaq || [];
53      _gaq.push(['_setAccount', 'UA-54706-2']);
54      _gaq.push(['_trackPageview']);
55   
56      (function() {
57        var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
58        ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
59        var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
60      })();
61    </script>
62
63</head>
64<body>
65
66   
67    <!-- Social networking buttons -->
68        <div id="social_icons" class="warning" style="border-radius: 10px; top: 1px; position: fixed">
69            <a title="Bookmark with delicious" href="http://delicious.com/save?jump=close&v=4&noui&jump=close&url=http://www.rgraph.net&notes=RGraph%20is%20a%20HTML5%20based%20javascript%20charts%20library%20supporting%20a%20wide%20range%20of%20different%20charts%20types&title=RGraph:Javascript%20charts%20and%20graphs%20library" target="_blank"><img src="../images/delicious.png" alt="Bookmark with delicious" width="22" height="22" border="0" align="absmiddle" /></a>
70            <a href="http://twitter.com/home/?status=RGraph%3A%20Javascript+charts+and+graph+library+http%3A%2F%2Fwww.rgraph.net+%23rgraph+%23html5+%23canvas+%23javascript+%23charts+@_rgraph" target="_blank"><img src="../images/twitter.png" id="twitter_icon" alt="tweet this site" width="22" height="22" border="0" align="absmiddle" /></a>
71        </div>
72
73        <script>
74            // Opera fix
75            if (navigator.userAgent.indexOf('Opera') == -1) {
76              document.getElementById("social_icons").style.position = 'fixed';
77            }
78        </script>
79    <!-- Social networking buttons -->
80
81    <div id="breadcrumb">
82        <a href="../index.html">RGraph: Javascript charts and graph library</a>
83        >
84        <a href="index.html">Documentation</a>
85        >
86        Tooltips
87    </div>
88
89    <h1>RGraph: <span>Javascript charts and graph library</span> - Tooltips</h1>
90
91    <script>
92        if (RGraph.isIE8()) {
93            document.write('<div style="background-color: #fee; border: 2px dashed red; padding: 5px"><b>Important</b><br /><br /> Internet Explorer 8 does not natively support the HTML5 canvas tag, so if you want to see the charts, you can either:<ul><li>Install <a href="http://code.google.com/chrome/chromeframe/">Google Chrome Frame</a></li><li>Use ExCanvas. This is provided in the RGraph Archive.</li><li>Use another browser entirely. Your choices are Firefox 3.5+, Chrome 2+, Safari 4+ or Opera 10.5+. </li></ul> <b>Note:</b> Internet Explorer 9 fully supports the canvas tag. Click <a href="http://support.rgraph.net/message/rgraph-in-internet-explorer-9.html" target="_blank">here</a> to see some screenshots.</div>');
94        }
95    </script>
96
97    <div style="float: right; text-align: right">
98        <canvas width="600" height="250" id="cvs">[No canvas support]</canvas><br />
99        Tooltip effect:
100        <select id="effect" onchange="RGraph.Clear(line.canvas); line.Set('chart.tooltips.effect', this.options[this.selectedIndex].value); line.Draw();">
101            <option>none</option>
102            <option selected>fade</option>
103            <option>expand</option>
104            <option>contract</option>
105            <option>snap</option>
106        </select>
107    </div>
108
109    <script>
110        /**
111        * This is the function which handles the display of all the tooltips (for the line chart) - it is passed the
112        * zero-indexed number of the tooltip. Here, that index is just used to get the text from an array, but you
113        * could do anything with it. You could even perform an AJAX request to get the tooltip. Note that at this
114        * point, ie when the text is being retrieved, the tooltip DIV doesn't exist yet.
115        */
116        function myTooltipFunc (idx)
117        {
118            var tooltips = ['<b>Winner!</b><br />John','Fred','Jane','Lou','Pete','Kev'];
119            return tooltips[idx];
120        }
121
122
123        window.onload = function ()
124        {
125            // Has to be a global variable
126            line = new RGraph.Line('cvs', [64,34,26,35,51,24]);
127           
128            /**
129            * These lines show you some of the alternative methods  of specifying tooltips:
130            *
131            *  o An array of strings - one per tooltip
132            *  o An array of functions - one per tooltip
133            *  o A single function that handles all of the tooltips
134            * o An "id:xxx" string (xxx being the ID tag of a div whose contents are used as the tooltip)
135            *
136            * Functions are passed a single argument - the zero-indexed number of the tooltip
137            */
138            //line.Set('chart.tooltips', ['John', 'Fred', 'Jane', 'Lou', 'Pete', 'Kev']);
139            //line.Set('chart.tooltips', [myTooltipFunc, myTooltipFunc, myTooltipFunc, myTooltipFunc, myTooltipFunc, myTooltipFunc]);
140            line.Set('chart.tooltips', myTooltipFunc);
141            line.Set('chart.tooltips.effect', 'fade');
142            line.Set('chart.hmargin', 10);
143            line.Set('chart.linewidth', 2);
144            line.Set('chart.shadow', true);
145            line.Set('chart.shadow.offsetx', 0);
146            line.Set('chart.shadow.offsety', 0);
147            line.Set('chart.shadow.blur', 15);
148            line.Set('chart.colors', ['green']);
149            line.Set('chart.tickmarks', 'circle');
150            line.Set('chart.labels', ['John', 'Fred', 'Jane', 'Lou', 'Pete', 'Kev']);
151            line.Draw();
152
153
154            /* -------------------------------------------------------------------------------------------------------- */
155
156
157            /**
158            * Create and display the bar chart
159            */
160            bar = new RGraph.Bar('cvs2', [41.2,51.3,64.2,42.1,32.2,43.2,45.8,45.1,61.1]);
161           
162            var grad = bar.context.createLinearGradient(0,25,0,225);
163            grad.addColorStop(0, 'blue');
164            grad.addColorStop(1, 'white');
165
166            bar.Set('chart.hmargin', 15);
167            bar.Set('chart.colors', [grad]);
168            bar.Set('chart.linewidth', 2);
169            bar.Set('chart.tickmarks', 'endsquare');
170            bar.Set('chart.labels', ['John', 'Pete', 'Glynn', 'Kev', 'Youssef', 'Lou', 'Kiff', 'Liz', 'Fred']);
171            bar.Set('chart.background.grid.autofit', true);
172            bar.Set('chart.strokecolor', 'rgba(0,0,0,0)');
173            bar.Set('chart.tooltips', getTooltip); // The getTooltip() function (defined below) provides the tooltip text ONLY
174            bar.Set('chart.tooltips.css.class', 'bar_chart_tooltips_css');
175            bar.Set('chart.tooltips.effect', 'fade');
176            bar.Draw();
177           
178            /**
179            * This installs the RGraph ontooltip event handler. The CreateTooltipGraph() function is defined below
180            */
181            RGraph.AddCustomEventListener(bar, 'ontooltip', CreateTooltipGraph);
182        }
183
184
185        /*
186        * Used by the bar chart to get the tooltip text.
187        *
188        * @param idx int The zero indexed number of the tooltip
189        */
190        function getTooltip(idx)
191        {
192            return '<b>' + bar.Get('chart.labels')[idx] + 's stats</b><br /><canvas id="__tooltip_canvas__" width="400" height="150" style="background-color: white; margin: 5px">[No canvas support</canvas>';
193        }
194
195
196        /**
197        * This is the function that is called (by the ontooltip event) to create the tooltip charts
198        *
199        * @param obj object   The chart object
200        */
201        function CreateTooltipGraph(obj)
202        {
203            // These are the statistics that are shown in the tooltips. This data could quite easily
204            // come from your server.
205            var stats = [
206                         [5,8,7,6,9,5,4,6,3,5,4,4],
207                         [4,6,7,8,6,5,4,4,2,5,8,4],
208                         [3,2,1,3,4,5,1,5,6,7,4,1],
209                         [3,5,1,2,4,8,9,6,7,4,5,1],
210                         [9,6,7,8,7,9,4,5,6,3,5,8],
211                         [4,8,5,6,4,3,5,4,6,5,7,8],
212                         [4,3,4,9,8,7,8,6,4,3,5,1],
213                         [1,2,3,1,2,4,5,1,6,5,3,1],
214                         [2,3,5,4,3,5,1,3,5,2,6,4]
215                        ];
216
217            var idx  = RGraph.Registry.Get('chart.tooltip').__index__;
218            var data = stats[idx];
219
220            // This data could be dynamic
221            var g  = new RGraph.Line('__tooltip_canvas__', data);
222            g.Set('chart.labels', ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']);
223            g.Set('chart.gutter.top', 5);
224            g.Set('chart.hmargin', 5);
225            g.Set('chart.tickmarks', 'endcircle');
226            g.Set('chart.background.grid.autofit', true);
227            g.Draw();
228        }
229
230
231    </script>
232
233    <ul>
234        <li><a href="#introduction">Introduction</a></li>
235        <li><a href="#hold">What can they hold?</a></li>
236        <li><a href="#how">How can I specify them?</a></li>
237        <li><a href="#what">What can I specify?</a></li>
238        <li><a href="#charts">Can I show charts in tooltips?</a></li>
239        <li><a href="#customise">Can I customise the appearance of tooltips?</a></li>
240        <li><a href="#effects">What tooltip effects are available?</a></li>
241        <li><a href="#firefox">Tooltips, the clipboard and Firefox</a></li>
242        <li><a href="#override">Can I override the tooltip function?</a></li>
243    </ul>
244
245    <a name="introduction"></a>
246    <h4>Introduction</h4>
247
248    <p>
249        Tooltips are a very effective and straight forward way to extend your charts and add more information to them, without overloading
250        the user.
251    </p>
252   
253    <a name="hold"></a>
254    <h4>What can they hold?</h4>
255   
256    <p>
257        At the base level, tooltips are DIVs, so they can hold a multitude of HTML - images, videos etc. See <a href="#charts">below</a>
258        for information on showing charts in tooltips.
259    </p>
260
261    <a name="how"></a>
262    <h4>How can I specify them?</h4>
263   
264    <p>
265        You can specify them by including the tooltips code and then using the <i>chart.tooltips</i> property. For example:
266    </p>
267   
268    <ol>
269        <li>
270            Include the RGraph libraries.
271            <pre class="code">
272&lt;script src="RGraph.common.core.js"&gt;&lt;/script&gt;
273&lt;script src="RGraph.common.tooltips.js"&gt;&lt;/script&gt;
274&lt;script src="RGraph.line.js"&gt;&lt;/script&gt;
275</pre>
276        </li>
277       
278        <li>
279            Define your chart and set the tooltips property.
280            <pre class="code">
281&lt;script&gt;
282    window.onload = function ()
283    {
284        var line = new RGraph.Line('cvs', [64,34,26,35,51,24]);
285        <span style="color: green">line.Set('chart.tooltips', ['&lt;b&gt;Winner!&lt;/b&gt;&lt;br /&gt;John', 'Fred', 'Jane', 'Lou', 'Pete', 'Kev']);</span>
286        line.Set('chart.tooltips.effect', 'expand');
287        line.Set('chart.hmargin', 10);
288        line.Set('chart.linewidth', 2);
289        line.Set('chart.shadow', true);
290        line.Set('chart.shadow.offsetx', 0);
291        line.Set('chart.shadow.offsety', 0);
292        line.Set('chart.shadow.color', 'green');
293        line.Set('chart.shadow.blur', 25);
294        line.Set('chart.colors', ['green']);
295        line.Set('chart.tickmarks', 'circle');
296        line.Set('chart.labels', ['John', 'Fred', 'Jane', 'Lou', 'Pete', 'Kev']);
297        line.Draw();
298    }
299&lt;/script&gt;
300</pre>
301        </li>
302    </ol>
303
304    <a name="what"></a>
305    <h4>What can I specify?</h4>
306   
307    <p>
308        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
309        to be displayed. The function should return the text that is used as the tooltip. You have the option to either specify
310        one function per data point, or just one function for all of the tooltips. You can mix functions and strings if you wish.
311        These functions are passed the numerical, zero-indexed tooltip index and the return value is used as the tooltip
312        text. So to summarise:
313    </p>
314   
315    <ul>
316        <li>
317            An array of strings. The string is used as the tooltip. Eg:
318            <pre class="code">myGraph.Set('chart.tooltips', ['John', 'Fred', 'Lou']);</pre>
319        </li>
320
321        <li>
322            An array of function objects. Each function is called and should return the text to be used. Eg:
323            <pre class="code">myGraph.Set('chart.tooltips', [getJohnTooltip, getFredTooltip, getLouTooltip]);</pre>
324        </li>
325
326        <li>
327            A single function object. This is probably the most useful. This function is called whenever a tooltip
328            is about to be displayed, and passed the numerical, zero-indexed tooltip index of the point on the chart.
329            The function should return the text to be used as the tooltip. Note that the function you specify is called
330            <i>before</i>
331            the tooltip DIV has been created, so you cannot access it. If you wish to customise the appearance
332            of the tooltip, you can use either the tooltip <a href="css.html">CSS class</a> or a call to <i>setTimeout()</i>. Eg:
333            <pre class="code">myGraph.Set('chart.tooltips', getTooltip);</pre>
334        </li>
335       
336        <li>
337            An array of DIV ids. This will make working with large tooltips easier. You basically specify the id of a DIV whose
338            .innerHTML is then used as the tooltip. Only the contents of the DIV are used, not the DIV itself, so you can hide
339            the DIV by setting its <i>display</i> CSS value to <i>none</i>. An example of this in action is the
340            <a href="../examples/line.html">first line chart</a>. For example:
341           
342            <pre class="code">myBar.Set('chart.tooltips', ['id:myDiv', ...])</pre>
343        </li>
344    </ul>
345
346    <a name="charts"></a>
347    <h4>Can I show charts in tooltips?</h4>
348
349    <canvas style="float: right" id="cvs2" width="600" height="250">[No canvas support]</canvas>
350
351    <p>
352        You can, and with the custom event support that RGraph has, it's reasonably easy. Simply attach your function that
353        creates the chart to the <i>ontooltip</i> event. This allows the tooltip HTML to be created and added to the page
354        so that the code that creates the chart can run. The sequence is:
355    </p>
356   
357    <ol>
358        <li style="margin-top: 0">Specify the HTML for the tooltip as normal (including the &lt;canvas&gt; tag).</li>
359        <li style="margin-top: 0">Use the <i>ontooltip</i> RGraph event so that a function is called when a tooltip is shown.</li>
360        <li style="margin-top: 0">This function should subsequently create the chart.</li>
361    </ol>
362   
363    <p>
364        The tooltip DIV is to be found in the RGraph registry - <i>RGraph.Registry.Get('chart.tooltip')</i>. And if you want it the
365        numerical zero indexed count of the tooltip is to be found in the <i>__index__</i> property:
366        <i>RGraph.Registry.Get('chart.tooltip').__index__</i>
367    </p>
368   
369    <pre class="code">
370&lt;script src="RGraph.common.core.js" &gt;&lt;/script&gt;
371&lt;script src="RGraph.common.tooltips.js" &gt;&lt;/script&gt;
372&lt;script src="RGraph.bar.js" &gt;&lt;/script&gt;
373&lt;script src="RGraph.line.js" &gt;&lt;/script&gt;
374
375&lt;style&gt;
376    .RGraph_tooltip {
377        background-color: white ! important;
378    }
379&lt;/style&gt;
380
381&lt;canvas id="cvs" width="600" height="250"&gt;[No canvas support]&lt;/canvas&gt;
382
383&lt;script&gt;
384    window.onload = function ()
385    {
386        labels = ['Gary','Pete','Lou','Ned','Kev','Fred'];
387
388        bar = new RGraph.Bar("cvs", [4.5,28,13,26,35,36]);
389        bar.Set('chart.tooltips', function (idx) {return labels[idx] + 's stats&lt;br/&gt;&lt;canvas id="__tooltip_canvas__" width="400" height="150"&gt;[No canvas support]&lt;/canvas&gt;';});
390        bar.Set('chart.hmargin', 10);
391        bar.Set('chart.tickmarks', 'endcircle');
392        bar.Set('chart.colors', ['blue']);
393        bar.Set('chart.ymax', 100);
394        bar.Set('chart.labels', labels);
395        bar.Draw();
396       
397        <span style="color: green">RGraph.AddCustomEventListener(line, 'ontooltip', CreateTooltipGraph);</span>
398    }
399     
400
401    <span style="color: green">
402    /**
403    * This is the function that is called by the ontooltip event to create the tooltip charts
404    *
405    * @param obj object   The chart object
406    */
407    function CreateTooltipGraph(obj)
408    {
409        // This data could be dynamic
410        var line  = new RGraph.Line('__tooltip_canvas__', [5,8,7,6,9,5,4,6,3,5,4,4]);
411        line.Set('chart.labels', ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']);
412        line.Set('chart.hmargin', 5);
413        line.Set('chart.tickmarks', 'endcircle');
414        line.Set('chart.background.grid.autofit', true);
415        line.Draw();
416    }
417    </span>
418&lt;/script&gt;
419</pre>
420
421    <p>
422        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.
423        There's also a basic stripped-down example <a href="basic_tooltips.html">here</a>.
424    </p>
425
426    <br clear="all" />   
427
428        <a name="customise"></a>
429        <h4>Can I customise the appearance of tooltips?</h4>
430       
431        <p>
432            Yes. You can either use the default CSS class <i>RGraph_tooltip</i>, or you can specify a specific CSS class that a
433            charts tooltips should use with the property <i>chart.tooltips.css.class</i>. The two charts on this page have
434            different looking tooltips by using this method - the line chart uses the default look, whilst the bar chart
435            overrides the CSS class name and sets it to <i>bar_chart_tooltips_css</i>. For example:
436        </p>
437       
438        <pre class="code">bar.Set('chart.tooltips.css.class', 'bar_chart_tooltips_css');</pre>
439       
440        <pre class="code">
441&lt;style&gt;
442    .bar_chart_tooltips_css {
443        background-color: white ! important;
444        border: 2px solid black ! important;
445        padding: 3px;
446    }
447&lt;/style&gt;
448</pre>
449
450        <p>
451            You can read more about RGraph CSS classes <a href="css.html">here</a>.
452        </p>
453
454        <a name="effects"></a>
455        <h4>What tooltip effects are available?</h4>
456       
457        <p>
458            These effects are available to you:
459        </p>
460       
461        <ul>
462            <li>fade</li>
463            <li>expand</li>
464            <li>contract</li>
465            <li>snap</li>
466            <li>none</li>
467        </ul>
468       
469        <p>
470            All of them are as their names imply. <i>fade</i> is a straight forward fade in effect, <i>expand</i> is another effect
471            which expands outward from the center of the tooltip, <i>contract</i> is like the <i>expand</i> effect but in reverse, <i>snap</i> is an effect which can be used in a limited set of circumstances
472            and "snaps" to the current mouse position and <i>none</i> is simply no effect at all. The default effect used
473            by all chart types is <i>fade</i>. Note: If you're showing canvases in your tooltips then the <i>expand</i>, <i>contract</i> and <i>snap</i>
474            effects will not work - you must use <i>fade</i> or <i>none</i>.
475        </p>
476       
477        <p>
478            <b>Note:</b> The snap effect is only available to chart types where the tooltip is triggered using the onmousemove event.
479            Currently this means the <i>Line chart</i>, <i>Rscatter chart</i>, <i>Scatter chart</i> and Radar chart. It can also
480            be negatively effected when using multiple charts on one page.
481        </p>
482
483
484        <a name="firefox"></a>
485        <h4>Tooltips, the clipboard and Firefox</h4>
486       
487        <p>
488            If you're using Firefox, there's a note about tooltips and the clipboard (ie copying text) on the <a href="issues.html">issues page</a>.
489        </p>
490       
491        <a name="override"></a>
492        <h4>Can I override the tooltip function?</h4>
493
494        <p>
495            You can by stipulating <i>chart.tooltips.override</i>. This should be a function object that handles everything with regard
496            to showing the tooltip. Highlighting the chart is still done for you - the override function is only concerned with showing
497            the tooltip. The override function is passed these arguments:
498        </p>
499
500        <ul>
501            <li>canvas - The HTML canvas element, the same as what you get from document.getElementById()</li>
502            <li>text - The tooltip text (id:xxx strings are NOT expanded)</li>
503            <li>x - The X coordinate in relation to the entire page</li>
504            <li>y - The Y coordinate in relation to the entire page</li>
505            <li>index - The numerical index of the tooltip in the original tooltip array</li>
506        </ul>
507       
508        <p>
509            <b>Note:</b> Although "id:xxx" strings are not expanded for you, you can easily do this yourself by using the
510            <i>RGraph.getTooltipText('id:xxx')</i> function.
511        </p>
512       
513        <pre class="code">
514&lt;script&gt;
515    function tooltip_override (canvas, text, x, y, idx)
516    {
517        alert('In tooltip override function...');
518    }
519    myObj.Set('chart.tooltips.override', tooltip_override);
520&lt;/script&gt;
521</pre>
522
523</body>
524</html>
Note: See TracBrowser for help on using the repository browser.