plotkit_v091/doc/PlotKit.QuickStart.html

   1
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en" >
   4 <head>
   5         <title>PlotKit Quick Start | liquidx</title>
   6         <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
   7         <link href="http://media.liquidx.net/css/x_general.css" media="screen" rel="Stylesheet" type="text/css" />
   8         <link href="http://media.liquidx.net/css/x_header.css" media="screen" rel="Stylesheet" type="text/css" />
   9         <link href="http://media.liquidx.net/css/x_layout.css" media="screen" rel="Stylesheet" type="text/css" />
  10         <link href="http://media.liquidx.net/css/x_blocks.css" media="screen" rel="Stylesheet" type="text/css" />
  11         <link rel="icon" href="/favicon.png" type="image/x-png">
  12         <link rel="shortcut icon" href="/favicon.png" type="image/x-png">
  13         <!--[if lt IE 7.]>
  14         <script defer type="text/javascript" src="http://media.liquidx.net/js/pngfix.js"></script>
  15         <![endif]-->
  16
  17 <script type="text/javascript" src="/js/mochi/MochiKit.js"></script>
  18 <script type="text/javascript" src="/js/plotkit/Base.js"></script>
  19 <script type="text/javascript" src="/js/plotkit/Layout.js"></script>
  20 <script type="text/javascript" src="/js/plotkit/Canvas.js"></script>
  21 <script type="text/javascript" src="/js/plotkit/SweetCanvas.js"></script>
  22 <link href="doc.css" media="screen" rel="stylesheet" type="text/css" />
  23
  24 </head>
  25
  26 <body>
  27     <div id="header">
  28         <div id="logo"><a href="http://www.liquidx.net/"><img src="http://media.liquidx.net/imgx/logo.png" width="256" height="128" alt="liquidx.net" /></a></div>
  29                 <div id="menu-hack">
  30                         <div id="menu-l"><img src="http://media.liquidx.net/imgx/menu_l.png" width="17" height="28" alt="menu cap" /></div><div id="menu-r"><img src="http://media.liquidx.net/imgx/menu_r.png" width="17" height="28" alt="menu cap" /></div>
  31             <div id="menu-main">
  32                         <ul id="menu" class="code">
  33                         <li class="tab" id="blog"><a href="http://www.liquidx.net/" title="blog/home">blog</a></li>
  34                         <li class="tab" id="code"><a href="http://www.liquidx.net/code/" title="software i have written">software</a></li>
  35                         <li class="tab" id="dev"><a href="http://projects.liquidx.net/" title="source code for my open source projects">dev</a></li>
  36                         <li class="tab" id="photos"><a href="http://al.tse.id.au/gallery/" title="photos and videos">photos</a></li>
  37                         <li class="tab" id="research"><a href="http://al.tse.id.au/research/" title="research profile">research</a></li>
  38                         <li class="tab" id="links"><a href="http://www.liquidx.net/links/" title="my bookmarks">linkblog</a></li>
  39                         <li class="tab" id="stats"><a href="http://stats.liquidx.net/" title="stats for various parts of my website">stats</a></li>
  40                         <li class="tab" id="status"><a href="http://www.liquidx.net/status/" title="weather report for alastair">status</a></li>
  41                         <li class="tab" id="about"><a href="http://al.tse.id.au/" title="about alastair tse">aboutme</a></li>
  42                         </ul>
  43                 </div>
  44         </div>
  45                 <div id="quickbuttons">
  46                         <span class="quickbutton"><a href="http://www.liquidx.net/albumartwidget/"><img src="http://media.liquidx.net/imgx/quick_widget.png" alt="album art widget" /></a></span>
  47                         <span class="quickbutton"><a href="http://www.liquidx.net/plotkit/"><img src="http://media.liquidx.net/imgx/quick_plotkit.png" alt="plotkit" /></a></span>
  48                         <span class="quickbutton"><a href="http://www.liquidx.net/fruity/"><img src="http://media.liquidx.net/imgx/quick_fruity.png" alt="fruity" /></a></span>
  49                 </div>
  50
  51         </div>
  52
  53     <div id="body">
  54 <div class="page doc">
  55
  56
  57 <h1> PlotKit Quick Start</h1>
  58 <p>This is just a quick guide on how to get started with PlotKit. If you
  59    want to delve in deeper, be sure to check out the
  60    <a href="PlotKit.html">documentation</a>.
  61 </p>
  62
  63 <h1> Canvas or SVG</h1>
  64 <p>Before we start, you should know a little about HTML Canvas and SVG
  65    support in the real browser world. For a more indepth coverage, please
  66    check the <a href="SVGCanvasCompat.html">SVG/Canvas Browser Support Status</a>.
  67 </p>
  68 <p>Basically, Canvas and SVG have similar support across modern
  69    browsers. Canvas is supported by Opera 9, Safari 2 and Firefox 1.5,
  70    which probably only accounts for 10% of browsers. PlotKit also supports
  71    a degraded Emulated Canvas mode under IE which means you can achieve
  72    nearly 90% browser support using this technology.
  73 </p>
  74 <p>However, the future is in SVG where Firefox 1.5 and Opera 8 have
  75    support it, and IE6 with the Adobe SVG Viewer (ASV) install means you
  76    get around the same coverage as HTML Canvas.
  77 </p>
  78 <p>PlotKit plans to support both to maximise compatiblity. Canvas has a
  79    simplier rendering engine, but can do the equivalent to what SVG can
  80    apart from animation. SVG has wider support, but is more complex and
  81    support for key features varies widely across different
  82    implementations.
  83 </p>
  84
  85 <h1> Graphing with Canvas</h1>
  86 <p>Download the latest <a href="http://www.liquidx.net/plotkit/">PlotKit</a> and <a href="http://www.mochikit.com/">MochiKit</a> and extract it on to
  87    your web server and make sure <code>plotkit-0.8/PlotKit</code> and
  88    <code>mochikit/MochiKit</code> is visible.
  89 </p>
  90
  91 <h2> Preparing the HTML</h2>
  92 <p>Add the script headers for PlotKit to work.
  93 </p>
  94 <pre><code>&lt;script type=&quot;text/javascript&quot; src=&quot;/mochikit/MochiKit.js&quot;&gt;&lt;/script&gt;
  95 &lt;script type=&quot;text/javascript&quot; src=&quot;/plotkit/Base.js&quot;&gt;&lt;/script&gt;
  96 &lt;script type=&quot;text/javascript&quot; src=&quot;/plotkit/Layout.js&quot;&gt;&lt;/script&gt;
  97 &lt;script type=&quot;text/javascript&quot; src=&quot;/plotkit/Canvas.js&quot;&gt;&lt;/script&gt;
  98 &lt;script type=&quot;text/javascript&quot; src=&quot;/plotkit/SweetCanvas.js&quot;&gt;&lt;/script&gt;
  99 </code></pre><p>MochiKit.js is an autoloader for all the elements of MochiKit. You can
 100    reduce the size of it by making your own packed version or just
 101    including the script headers individually.
 102 </p>
 103 <p>The other four PlotKit javascript files deal with some basic
 104    functionality, the layout engine and two renderers, Canvas and
 105    SweetCanvas.
 106 </p>
 107 <p>Now we add the <code>&lt;canvas&gt;</code> tag to where we want the graph to
 108    appear. Note PlotKit <strong>requires</strong> the <code>&lt;canvas&gt;</code> tag is enclosed
 109    inside a <div> tags for labels to work.
 110 </p>
 111 <pre><code> &lt;div&gt;&lt;canvas id=&quot;graph&quot; height=&quot;300&quot; width=&quot;300&quot;&gt;&lt;/canvas&gt;&lt;/div&gt;
 112 </code></pre><p>This will create a blank canvas of 300 by 300 pixels.
 113 </p>
 114
 115 <h2> Javascript</h2>
 116 <p>There are only two simple steps to draw a chart, first is the create a
 117    layout with our data and second is to create the renderer. So lets
 118    start off with creating the layout.
 119 </p>
 120
 121 <h3> Layout and Data</h3>
 122 <pre><code>var layout = new PlotKit.Layout(&quot;bar&quot;, {});
 123 layout.addDataset(&quot;sqrt&quot;, [[0, 0], [1, 1], [2, 1.414], [3, 1.73], [4, 2]]);
 124 layout.evaluate();
 125 </code></pre><p>There, it is that simple. Lets explain what each line is doing:
 126 </p>
 127 <ol>
 128  <li><p> <code>var layout = new PlotKit.Layout(&quot;bar&quot;, {});</code>
 129 </p>
 130 <p>We create a new layout object, and tell it that we want a bar chart in the first parameter. The second parameter allows us to pass additional options, which we will go on to later. It can be left null, or in this case just an empty array.
 131 </p>
 132
 133  </li>
 134
 135  <li><p> <code>layout.addDataset(&quot;sqrt&quot;, [[0, 0], [1, 1]...)</code>
 136 </p>
 137 <p>This will add a new dataset to the layout. You can add multiple datasets by specifying a different name in the first parameter for each dataset. The dataset consists of an array of (x, y) values. These must be numeric, either floating point or integers.
 138 </p>
 139 <p>Note that PlotKit does not deal with negative numbers at the moment.
 140 </p>
 141
 142  </li>
 143
 144  <li><p> <code>layout.evaluate();</code>
 145 </p>
 146 <p>This will be the last command you make on the layout before passing it to the renderer. This will tell the layout to calculate the layout of the chart so the renderer can draw it. It is an expensive operation, so do not call it frequently, only unless the data or options have been changed.
 147 </p>
 148
 149  </li>
 150 </ol>
 151
 152 <h3> Renderer</h3>
 153 <pre><code> var canvas = MochiKit.DOM.getElement(&quot;graph&quot;);
 154  var plotter = new PlotKit.SweetCanvasRenderer(canvas, layout, {});
 155  plotter.render();
 156 </code></pre><ol>
 157  <li><p> <code>var canvas = MochiKit.DOM.getElement(&quot;graph&quot;);</code>
 158 </p>
 159 <p>This line will get the HTML element we defined earlier.
 160 </p>
 161
 162  </li>
 163
 164  <li><p> <code>var plotter =  new PlotKit.SweetCanvasRenderer(canvas, layout, {});</code>
 165 </p>
 166 <p>This will create the renderer to work on the object passed, and also with the data in the layout we created earlier. Again, the third parameter here is for options to relates to the look of the graph. We will show you some things you can do with this in the following section.
 167 </p>
 168
 169  </li>
 170
 171  <li><p> <code>plotter.render()</code>
 172 </p>
 173 <p>This line will render the graph.
 174 </p>
 175
 176  </li>
 177 </ol>
 178
 179 <h3> Putting it altogether</h3>
 180 <pre><code>function drawGraph() {
 181     var layout = new PlotKit.Layout(&quot;bar&quot;, {});
 182     layout.addDataset(&quot;sqrt&quot;, [[0, 0], [1, 1], [2, 1.414], [3, 1.73], [4, 2]]);
 183     layout.evaluate();
 184     var canvas = MochiKit.DOM.getElement(&quot;graph&quot;);
 185     var plotter = new PlotKit.SweetCanvasRenderer(canvas, layout, {});
 186     plotter.render();
 187 }
 188 MochiKit.DOM.addLoadEvent(drawGraph);
 189 </code></pre><p>This is a sample of what you would use to plot the graph of sqare roots for 0 to 4. Make sure you plot the graph on the load event because the DOM will not be ready if when the Javascript is first loaded.
 190 </p>
 191 <p>See this in an [HTML example here][example1].
 192 </p>
 193
 194 <h3> Additional Options</h3>
 195 <p>We mentioned that both the layout and renderer may take some additional options. In order to take advantage of that, we can use a simple options dictionary to store options for both layout and the renderer, in this way:
 196 </p>
 197 <pre><code>var options = {
 198    &quot;IECanvasHTC&quot;: &quot;/plotkit/iecanvas.htc&quot;,
 199    &quot;colorScheme&quot;: PlotKit.Base.palette(PlotKit.Base.baseColors()[0]),
 200    &quot;padding&quot;: {left: 0, right: 0, top: 10, bottom: 30},
 201    &quot;xTicks&quot;: [{v:0, label:&quot;zero&quot;},
 202           {v:1, label:&quot;one&quot;},
 203           {v:2, label:&quot;two&quot;},
 204           {v:3, label:&quot;three&quot;},
 205           {v:4, label:&quot;four&quot;}],
 206    &quot;drawYAxis&quot;: false
 207 };
 208
 209 function drawGraph() {
 210     var layout = new PlotKit.Layout(&quot;bar&quot;, options);
 211     layout.addDataset(&quot;sqrt&quot;, [[0, 0], [1, 1], [2, 1.414], [3, 1.73], [4, 2]]);
 212     layout.evaluate();
 213     var canvas = MochiKit.DOM.getElement(&quot;graph&quot;);
 214     var plotter = new PlotKit.SweetCanvasRenderer(canvas, layout, options);
 215     plotter.render();
 216 }
 217 MochiKit.DOM.addLoadEvent(drawGraph);
 218 </code></pre><p>Here we define some additional options to affect how our graph is rendered.
 219 </p>
 220 <ol>
 221  <li>
 222      First line defines where the <code>IECanvasHTC</code> behaviour file is so that we can have IE support.
 223  </li>
 224
 225  <li>
 226      Second line defines a new colorScheme to use. Here we are just using another preset color scheme that creates a palette out of the 6th preset base colour.
 227  </li>
 228
 229  <li>
 230      Third line defines some custom labels we would like by giving the mapping from X value to label.
 231  </li>
 232
 233  <li>
 234      Fourth line tells the renderer not to draw the Y axis.
 235  </li>
 236 </ol>
 237
 238 <h1> Demonstration</h1>
 239 <p>To show you that is how it works, below is the graph defined exactly how it is presented in this quick start guide. On the left is a PNG of what you should expect and on the right is what it actually renders to.
 240 </p>
 241
 242 <h3> Bar charts</h3>
 243 <div>
 244 <div style="float: left; padding-right: 5px;" width="300" height="300"><img src="barsample.png" width="300" height="300" alt="screenshot of graph" /></div>
 245 <div style="float: left; padding-left: 5px;" width="300" height="300"><canvas id="bargraph" width="300" height="300"></canvas></div>
 246 <div style="clear: both; height: 1px; width: 1px;">&nbsp</div>
 247 </div>
 248
 249
 250 <h3> Pie Charts</h3>
 251 <div>
 252 <div style="float: left; padding-right: 5px;" width="300" height="300"><img src="piesample.png" width="300" height="300" alt="screenshot of graph" /></div>
 253 <div style="float: left; padding-left: 5px;" width="300" height="300"><canvas id="piegraph" width="300" height="300"></canvas></div>
 254 <div style="clear: both; height: 1px; width: 1px;">&nbsp</div>
 255 </div>
 256
 257
 258 <h1> Author</h1>
 259 <p>Alastair Tse - Last Updated: 17th March 2006
 260 </p>
 261
 262
 263 </div>
 264 <script type="text/javascript">
 265 <!--
 266
 267 var options = {
 268    "IECanvasHTC": "../plotkit/iecanvas.htc",
 269    "colorScheme": PlotKit.Base.palette(PlotKit.Base.baseColors()[0]),
 270    "padding": {left: 10, right: 10, top: 10, bottom: 30},
 271    "xTicks": [{v:0, label:"zero"},
 272               {v:1, label:"one"},
 273               {v:2, label:"two"},
 274               {v:3, label:"three"},
 275               {v:4, label:"four"}],
 276    "drawYAxis": false,
 277    "pieRadius": 0.35
 278 };
 279
 280
 281 function drawBarGraph() {
 282    var layout = new PlotKit.Layout("bar", options);
 283    layout.addDataset("sqrt", [[0, 0], [1, 1], [2, 1.414], [3, 1.73], [4, 2]]);
 284    layout.evaluate();
 285    var canvas = MochiKit.DOM.getElement("bargraph");
 286    var plotter = new PlotKit.SweetCanvasRenderer(canvas, layout, options);
 287    plotter.render();
 288 }
 289 MochiKit.DOM.addLoadEvent(drawBarGraph);
 290
 291 function drawPieGraph() {
 292    var layout = new PlotKit.Layout("pie", options);
 293    layout.addDataset("sqrt", [[0, 0], [1, 1], [2, 1.414], [3, 1.73], [4, 2]]);
 294    layout.evaluate();
 295    var canvas = MochiKit.DOM.getElement("piegraph");
 296    var plotter = new PlotKit.SweetCanvasRenderer(canvas, layout, options);
 297    plotter.render();
 298 }
 299
 300 // Damn opera 9 has a bug with javascript subclassing??
 301 // but works in sweet.html, grr!!
 302 if (navigator.userAgent.toLowerCase().indexOf("opera") == -1) {
 303    MochiKit.DOM.addLoadEvent(drawPieGraph);
 304 }
 305
 306 //-->
 307 </script>
 308 </div>
 309
 310
 311
 312
 313     <div id="footer">
 314                 <div class="block">
 315                         <h3>Syndication Feeds:</h3>
 316                         <p>
 317                                 <ul class="tiny">
 318                                         <li><a href="http://www.liquidx.net/blog/feed/atom/" class="feed" title="feed for all posts on liquidx.net"><img src="http://media.liquidx.net/imgx/feed.gif" class="feed" alt="feed" />Atom Feed for the Blog Entries</a></li>
 319                                         <li><a href="http://www.liquidx.net/blog/feed/rss/" class="feed" title="feed for all posts on liquidx.net"><img src="http://media.liquidx.net/imgx/feed.gif" class="feed" alt="feed" />RSS Feed for the Blog Entries</a></li>
 320                                         <li><a href="http://www.liquidx.net/comments/feed/atom/" class="feed" title="feed for all posts on liquidx.net"><img src="http://media.liquidx.net/imgx/feed.gif" class="feed" alt="feed" />Feed for All Comments</a></li>
 321                                         <li><a href="http://www.liquidx.net/links/feed/atom/" class="feed" title="feed for all bookmarked links"><img src="http://media.liquidx.net/imgx/feed.gif" class="feed" alt="feed" />Feed for Links</a></li>
 322                                 </ul>
 323                         </p>
 324                 </div>
 325                 <div class="block">
 326                         <h3>About this site:</h3>
 327                         <p>Content on this site is licensed under <a href="http://creativecommons.org/licenses/by/2.5/">CC By Attribution</a> unless otherwise specified.
 328                         Copyright (c) 2002-2006, <a href="http://al.tse.id.au/">Alastair Tse</a>.</p>
 329                         <p>For more information, see <a href="http://al.tse.id.au/">al.tse.id.au</a>.</p>
 330                         <p><script type="text/javascript" src="http://technorati.com/embed/itwctkzez.js"></script></p>
 331                 </div>
 332                 <div class="block">
 333                         <h3>Is Made Possible By:</h3>
 334                         <p>
 335                         <dl>
 336                                 <dt><a href="http://ecto.kung-foo.tv/" class="clean">ecto</a>. </dt>
 337                                 <dd>Blogging client for Mac</dd>
 338                                 <dt><a href="http://djangoproject.com/" class="clean">Django</a>. </dt>
 339                                 <dd>Python Web Framework</dd>
 340                                 <dt><a href="http://www.lighttpd.net/" class="clean">lighttpd</a>. </dt>
 341                                 <dd>Really Fast Web Server</dd>
 342                                 <dt><a href="http://www.saddi.com/software/flup/" class="clean">flup</a>. </dt>
 343                                 <dd>FastCGI for Python</dd>
 344                         </dl>
 345                         </p>
 346                 </div>
 347         <div class="block">
 348             <h3>Search My Sites:</h3>
 349             <p>
 350            <div style='margin: 10px; text-align: center; width: 160px;'><form action='http://www.rollyo.com/search.html' ><fieldset style='margin: 0; padding: 4px 0 0 0; height: 60px; border: none; background: url(http://rollyo.com/remote/togo-bg4.png) no-repeat top left;'><div style="position: absolute; float:left; z-index:99; width: 46px; height: 50px;"><a href="http://rollyo.com"><img style="border: none;" height="50" width="46" src="http://rollyo.com/remote/x.gif"></a></div> <input type='text' size='30' style='float: left; width: 90px; margin: 2px 0 0 48px; padding: 0; font-size: 12px;' name='q' value='Search...' onclick='this.value="";' /><br /> <select name='sid' style='float: left; width: 78px; height: 15px; margin: 12px 0 0 46px; font-size: 7pt; padding: 0;'><option value='106081' selected='selected'>liquidx</option><option value='web'>Search The Web</option></select><input type='image' src='http://rollyo.com/remote/btn-togo.png' alt='Go' style='margin: 12px 0 0 3px; float: left;' /><input type='hidden' name='togo-v' value='1' /></fieldset></form></div>
 351                </p>
 352           </div>
 353
 354
 355                 <div class="clear">&nbsp;</div>
 356
 357     </div>
 358
 359
 360
 361    <script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script>
 362    <script type="text/javascript">
 363    _uacct = "UA-58117-1";
 364    urchinTracker();
 365    </script>
 366
 367 </body>
 368 </html>