plotkit_v091/doc/PlotKit.QuickStart.txt

   1 {% extends "basex.html" %}
   2 {% load markup %}
   3 {% block pageid %}code{% endblock %}
   4 {% block title %}PlotKit Quick Start{% endblock %}
   5 {% block headers %}
   6 <script type="text/javascript" src="/js/mochi/MochiKit.js"></script>
   7 <script type="text/javascript" src="/js/plotkit/Base.js"></script>
   8 <script type="text/javascript" src="/js/plotkit/Layout.js"></script>
   9 <script type="text/javascript" src="/js/plotkit/Canvas.js"></script>
  10 <script type="text/javascript" src="/js/plotkit/SweetCanvas.js"></script>
  11 <link href="doc.css" media="screen" rel="stylesheet" type="text/css" />
  12 {% endblock %}
  13
  14
  15 {% block content %}
  16 <div class="page doc">
  17 {% filter markdown %}
  18 PlotKit Quick Start
  19 ===================
  20
  21 This is just a quick guide on how to get started with PlotKit. If you
  22 want to delve in deeper, be sure to check out the
  23 [documentation][docs].
  24
  25 Canvas or SVG
  26 =============
  27
  28 Before we start, you should know a little about HTML Canvas and SVG
  29 support in the real browser world. For a more indepth coverage, please
  30 check the [SVG/Canvas Browser Support Status][Browser].
  31
  32 Basically, Canvas and SVG have similar support across modern
  33 browsers. Canvas is supported by Opera 9, Safari 2 and Firefox 1.5,
  34 which probably only accounts for 10% of browsers. PlotKit also supports
  35 a degraded Emulated Canvas mode under IE which means you can achieve
  36 nearly 90% browser support using this technology.
  37
  38 However, the future is in SVG where Firefox 1.5 and Opera 8 have
  39 support it, and IE6 with the Adobe SVG Viewer (ASV) install means you
  40 get around the same coverage as HTML Canvas.
  41
  42 PlotKit plans to support both to maximise compatiblity. Canvas has a
  43 simplier rendering engine, but can do the equivalent to what SVG can
  44 apart from animation. SVG has wider support, but is more complex and
  45 support for key features varies widely across different
  46 implementations.
  47
  48 Graphing with Canvas
  49 ====================
  50
  51 Download the latest [PlotKit][] and [MochiKit][] and extract it on to
  52 your web server and make sure ``plotkit-0.8/PlotKit`` and
  53 ``mochikit/MochiKit`` is visible.
  54
  55 Preparing the HTML
  56 ------------------
  57
  58 Add the script headers for PlotKit to work.
  59
  60     <script type="text/javascript" src="/mochikit/MochiKit.js"></script>
  61     <script type="text/javascript" src="/plotkit/Base.js"></script>
  62     <script type="text/javascript" src="/plotkit/Layout.js"></script>
  63     <script type="text/javascript" src="/plotkit/Canvas.js"></script>
  64     <script type="text/javascript" src="/plotkit/SweetCanvas.js"></script>
  65
  66 MochiKit.js is an autoloader for all the elements of MochiKit. You can
  67 reduce the size of it by making your own packed version or just
  68 including the script headers individually.
  69
  70 The other four PlotKit javascript files deal with some basic
  71 functionality, the layout engine and two renderers, Canvas and
  72 SweetCanvas.
  73
  74 Now we add the ``<canvas>`` tag to where we want the graph to
  75 appear. Note PlotKit __requires__ the ``<canvas>`` tag is enclosed
  76 inside a <div> tags for labels to work.
  77
  78      <div><canvas id="graph" height="300" width="300"></canvas></div>
  79
  80 This will create a blank canvas of 300 by 300 pixels.
  81
  82 Javascript
  83 ----------
  84
  85 There are only two simple steps to draw a chart, first is the create a
  86 layout with our data and second is to create the renderer. So lets
  87 start off with creating the layout.
  88
  89 ### Layout and Data
  90
  91     var layout = new PlotKit.Layout("bar", {});
  92     layout.addDataset("sqrt", [[0, 0], [1, 1], [2, 1.414], [3, 1.73], [4, 2]]);
  93     layout.evaluate();
  94
  95 There, it is that simple. Lets explain what each line is doing:
  96
  97 1. ``var layout = new PlotKit.Layout("bar", {});``
  98
  99     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.
 100
 101 2. ``layout.addDataset("sqrt", [[0, 0], [1, 1]...)``
 102
 103     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.
 104
 105     Note that PlotKit does not deal with negative numbers at the moment.
 106
 107 3. ``layout.evaluate();``
 108
 109     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.
 110
 111 ### Renderer
 112
 113      var canvas = MochiKit.DOM.getElement("graph");
 114      var plotter = new PlotKit.SweetCanvasRenderer(canvas, layout, {});
 115      plotter.render();
 116
 117 1.  ``var canvas = MochiKit.DOM.getElement("graph");``
 118
 119     This line will get the HTML element we defined earlier.
 120
 121 2.  ``var plotter =  new PlotKit.SweetCanvasRenderer(canvas, layout, {});``
 122
 123     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.
 124
 125 3.  ``plotter.render()``
 126
 127     This line will render the graph.
 128
 129 ### Putting it altogether
 130
 131     function drawGraph() {
 132         var layout = new PlotKit.Layout("bar", {});
 133         layout.addDataset("sqrt", [[0, 0], [1, 1], [2, 1.414], [3, 1.73], [4, 2]]);
 134         layout.evaluate();
 135         var canvas = MochiKit.DOM.getElement("graph");
 136         var plotter = new PlotKit.SweetCanvasRenderer(canvas, layout, {});
 137         plotter.render();
 138     }
 139     MochiKit.DOM.addLoadEvent(drawGraph);
 140
 141 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.
 142
 143 See this in an [HTML example here][example1].
 144
 145 ### Additional Options
 146
 147 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:
 148
 149     var options = {
 150        "IECanvasHTC": "/plotkit/iecanvas.htc",
 151        "colorScheme": PlotKit.Base.palette(PlotKit.Base.baseColors()[0]),
 152        "padding": {left: 0, right: 0, top: 10, bottom: 30},
 153        "xTicks": [{v:0, label:"zero"},
 154               {v:1, label:"one"},
 155               {v:2, label:"two"},
 156               {v:3, label:"three"},
 157               {v:4, label:"four"}],
 158        "drawYAxis": false
 159     };
 160
 161     function drawGraph() {
 162         var layout = new PlotKit.Layout("bar", options);
 163         layout.addDataset("sqrt", [[0, 0], [1, 1], [2, 1.414], [3, 1.73], [4, 2]]);
 164         layout.evaluate();
 165         var canvas = MochiKit.DOM.getElement("graph");
 166         var plotter = new PlotKit.SweetCanvasRenderer(canvas, layout, options);
 167         plotter.render();
 168     }
 169     MochiKit.DOM.addLoadEvent(drawGraph);
 170
 171
 172 Here we define some additional options to affect how our graph is rendered.
 173
 174 1. First line defines where the ``IECanvasHTC`` behaviour file is so that we can have IE support.
 175 2. 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.
 176 3. Third line defines some custom labels we would like by giving the mapping from X value to label.
 177 4. Fourth line tells the renderer not to draw the Y axis.
 178
 179 Demonstration
 180 =============
 181
 182 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.
 183
 184 ### Bar charts
 185
 186 <div>
 187 <div style="float: left; padding-right: 5px;" width="300" height="300"><img src="barsample.png" width="300" height="300" alt="screenshot of graph" /></div>
 188 <div style="float: left; padding-left: 5px;" width="300" height="300"><canvas id="bargraph" width="300" height="300"></canvas></div>
 189 <div style="clear: both; height: 1px; width: 1px;">&nbsp</div>
 190 </div>
 191
 192 ### Pie Charts
 193
 194 <div>
 195 <div style="float: left; padding-right: 5px;" width="300" height="300"><img src="piesample.png" width="300" height="300" alt="screenshot of graph" /></div>
 196 <div style="float: left; padding-left: 5px;" width="300" height="300"><canvas id="piegraph" width="300" height="300"></canvas></div>
 197 <div style="clear: both; height: 1px; width: 1px;">&nbsp</div>
 198 </div>
 199
 200 Author
 201 ======
 202
 203 Alastair Tse - Last Updated: 17th March 2006
 204
 205 [docs]: PlotKit.html
 206 [Browser]: SVGCanvasCompat.html
 207 [PlotKit]: http://www.liquidx.net/plotkit/
 208 [MochiKit]: http://www.mochikit.com/
 209
 210 {% endfilter %}
 211 </div>
 212 <script type="text/javascript">
 213 <!--
 214
 215 var options = {
 216    "IECanvasHTC": "../plotkit/iecanvas.htc",
 217    "colorScheme": PlotKit.Base.palette(PlotKit.Base.baseColors()[0]),
 218    "padding": {left: 10, right: 10, top: 10, bottom: 30},
 219    "xTicks": [{v:0, label:"zero"},
 220               {v:1, label:"one"},
 221               {v:2, label:"two"},
 222               {v:3, label:"three"},
 223               {v:4, label:"four"}],
 224    "drawYAxis": false,
 225    "pieRadius": 0.35
 226 };
 227
 228
 229 function drawBarGraph() {
 230    var layout = new PlotKit.Layout("bar", options);
 231    layout.addDataset("sqrt", [[0, 0], [1, 1], [2, 1.414], [3, 1.73], [4, 2]]);
 232    layout.evaluate();
 233    var canvas = MochiKit.DOM.getElement("bargraph");
 234    var plotter = new PlotKit.SweetCanvasRenderer(canvas, layout, options);
 235    plotter.render();
 236 }
 237 MochiKit.DOM.addLoadEvent(drawBarGraph);
 238
 239 function drawPieGraph() {
 240    var layout = new PlotKit.Layout("pie", options);
 241    layout.addDataset("sqrt", [[0, 0], [1, 1], [2, 1.414], [3, 1.73], [4, 2]]);
 242    layout.evaluate();
 243    var canvas = MochiKit.DOM.getElement("piegraph");
 244    var plotter = new PlotKit.SweetCanvasRenderer(canvas, layout, options);
 245    plotter.render();
 246 }
 247
 248 // Damn opera 9 has a bug with javascript subclassing??
 249 // but works in sweet.html, grr!!
 250 if (navigator.userAgent.toLowerCase().indexOf("opera") == -1) {
 251    MochiKit.DOM.addLoadEvent(drawPieGraph);
 252 }
 253
 254 //-->
 255 </script>
 256 {% endblock %}