RGraph/docs/index.html

   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: HTML5 canvas graph library - documentation</title>
  22
  23     <meta name="keywords" content="rgraph html5 canvas graph docs" />
  24     <meta name="description" content="RGraph: HTML5 canvas graph library - Documentation index" />
  25
  26     <link rel="stylesheet" href="../css/website.css" type="text/css" media="screen" />
  27     <link rel="icon" type="image/png" href="../images/favicon.png">
  28
  29     <meta name="keywords" content="rgraph graph html5 javascript canvas" />
  30     <meta name="description" content="RGraph: The HTML5 graphing library for websites on all platforms" />
  31 </head>
  32 <body>
  33
  34     <!-- Social networking buttons -->
  35
  36     <script src="../libraries/RGraph.common.core.js" ></script>
  37
  38     <script>
  39         function HideTwitterDIV ()
  40         {
  41             document.getElementById("twitter_div").style.opacity = 0;
  42             document.getElementById("twitter_div").style.display = 'none';
  43         }
  44
  45
  46         function ShowTwitterDIV (e)
  47         {
  48             var e   = RGraph.FixEventObject(document.all ? event : e);
  49             var div = document.getElementById("twitter_div");
  50             var img = document.getElementById("twitter_icon");
  51
  52             div.style.display = 'block';
  53             div.style.left    = (RGraph.getCanvasXY(img)[0] + img.offsetWidth - div.offsetWidth + 110) + 'px';
  54             div.style.top     = (RGraph.getCanvasXY(img)[1] - 1) + 'px';
  55
  56             /**
  57             * Fade it in
  58             */
  59             setTimeout('document.getElementById("twitter_div").style.opacity = 0.2;', 25);
  60             setTimeout('document.getElementById("twitter_div").style.opacity = 0.4;', 50);
  61             setTimeout('document.getElementById("twitter_div").style.opacity = 0.6;', 100);
  62             setTimeout('document.getElementById("twitter_div").style.opacity = 0.8;', 125);
  63             setTimeout('document.getElementById("twitter_div").style.opacity = 1.0;', 150);
  64
  65             e.stopPropagation();
  66
  67             return false;
  68         }
  69
  70         /**
  71         * This code installs the event handler that hides the Twitter DIV
  72         */
  73         if (RGraph.isIE8()) {
  74              window.attachEvent('onload', function () {document.body.attachEvent('onclick', HideTwitterDIV);});
  75         } else {
  76             window.addEventListener('click', HideTwitterDIV, false);
  77         }
  78     </script>
  79
  80     <!-- The twitter DIV -->
  81     <div id="twitter_div" style="position: absolute;top: 0;left: 0;background-color: #eee;border: 2px dashed black;box-shadow: 0 0 15px #aaa;-moz-box-shadow: 0 0 15px #aaa;-webkit-box-shadow: 0 0 15px #aaa;padding: 3px;display: none;opacity: 0;z-index: 99;">
  82         <a href="http://twitter.com/home/?status=RGraph%3A+HTML5+canvas+graph+library+based+on+the+HTML5+canvas+tag+http%3A%2F%2Fwww.rgraph.net+%23rgraph+%23html5+%23canvas" target="_blank" title="Share on Twitter" rel="nofollow" style="text-decoration: none">Tweet&nbsp;about&nbsp;RGraph</a><br>
  83         <a href="http://twitter.com/_rgraph" style="text-decoration: none" rel="nofollow" target="_blank">Follow for HTML5 news</a>
  84     </div>
  85
  86     <div id="social_icons" class="warning" style="top: 0; left: 5px; position: absolute">
  87         <script>
  88             // Opera fix
  89             if (navigator.userAgent.indexOf('Opera') == -1) {
  90               document.getElementById("social_icons").style.position = 'fixed';
  91               document.getElementById("twitter_div").style.position = 'fixed';
  92
  93             }
  94         </script>
  95
  96         <b style="display: inline-block; position: relative; top: 1px">Bookmark and share:</b>
  97
  98
  99             <div id="social">
 100                 <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%20graph%20library%20supporting%20a%20wide%20range%20of%20different%20graph%20types:Bar,%20Bipolar,%20Donut,%20Funnel,%20Gantt,%20Horizontal%20Bar,%20LED,%20Line,%20Meter,%20Odometer,%20Pie,%20Progress%20Bar,%20Rose,%20RScatter,%20Scatter%20and%20Traditional%20Radar&title=RGraph:%20HTML5%20canvas%20graph%20library%20based%20on%20the%20HTML5%20canvas%20tag" target="_blank">
 101                     <img src="../images/delicious.png" alt="Bookmark with delicious" width="22" height="22" border="0" align="absmiddle" />
 102                 </a>
 103
 104                 <a href="" target="_blank" onmouseover="if (document.getElementById('twitter_div').style.display == 'none') ShowTwitterDIV(event);" onclick="event.stopPropagation(); event.cancelBubble = true; return false">
 105                     <img src="../images/twitter.png" id="twitter_icon" alt="tweet this site" width="22" height="22" border="0" align="absmiddle" />
 106                 </a>
 107
 108
 109 <!--
 110                 <a title="Post to Google Buzz!" href="" onclick="window.open('http://www.google.com/buzz/post?url=http://www.rgraph.net&imageurl=http://www.rgraph.net/images/logo.png', 'google_buzz_window', 'width=800,height=400,top=100,left=100'); return false">
 111                     <img src="../images/buzz.png" width="22" height="22" alt="Post to Google Buzz!" align="absmiddle" style="position: relative; top: -2px; border: 0" border="0"/>
 112                 </a>
 113
 114
 115                 <a title="Share RGraph on Facebook" href="" onclick="window.open('http://www.facebook.com/sharer.php?u=http://www.rgraph.net&t=RGraph:%20HTML5%20canvas%20graph%20library', 'facebook_window', 'width=500,height=300,top=100,left=100'); return false">
 116                     <img src="../images/facebook.png" width="22" height="22" alt="Post to Facebook" align="absmiddle" style="position: relative; top: -2px; border: 0" border="0"/>
 117                 </a>
 118
 119                 <a href="mailto:share@friendfeed.com" title="Share on FriendFeed">
 120                     <img src="../images/friendfeed.png" width="22" height="22" alt="Share on FriendFeed" border="0" align="absmiddle" />
 121                 </a>
 122
 123                 <a href="http://www.stumbleupon.com/submit?url=http://www.rgraph.net" target="_blank" title="Share on StumbleUpon" >
 124                     <img src="../images/stumble.png" alt="Stumble! this site" width="22" height="22" border="0" align="absmiddle" />
 125                 </a>
 126 -->
 127             </div>
 128     </div>
 129     <!-- /Social networking buttons -->
 130
 131
 132 <div id="breadcrumb">
 133     <a href="../index.html">RGraph: HTML5 canvas graph library</a>
 134     >
 135     Documentation
 136 </div>
 137
 138 <h1>RGraph: HTML5 canvas graph library - Documentation</h1>
 139
 140     <script>
 141         if (RGraph.isIE8()) {
 142             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 graphs, 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://groups.google.com/group/rgraph/browse_thread/thread/c5651ff8c56b8f3c#" target="_blank">here</a> to see some screenshots.</div>');
 143         }
 144     </script>
 145
 146 <p>
 147     The following documentation is available:
 148 </p>
 149
 150     <div style="float: left; width: 202px">
 151         <h4>Chart types</h4>
 152         <ul>
 153             <li><a href="bar.html">Bar chart</a></li>
 154             <li><a href="bipolar.html">Bi-polar chart</a></li>
 155             <li><a href="donut.html">Donut chart</a></li>
 156             <li><a href="funnel.html">Funnel chart</a></li>
 157             <li><a href="gantt.html">Gantt chart</a></li>
 158             <li><a href="hbar.html">Horizontal bar chart</a></li>
 159             <li><a href="hprogress.html">Horizontal progress bar</a></li>
 160             <li><a href="led.html">LED Grid</a></li>
 161             <li><a href="line.html">Line chart</a></li>
 162             <li><a href="meter.html">Meter</a></li>
 163             <li><a href="odo.html">Odometer</a></li>
 164             <li><a href="pie.html">Pie chart</a></li>
 165             <li><a href="rose.html">Rose chart</a></li>
 166             <li><a href="rscatter.html">Radial scatter chart</a></li>
 167             <li><a href="scatter.html">Scatter graph</a></li>
 168             <li><a href="tradar.html">Traditional radar chart</a></li>
 169             <li><a href="vprogress.html">Vertical progress bar</a></li>
 170         </ul>
 171     </div>
 172
 173     <div style="float: left; width: 435px">
 174         <h4>Features</h4>
 175         <ul>
 176             <li><a href="setconfig.html">The RGraph.SetConfig() function</a></li>
 177             <li><a href="keys.html">Examples of keys</a></li>
 178             <li><a href="dynamic.html">Updating your graphs dynamically</a></li>
 179             <li><a href="png.html">Retrieving a PNG of your graph</a></li>
 180             <li><a href="domcontentloaded.html">DOMContentLoaded example</a></li>
 181             <li><a href="events.html">Custom RGraph events</a></li>
 182             <li><a href="adjusting.html">Adjusting your graphs interactively</a></li>
 183             <li><a href="tooltips.html">Using tooltips</a></li>
 184             <li><a href="resizing.html">Resizing your graphs</a></li>
 185             <li><a href="msie.html">Microsoft Internet Explorer support</a></li>
 186             <li><a href="async.html">Asynchronous processing</a></li>
 187             <li><a href="zoom.html">Zooming your graphs</a></li>
 188             <li><a href="annotating.html">Annotating your graphs</a></li>
 189             <li><a href="combine.html">Combining charts</a></li>
 190             <li><a href="external.html">Integrating RGraph with external libraries (ModalDialog)</a></li>
 191             <li><a href="animation.html">Animating your graphs</a></li>
 192             <li><a href="css.html">Available CSS classes</a></li>
 193             <li><a href="color.html">About canvas color definitions</a></li>
 194             <li><a href="context.html">Context menus</a></li>
 195             <li><a href="misc.html">Miscellaneous documentation</a></li>
 196             <li><a href="issues.html">Common issues</a></li>
 197             <li><a href="api.html">API Documentation</a></li>
 198         </ul>
 199     </div>
 200
 201     <div style="float: left; width: 338px">
 202         <h4>Miscellaneous</h4>
 203         <ul>
 204             <li><a href="licensing.html"><b>Licensing FAQs</b></a></li>
 205             <li><a href=".CHANGELOG.txt">The changelog</a></li>
 206             <li><a href=".BC.txt">Backwards compatibility breaks</a></li>
 207         </ul>
 208
 209         <h4>On this page:</h4>
 210
 211         <ul>
 212             <li><a href="#benefits" title="Benefits of HTML5 canvas graphs">Benefits of HTML5 canvas graphs</a></li>
 213             <li><a href="#browser" title="Information about browser support">Browser support</a></li>
 214             <li><a href="#performance" title="Things you may want to look at concerning performance">Improving the performance of your graphs</a></li>
 215             <li><a href="#implementation" title="Implementing RGraph on your website">Implementing RGraph</a></li>
 216             <li><a href="#structure" title="Suggested structure for RGraph">Suggested structure for RGraph</a></li>
 217             <li>
 218                 <a href="#integration" title="Information on integrating RGraph with server side scripting">Integration with server side scripting</a>
 219                 <ul>
 220                     <li><a href="#mysql" title="Integration with PHP &amp; MySQL">Integration with PHP &amp; MySQL</a></li>
 221                     <li><a href="#ajax" title="Making AJAX requests">Making AJAX requests</a></li>
 222                 </ul>
 223             </li>
 224             <li><a href="#support" title="Need support? Get it here">Support forum</a></li>
 225         </ul>
 226     </div>
 227
 228
 229
 230 <!------------------------------------------------------------------------------------------------------------------------>
 231
 232
 233
 234     <br clear="all" />
 235     <hr />
 236
 237
 238
 239     <a name="benefits"></a>
 240     <br />&nbsp;<br />&nbsp;<br />
 241     <h2>Benefits of HTML5 canvas graphs</h2>
 242
 243     <p>
 244         HTML5 introduces a new HTML element - the CANVAS tag. This tag allows for two dimensional drawing easily using Javascript.
 245         This makes it perfect for producing graphs. Because Javascript runs on your users computer, none of the stress on your server
 246         normally associated with producing graphs is incurred. Not only that but because
 247         of the greater processing power that is typically available on users' computers, they will be much faster. And,
 248         because the code can be both compressed (for example if you're using Apache, mod_gzip will do this automatically for you) and
 249         cached, bandwidth usage can be massively reduced. This makes it economically attractive to employ, (ie <b>it can save you
 250         money...</b>).
 251     </p>
 252
 253     <p>
 254         Imagine, you are creating 100,000 graphs a day and the data is such that the resulting graphs cannot be cached. With the RGraph
 255         library you can reduce that figure to zero. All the processing and graph creation is done by each individual client, much like
 256         rendering the HTML you send to them. So you don't have to send any images, you simply send them the Javascript libraries once.
 257         So, much lower bandwidth bills and far less strain on your webserver.
 258     </p>
 259
 260     <p>
 261         And if that wasn't enough, because the graphs are created using Javascript, they will work offline if you view a .html page
 262         on your own PC. Download the archive and see! Useful if you need to do a presentation for example and want to use the same
 263         graph(s) as your website.
 264     </p>
 265
 266     <div>
 267         <div style="width: 45%; background-color: #fff; display: inline; display: inline-block">
 268             <ul>
 269                 <li>Cross browser support.</li>
 270                 <li>17 Different base graph types (<a href="../examples/index.html">Examples</a>).</li>
 271                 <li>Graphs work on and off-line.</li>
 272                 <li>Interactive features.</li>
 273             </ul>
 274         </div>
 275
 276         <div style="width: 45%; display: inline; display: inline-block">
 277             <ul>
 278                 <li>Graphs are created on the client - no server overhead.</li>
 279                 <li>Very easy setup (see <a href="#implementation">Implementing RGraph</a>).</li>
 280                 <li>Fully documented.</a></li>
 281                 <li>Very easy to learn.</li>
 282             </ul>
 283         </div>
 284     </div>
 285
 286
 287     <a name="browser"></a>
 288     <br />&nbsp;<br />&nbsp;<br />
 289     <h2>Browser support</h2>
 290
 291     <p>
 292         Since the graphs are produced using HTML5 features (the new <b>canvas</b> tag), client support is currently:
 293     </p>
 294
 295     <ul>
 296         <li>Mozilla Firefox 3.0+</li>
 297         <li>Google Chrome 1+</li>
 298         <li>Apple Safari 3+</li>
 299         <li>Opera 9.5+</li>
 300         <li>Microsoft Internet Explorer 8+ (see note)</li>
 301         <li>iPhone (text support from iOS v4+)</li>
 302         <li>iPad (text support from iOS v4.2+)</li>
 303     </ul>
 304
 305     <p>
 306         The HTML5 canvas tag is part of the <a href="http://www.w3.org/html/wg/html5/" target="_blank">HTML5 specification</a>,
 307         and all of the above browsers have some sort of support for it.
 308     </p>
 309
 310     <p>
 311         <b>Canvas &amp; Microsoft Internet Explorer (MSIE)</b><br />
 312         Microsoft Internet Explorer 8 doesn't natively support the HTML5 &lt;canvas&gt; tag. To support
 313         MSIE 8 you will need to use either
 314         <a href="http://code.google.com/chrome/chromeframe/" target="_blank">Google Chrome Frame</a> or
 315         <a href="http://code.google.com/p/explorercanvas/" target="_blank">ExCanvas from Google</a>
 316         (which is included in the RGraph archive). Read more about Internet Explorer compatibility
 317         <a href="msie.html">here</a>.
 318
 319         <p />
 320
 321         <span style="color: #090">
 322             Starting with preview 3 <b style="color: black">Microsoft Internet Explorer 9</b> has full support for &lt;canvas&gt;. You can view some screenshots
 323             <a href="http://groups.google.com/group/rgraph/browse_thread/thread/c5651ff8c56b8f3c#" target="_blank">here</a>.
 324             MSIE 6 and 7 are supported by way of Google Chrome Frame.
 325         </span>
 326     </p>
 327
 328     <p>
 329         <b>RGraph and older browsers</b><br />
 330         Older browsers (eg Chrome 1, Firefox 3, Safari 3, Opera 9.5) are supported, however if they don't support the canvas shadow or
 331         text APIs, these will naturally be unavailable. Earlier versions of these browsers may work, but are untested.
 332     </p>
 333
 334     <a name="performance"></a>
 335     <br />&nbsp;<br />&nbsp;<br />
 336     <h2>Improving the performance of your graphs</h2>
 337
 338     <p>
 339         Although performance is excellent, (traditionally your webserver has been
 340         producing all of your graphs, and now the client produces them, and typically only one at a time), you may still want to tune
 341         RGraph further. The biggest thing you can do is use compression, which reduces the initial download time of the libraries, but
 342         there are a number of things you can do:
 343     </p>
 344
 345     <ul>
 346         <li>
 347             <b>Compression</b><br />HTTP compression can dramatically reduce your bandwidth bills and increase the speed
 348             of your website. The RGraph.common.core.js file for example used to be over 100k, but with compression this was reduced
 349             to around 17k. Less than a fifth of the original size! <span style="color: red">If you do only one thing to aid performance,
 350             then it should be this.</span>
 351
 352             <p>
 353                 To achieve this with Apache you have a few options:
 354             </p>
 355
 356             <ul style="list-style-type: disc">
 357                 <li>You can use the Apache module mod_gzip which compresses the libraries on the fly.</li>
 358                 <li>
 359                     You can compress the libraries manually using the gzip command, rename them to remove the .gz suffix
 360                     and add the header using an Apache directive
 361                     (eg <span style="background-color: #C5FFC5; padding: 1px">AddEncoding gzip .js</span>). If you have some sort of
 362                     release process/script, it would make sense to add this to it to automate the procedure.
 363                 </li>
 364             </ul>
 365             <p>
 366         </li>
 367
 368         <li>
 369             <b>Minification</b><br />
 370             Minification reduces the size of the library before compression takes effect, removing unnecessary spaces and comments etc.
 371             A combination of minification and compression will give superb results. For example, before being split up into seperate files,
 372             minification combined with compression reduced the common library from over 100k to roughly 10k (!). There is a PHP shell
 373             script that you can use to minify the libraries in the scripts directory.
 374
 375             <p>
 376                 You can get pre-minified versions of the libraries <a href="http://www.rgraph.net/RGraph.minified.zip">here</a>.
 377             </p>
 378         </li>
 379
 380         <p>
 381
 382         <li>
 383             <b>Pre-emptive caching</b><br />
 384             Slightly different to caching itself, is pre-emptive caching. This involves downloading the libraries before the page that requires
 385             them is shown. This way, they're already in the users browser cache and the graph will subsequently appear to be much much
 386             quicker. An example of this would be having the library included at the bottom of your index page of your website (optionally
 387             with the <b>defer="defer"</b> attribute). The script can be downloaded at will because the page doesn't actually use it, but
 388             for subsequent pages it will already be in the users browser cache.
 389
 390             <p>
 391         </li>
 392
 393         <li>
 394             <b>Caching</b><br />
 395             Since the libraries you're using won't change that often, you can set distant Expires: headers on them, or appropriate
 396             Cache-Control: headers, and the client will not even have to contact your server for it. When you want to make sure
 397             the library is re-downloaded (eg. you update the library), then simply change the filename.
 398
 399             <p>
 400         </li>
 401
 402         <li>
 403             <b>Script tag placement</b><br />
 404             According to <a href="http://developer.yahoo.com/performance/" target="_blank">Yahoo! guidelines</a> placing the &lt;SCRIPT&gt;
 405             tag at the bottom of the page can increase the percieved load time. If you do this, then your graphs should be
 406             created in the window.onload event, otherwise the browser may try to create them without the library
 407             having been loaded, and will therefore subsequently fail.
 408
 409             <p>
 410
 411             You should also consider the effect that this has when your page is rather weighty. If the page is weighty there
 412             will be a small delay before the onload event fires, and therefore creates the graph. This might not be so bad if the
 413             graph is not immediately visible, however if it is then you should carefully consider using the onload event. You
 414             may wish to load the library in the page header, define the canvas tag and then immediately define the javascript that creates the graph. This way
 415             the graph will be created and shown, and then the rest of the page loads. The end result is that your graph
 416             appears to be faster.
 417
 418             <p />
 419
 420             Between the onload event, asychronous Javascript and careful tag placement, you will need to experiment to get the right result
 421             for you.
 422         </li>
 423
 424         <li>
 425             <b>Document structure</b><br />
 426             The structure of your document can have a significant impact on how fast your graphs are displayed. If, for example, you use
 427             tables for layout, this can delay the display of elements that are affected by the size of the table. Where possible, you
 428             should consider trying to convert your layout to DIVs. An example of this is the front page of this website. The graphs
 429             were right aligned using a table as a container. This caused a visible delay when showing them. In this case it was a
 430             simple matter to convert the page to use DIVs, and the page subsequently displays much faster.
 431             <p />
 432         </li>
 433
 434         <li>
 435             <b>Creating your graphs asynchronously</b><br />
 436             Where possible, you may wish to create your graphs asynchronously. This allows the browser to continue rendering the page
 437             immediately after getting to the code that creates the graph. This might not be perceptible if you don't have a lot of
 438             graphs, or your page is small. You can read a little more about this and see example code <a href="async.html">here</a>.
 439
 440             <p />
 441
 442             Note that recent releases of Google Chrome (from a dev release of version 4) have had an issue with creating graphs
 443             asynchronously, which presents itself by not drawing text sometimes (it's not consistent). Simply not using
 444             asynchronous graph production in this case resolves the issue.
 445         </li>
 446
 447         <li>
 448             <b>DOMContentLoaded event</b><br />
 449             Using this event can speed up the display of your graphs signifcantly compared to the more well known <i>onload</i> event.
 450             It is supported by Chrome, Gecko based browsers (ie Firefox), Safari, Opera and Internet Explorer 9. This event fires when
 451             the structure of the page is loaded, but not necessarily the images or CSS. This means that if your page is laden with
 452             images, this event will fire before the onload event, thus creating your graphs quicker. The effect can be very noticeable.
 453
 454             <pre class="code">
 455 function addListener(func)
 456 {
 457     if(window.addEventListener) {
 458         window.addEventListener('DOMContentLoaded', func, false);
 459     } else {
 460         document.attachEvent("onDOMContentLoaded", func);
 461     }
 462 }
 463 </pre>
 464             You can read more about the <i>DOMContentLoaded</i> event on the Mozilla site, <a href="https://developer.mozilla.org/en/Gecko-Specific_DOM_Events" target="_blank">here</a>,
 465             and the Microsoft site <a href="http://ie.microsoft.com/testdrive/HTML5/87DOMContent-Loaded/Default.html" target="_blank">here</a>.
 466             There's an example <a href="domcontentloaded.html">here</a>.
 467             <p />
 468         </li>
 469
 470         <li>
 471             <b>AJAX requests</b><br />
 472             If you can take advantage of AJAX, you can use this method to retrieve data from your server. If, for example, you have a graph that
 473             shows ongoing information, instead of simply refreshing the entire page, you could use an AJAX request to just retrieve the
 474             data that you want and update the graph that way. This reduces the amount of data needed to be transferred, thus reducing the
 475             bandwidth used, and will be quicker than a full page refresh, particularly if your page is weighty. There's a simple AJAX
 476             function that you can use <a href="#ajax">below</a>.
 477             <p />
 478         </li>
 479
 480         <li>
 481             <b>Combining libraries</b><br />
 482             If your performance requirements are extreme, then you may wish to consider combining the libraries into a single file.
 483             This won't save on the size of the individual libraries, but will save on the headers that are sent as part of the response.
 484             If a typical response sends 500 bytes worth of headers, and you send four graph libraries, then combining the libraries
 485             would save 1500 bytes. Multiple factors need to be considered though, including things like caching, which can circumvent
 486             the unneccessary repeated downloading of the libraries.
 487
 488             <p>
 489                 Another effect of combining libraries is reducing the amount of HTTP connections needed to retrieve them. Most browsers
 490                 have a limit on how many connections they can create simultaneously, so if they're not being used to retrieve your
 491                 graph libraries, they can be used for something else. Reducing the number of HTTP connections also eliminates the time
 492                 spent setting up those connections.
 493             </p>
 494         </li>
 495     </ul>
 496
 497     <b>A reasonable performance strategy</b>
 498
 499     <p>
 500         Although there's a lot you can do in regards to performance, a few of the points here will suffice for most
 501         websites:
 502
 503         <ul>
 504             <li>Compression</li>
 505             <li>Minification</li>
 506             <li>Pre-emptive caching</li>
 507             <li>Caching</li>
 508         </ul>
 509
 510         The number one thing you should do is compress your libraries. This has multiple benefits and provides by far the most gain,
 511         effectively for free. Secondly, use the minified libraries. Since you can download them <a href="../RGraph.minified.zip">here</a>,
 512         you might as well use them. Then we have pre-emptive caching. Since most websites won't show graphs on the front page or will
 513         have a login page that is shown before any graphs, this effectively eliminates the graph library download. And lastly caching
 514         should be done as a matter of course. There's no reason to keep downloading the same library so even caching for only 30 minutes
 515         (or the duration of an average visit to your website) will produce results.
 516     </p>
 517
 518     <p>
 519
 520     </p>
 521
 522     <a name="implementation"></a>
 523     <br />&nbsp;<br />&nbsp;<br />
 524     <h2>Implementing RGraph</h2>
 525
 526     <p>
 527         Getting RGraph up and running is very easy and consists of three steps. If you're having trouble I suggest you get hold of a copy of
 528         <a href="http://www.mozilla.com" target="_blank">Firefox</a> along with <a href="http://www.getfirebug.com" target="_blank">Firebug</a> - its
 529         Javascript error console will make debugging your issue much easier. Many problems are down to a library not having been included or
 530         not using the onload event when you need to. You might also benefit from using the <a href="https://addons.mozilla.org/en-US/firefox/addon/60" target="_blank">Web Developer toolbar</a>
 531         for Firefox. This allows you to easily disable caching, thus eliminating any problems that that causes. You could equally use
 532         the Chrome developer tools (CTRL+SHIFT+J), optionally in docked mode, which also provides a good quality Javascript console.
 533     </p>
 534
 535     <ol>
 536         <li>
 537             Include the libraries (put this in your documents &lt;HEAD&gt;):
 538 <pre class="code">
 539 &lt;script src="RGraph.common.core.js"&gt;&lt;/script&gt;
 540
 541 &lt;script src="RGraph.common.adjusting.js"&gt;&lt;/script&gt; &lt;!-- Just needed for adjusting --&gt;
 542 &lt;script src="RGraph.common.annotate.js"&gt;&lt;/script&gt;  &lt;!-- Just needed for annotating --&gt;
 543 &lt;script src="RGraph.common.context.js"&gt;&lt;/script&gt;   &lt;!-- Just needed for context menus --&gt;
 544 &lt;script src="RGraph.common.resizing.js"&gt;&lt;/script&gt;  &lt;!-- Just needed for resizing --&gt;
 545 &lt;script src="RGraph.common.tooltips.js"&gt;&lt;/script&gt;  &lt;!-- Just needed for tooltips --&gt;
 546 &lt;script src="RGraph.common.zoom.js"&gt;&lt;/script&gt;      &lt;!-- Just needed for zoom --&gt;
 547
 548 &lt;script src="RGraph.bar.js"&gt;&lt;/script&gt;              &lt;!-- Just needed for bar graphs --&gt;
 549 &lt;script src="RGraph.bipolar.js"&gt;&lt;/script&gt;          &lt;!-- Just needed for bi-polar graphs --&gt;
 550 &lt;script src="RGraph.funnel.js"&gt;&lt;/script&gt;           &lt;!-- Just needed for funnel charts --&gt;
 551 &lt;script src="RGraph.gantt.js"&gt;&lt;/script&gt;            &lt;!-- Just needed for gantt charts --&gt;
 552 &lt;script src="RGraph.hbar.js"&gt;&lt;/script&gt;             &lt;!-- Just needed for horizontal bar charts --&gt;
 553 &lt;script src="RGraph.hprogress.js"&gt;&lt;/script&gt;        &lt;!-- Just needed for horizontal progress bars --&gt;
 554 &lt;script src="RGraph.led.js"&gt;&lt;/script&gt;              &lt;!-- Just needed for LED charts --&gt;
 555 &lt;script src="RGraph.line.js"&gt;&lt;/script&gt;             &lt;!-- Just needed for line graphs --&gt;
 556 &lt;script src="RGraph.meter.js"&gt;&lt;/script&gt;            &lt;!-- Just needed for meter charts --&gt;
 557 &lt;script src="RGraph.odo.js"&gt;&lt;/script&gt;              &lt;!-- Just needed for odometers --&gt;
 558 &lt;script src="RGraph.pie.js"&gt;&lt;/script&gt;              &lt;!-- Just needed for pie AND donut charts --&gt;
 559 &lt;script src="RGraph.rose.js"&gt;&lt;/script&gt;             &lt;!-- Just needed for rose charts --&gt;
 560 &lt;script src="RGraph.rscatter.js"&gt;&lt;/script&gt;         &lt;!-- Just needed for rscatter charts --&gt;
 561 &lt;script src="RGraph.scatter.js"&gt;&lt;/script&gt;          &lt;!-- Just needed for scatter graphs --&gt;
 562 &lt;script src="RGraph.tradar.js"&gt;&lt;/script&gt;           &lt;!-- Just needed for traditional radar charts --&gt;
 563 &lt;script src="RGraph.vprogress.js"&gt;&lt;/script&gt;        &lt;!-- Just needed for vertical progress bars --&gt;
 564 </pre>
 565         </li>
 566
 567         <li>
 568             Add the canvas tag (put it where you want the graph to appear):
 569 <pre class="code">
 570 &lt;canvas id="myCanvas" width="600" height="250"&gt;[No canvas support]&lt;/canvas&gt;
 571 </pre>
 572         </li>
 573
 574         <li>
 575             Create the graph (since it is using the onload event, you can put this anywhere):
 576
 577 <pre class="code">
 578 &lt;script&gt;
 579     window.onload = function ()
 580     {
 581         var data = [280, 45, 133, 166, 84, 259, 266, 960, 219, 311, 67, 89];
 582
 583         var bar = new RGraph.Bar('myCanvas', data);
 584         bar.Set('chart.labels', ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']);
 585         bar.Set('chart.gutter', 35);
 586         bar.Draw();
 587     }
 588 &lt;/script&gt;
 589 </pre>
 590         </li>
 591     </ol>
 592
 593     <p>
 594         There's also a very <a href="../examples/basic.html">basic example</a> of using RGraph, that does very little. It can be helpful to
 595         illustrate how you can get RGraph up and running.
 596     </p>
 597
 598     <h4>Common library split (17th April 2010)</h4>
 599     <p>
 600         The common library has now been split into separate files. This was because the single common library had become far too large.
 601         If you don't use any of the dynamic features, then you still need to change your code, as <i>RGraph.common.js</i> is now
 602         called <i>RGraph.common.core.js</i>.
 603     </p>
 604
 605     <a name="structure"></a>
 606     <br />&nbsp;<br />&nbsp;<br />
 607     <h2>Suggested structure for RGraph</h2>
 608
 609     <img src="../images/structure.png" width="175" height="205" alt="Suggested structure for RGraph" style="float: right" />
 610
 611     <p>
 612         The suggested layout structure for the RGraph libraries is shown on the right. The <b>www.example.com</b> folder represents
 613         the root/top level of your website with the <b>javascript</b> directory beneath that. The <b>css</b> and <b>images</b>
 614         folders are shown for
 615         illustrative purposes only. If you follow this layout then your URLs to the RGraph libraries would be:
 616     </p>
 617
 618     <p>
 619         <b>/javascript/rgraph/RGraph.common.core.js</b><br />
 620         <b>/javascript/rgraph/RGraph.bar.js</b><br />
 621         etc
 622     </p>
 623
 624     <p>
 625         By using this structure you make RGraph easy to update should you need to, and also keep all the RGraph libraries in
 626         one, easy to find, place.
 627     </p>
 628
 629     <br clear="all" />
 630
 631     <a name="integration"></a>
 632     <br />&nbsp;<br />&nbsp;<br />
 633     <h2>Integration with server side scripting</h2>
 634
 635     <p>
 636         This is a very easy process, as easy as sending content to the browser. All you need to do is make the <i>data</i> variable
 637         (as in the example below) contain the data you want to be displayed. Eg:
 638     </p>
 639
 640     <pre class="code">
 641 &lt;script src="RGraph.common.core.js"&gt;&lt;/script&gt;
 642 &lt;script src="RGraph.line.js"&gt;&lt;/script&gt;
 643
 644 &lt;canvas id="myCanvasTag" width="600" height="200"&gt;[No canvas support]&lt;/canvas&gt;
 645
 646 &lt;script&gt;
 647     data = [78,16,26,23,25,51,34,64,84,84];
 648
 649     line = new RGraph.Line("myCanvasTag", data);
 650     line.Set("chart.labels", ["Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov"]);
 651     line.Draw();
 652 &lt;/script&gt;
 653 </pre>
 654
 655     <p>
 656         To get the above using PHP you could do this:
 657     </p>
 658
 659     <pre class="code">&lt;?php
 660     // This simply makes a string out of the array of data
 661     $myData = join(',', array(78,16,26,23,25,51,34,64,84,84));
 662
 663     // This prints out the required HTML markup
 664     print('&lt;script src="RGraph.common.core.js"&gt;&lt;/script&gt;' . "\n");
 665     print('&lt;script src="RGraph.line.js"&gt;&lt;/script&gt;' . "\n\n");
 666     print('&lt;canvas id="myCanvasTag" width="600" height="200"&gt;[No canvas support]&lt;/canvas&gt;' . "\n\n");
 667     print('&lt;script&gt;' . "\n");
 668     print('    var data = [' . $myData . '];' . "\n\n");
 669     print('    var line = new RGraph.Line("myCanvasTag", data);' . "\n");
 670     print('    line.Set("chart.labels", ["Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov"]);' . "\n");
 671     print('    line.Draw();' . "\n");
 672     print('&lt;/script&gt;');
 673 ?&gt;
 674 </pre>
 675
 676     <p>
 677         Strictly speaking the <span style="font-family: Monospace">var</span> isn't necessary, however if you put the code inside a
 678         function (like window.onload), it's probably best to do so as using <span style="font-family: Monospace">var</span> will
 679         make the variable local, and not global. So doing so will help prevent naming clashes.
 680     </p>
 681
 682
 683     <a name="mysql"></a>
 684     <br />&nbsp;<br />&nbsp;<br />
 685     <h4>Integration with PHP &amp;  MySQL</h4>
 686
 687         <p>
 688             This is a simple matter of formatting what you get back from MySQL into a string, as the MySQL dump and PHP code
 689             below shows (it's based on a database called RGraph_example):
 690         </p>
 691
 692         <pre class="code">
 693 #
 694 # Table structure for table `daily_statistics`
 695 #
 696
 697 CREATE TABLE `daily_statistics` (
 698   `st_day` char(9) NOT NULL,
 699   `st_statistics` tinyint(4) NOT NULL,
 700   UNIQUE KEY `st_day` (`st_day`)
 701 ) ENGINE=MyISAM DEFAULT CHARSET=latin1;
 702
 703 #
 704 # Dumping data for table `daily_statistics`
 705 #
 706
 707 INSERT INTO `daily_statistics` VALUES ('Mon', 124);
 708 INSERT INTO `daily_statistics` VALUES ('Tue', 95);
 709 INSERT INTO `daily_statistics` VALUES ('Wed', 64);
 710 INSERT INTO `daily_statistics` VALUES ('Thu', 94);
 711 INSERT INTO `daily_statistics` VALUES ('Fri', 75);
 712 INSERT INTO `daily_statistics` VALUES ('Sat', 98);
 713 INSERT INTO `daily_statistics` VALUES ('Sun', 84);
 714 </pre>
 715
 716         <pre class="code">
 717 &lt;?php
 718     /**
 719     * Change these to your own credentials
 720     */
 721     $hostname = "localhost";
 722     $username = "root";
 723     $password = "PASSWORD";
 724     $database = "RGraph_example";
 725
 726     $connection = mysql_connect($hostname, $username, $password) OR die('Could not connect to MySQL: ' . mysql_error());
 727     mysql_select_db($database);
 728
 729     $result = mysql_query("SELECT st_day, st_statistics FROM daily_statistics");
 730     if ($result) {
 731
 732         $labels = array();
 733         $data   = array();
 734
 735         while ($row = mysql_fetch_assoc($result)) {
 736             $labels[] = $row["st_day"];
 737             $data[]   = $row["st_statistics"];
 738         }
 739
 740         // Now you can aggregate all the data into one string
 741         $data_string = "[" . join(", ", $data) . "]";
 742         $labels_string = "['" . join("', '", $labels) . "']";
 743     } else {
 744         print('MySQL query failed with error: ' . mysql_error());
 745     }
 746 ?&gt;
 747 &lt;html&gt;
 748 &lt;head&gt;
 749
 750     &lt;!-- Don't forget to update these paths --&gt;
 751
 752     &lt;script src="libraries/RGraph.common.core.js" &gt;&lt;/script&gt;
 753     &lt;script src="libraries/RGraph.line.js" &gt;&lt;/script&gt;
 754
 755 &lt;/head&gt;
 756 &lt;body&gt;
 757
 758     &lt;canvas id="cvs" width="600" height="250"&gt;[No canvas support]&lt;/canvas&gt;
 759     &lt;script&gt;
 760         graph = new RGraph.Line('cvs', &lt;?php print($data_string) ?&gt;);
 761         graph.Set('chart.background.grid.autofit', true);
 762         graph.Set('chart.gutter', 17);
 763         graph.Set('chart.hmargin', 10);
 764         graph.Set('chart.tickmarks', 'endcircle');
 765         graph.Set('chart.labels', &lt;?php print($labels_string) ?&gt;);
 766
 767         graph.context.translate(12, 0);
 768
 769         graph.Draw();
 770     &lt;/script&gt;
 771
 772 &lt;/body&gt;
 773 &lt;/html&gt;
 774 </pre>
 775
 776     <p>
 777         This PHP code provides the data in two strings - <i>$labels_string</i> and <i>$data_string</i>. These variables are then used
 778         in the RGraph code to provide the data and the labels.
 779     </p>
 780
 781     <p><b>Remember:</b></p>
 782
 783     <ul>
 784         <li>Change the database hostname/username/password/database to match your own.</li>
 785         <li>Ensure you have the correct paths to the RGraph libraries.</li>
 786     </ul>
 787
 788     <a name="ajax"></a>
 789     <br />&nbsp;<br />&nbsp;<br />
 790     <h4>Making AJAX requests</h4>
 791
 792         <p style="background-color: #ffa; padding: 3px; border: 1px dashed black">
 793             <b>Note:</b>
 794             It is important that you're careful with types when making AJAX requests. Since the response is initially a string,
 795             and your AJAX function/library may not do conversions for you, you may need to convert these strings to numbers. To
 796             do this you can use the <i>Number()</i> or <i>parseInt()</i> functions. For example:
 797         </p>
 798
 799         <pre class="code">
 800 &lt;script&gt;
 801     num = Number('23');
 802     num = parseInt('43');
 803 &lt;/script&gt;
 804 </pre>
 805
 806         <p>
 807             Here is a simple function that you could use to get data from your server using AJAX:
 808         </p>
 809
 810     <pre class="code">
 811 &lt;script&gt;
 812     /**
 813     * Makes an AJAX call. It calls the given callback (a function) when ready
 814     *
 815     * @param string   url      The URL to retrieve
 816     * @param function callback A function object that is called when the response is ready, there's an example below
 817     *                          called "myCallback".
 818     */
 819     function AjaxCall (url, callback)
 820     {
 821         // Mozilla, Safari, ...
 822         if (window.XMLHttpRequest) {
 823             var httpRequest = new XMLHttpRequest();
 824
 825         // MSIE
 826         } else if (window.ActiveXObject) {
 827             var httpRequest = new ActiveXObject("Microsoft.XMLHTTP");
 828         }
 829
 830         httpRequest.onreadystatechange = callback;
 831
 832         httpRequest.open('GET', url, true);
 833         httpRequest.send();
 834     }
 835
 836
 837     /**
 838     * This sample callback function is called when the data is ready (readyState=4)
 839     */
 840     function myCallback ()
 841     {
 842         if (this.readyState == 4 && this.status == 200) {
 843             // Everything is good, the response is received
 844             alert(this.responseText);
 845         }
 846     }
 847 &lt;/script&gt;
 848 </pre>
 849
 850     <p>And you would use it like this:</p>
 851
 852     <pre class="code">
 853 &lt;script&gt;
 854     AjaxCall('http://www.example.com/getSomething.php', myCallback);
 855 &lt;/script&gt;
 856 </pre>
 857
 858     <p>
 859         There's an example <a href="dynamic.html">here</a> that shows updating your graph dynamically.
 860     </p>
 861
 862
 863     <a name="support"></a>
 864     <br />&nbsp;<br />&nbsp;<br />
 865     <h2>Support forum</h2>
 866
 867     <!-- Google Groups code -->
 868         <table border="0" style="float: right; background-color: #eee; border: 2px dashed gray; padding: 5px" cellspacing=0>
 869             <tr>
 870                 <td>
 871                     <img src="../images/googlegroups.png" height="26" width="132" alt="Google Groups" />
 872                 </td>
 873             </tr>
 874
 875             <tr>
 876                 <td style="padding-left: 5px">
 877                     <b>Subscribe to RGraph support</b>
 878                 </td>
 879             </tr>
 880
 881             <tr>
 882                 <td style="padding-left: 5px;">
 883                     <form action="http://groups.google.com/group/rgraph/boxsubscribe" method="get">
 884                         Email: <input type=text name=email>
 885                         <input type=submit name="sub" value="Subscribe">
 886                     </form>
 887                 </td>
 888             </tr>
 889
 890             <tr>
 891                 <td align="right">
 892                     <a href="http://groups.google.com/group/rgraph/topics?gvc=2" target="_blank">Visit this group</a>
 893                 </td>
 894             </tr>
 895
 896             <tr>
 897                 <td>
 898                     <a href="http://groups.google.com/group/rgraph/feed/rss_v2_0_msgs.xml" target="_blank"><img src="../images/rss.png" alt="RSS Feed" width="39" height="23" /></a>
 899                     <a href="http://groups.google.com/group/rgraph/feed/atom_v1_0_msgs.xml" target="_blank"><img src="../images/atom.png" alt="Atom XML Feed" width="45" height="23"  /></a>
 900                 </td>
 901             </tr>
 902         </table>
 903     <!-- End of Google Groups code -->
 904
 905     <p>
 906         Support is available via a Google Groups forum. If you think that the issue you have is common, try the <a href="issues.html">issues</a>
 907         page first, and then try searching the forum in case your question has been answered previously. If that all yields nothing,
 908         post a question to the forum.
 909     </p>
 910
 911     <p>
 912         If you want to keep up-to-date on RGraph, then subscribe to the group, as I post update notifications here. You can also follow me on
 913         <a href="http://twitter.com/_rgraph"><b>Twitter</b></a>. I post update notifications here along with HTML5 related news.
 914     </p>
 915
 916     <br />
 917     <br />
 918
 919 </body>
 920 </html>