maglev-webtools 0.2.1 → 1.0

data/public/flot/PLUGINS.txt

@@ -0,0 +1,137 @@
+Writing plugins
+---------------
+
+All you need to do to make a new plugin is creating an init function
+and a set of options (if needed), stuffing it into an object and
+putting it in the $.plot.plugins array. For example:
+
+  function myCoolPluginInit(plot) {
+    plot.coolstring = "Hello!";
+  };
+
+  $.plot.plugins.push({ init: myCoolPluginInit, options: { ... } });
+
+  // if $.plot is called, it will return a plot object with the
+  // attribute "coolstring"
+
+Now, given that the plugin might run in many different places, it's
+a good idea to avoid leaking names. The usual trick here is wrap the
+above lines in an anonymous function which is called immediately, like
+this: (function () { inner code ... })(). To make it even more robust
+in case $ is not bound to jQuery but some other Javascript library, we
+can write it as
+
+  (function ($) {
+    // plugin definition
+    // ...
+  })(jQuery);
+
+There's a complete example below, but you should also check out the
+plugins bundled with Flot.
+
+
+Complete example
+----------------
+  
+Here is a simple debug plugin which alerts each of the series in the
+plot. It has a single option that control whether it is enabled and
+how much info to output:
+
+  (function ($) {
+    function init(plot) {
+      var debugLevel = 1;
+    
+      function checkDebugEnabled(plot, options) {
+        if (options.debug) {
+          debugLevel = options.debug;
+            
+          plot.hooks.processDatapoints.push(alertSeries);
+        }
+      }
+
+      function alertSeries(plot, series, datapoints) {
+        var msg = "series " + series.label;
+        if (debugLevel > 1)
+          msg += " with " + series.data.length + " points";
+        alert(msg);
+      }
+    
+      plot.hooks.processOptions.push(checkDebugEnabled);
+    }
+
+    var options = { debug: 0 };
+    
+    $.plot.plugins.push({
+        init: init,
+        options: options,
+        name: "simpledebug",
+        version: "0.1"
+    });
+  })(jQuery);
+
+We also define "name" and "version". It's not used by Flot, but might
+be helpful for other plugins in resolving dependencies.
+  
+Put the above in a file named "jquery.flot.debug.js", include it in an
+HTML page and then it can be used with:
+
+  $.plot($("#placeholder"), [...], { debug: 2 });
+
+This simple plugin illustrates a couple of points:
+
+ - It uses the anonymous function trick to avoid name pollution.
+ - It can be enabled/disabled through an option.
+ - Variables in the init function can be used to store plot-specific
+   state between the hooks.
+
+The two last points are important because there may be multiple plots
+on the same page, and you'd want to make sure they are not mixed up.
+
+
+Shutting down a plugin
+----------------------
+
+Each plot object has a shutdown hook which is run when plot.shutdown()
+is called. This usually mostly happens in case another plot is made on
+top of an existing one.
+
+The purpose of the hook is to give you a chance to unbind any event
+handlers you've registered and remove any extra DOM things you've
+inserted.
+
+The problem with event handlers is that you can have registered a
+handler which is run in some point in the future, e.g. with
+setTimeout(). Meanwhile, the plot may have been shutdown and removed,
+but because your event handler is still referencing it, it can't be
+garbage collected yet, and worse, if your handler eventually runs, it
+may overwrite stuff on a completely different plot.
+
+ 
+Some hints on the options
+-------------------------
+   
+Plugins should always support appropriate options to enable/disable
+them because the plugin user may have several plots on the same page
+where only one should use the plugin. In most cases it's probably a
+good idea if the plugin is turned off rather than on per default, just
+like most of the powerful features in Flot.
+
+If the plugin needs options that are specific to each series, like the
+points or lines options in core Flot, you can put them in "series" in
+the options object, e.g.
+
+  var options = {
+    series: {
+      downsample: {
+        algorithm: null,
+        maxpoints: 1000
+      }
+    }
+  }
+
+Then they will be copied by Flot into each series, providing default
+values in case none are specified.
+
+Think hard and long about naming the options. These names are going to
+be public API, and code is going to depend on them if the plugin is
+successful.

data/public/flot/README.txt

@@ -0,0 +1,90 @@
+About
+-----
+
+Flot is a Javascript plotting library for jQuery. Read more at the
+website:
+
+  http://code.google.com/p/flot/
+
+Take a look at the examples linked from above, they should give a good
+impression of what Flot can do and the source code of the examples is
+probably the fastest way to learn how to use Flot.
+  
+
+Installation
+------------
+
+Just include the Javascript file after you've included jQuery.
+
+Generally, all browsers that support the HTML5 canvas tag are
+supported.
+
+For support for Internet Explorer < 9, you can use Excanvas, a canvas
+emulator; this is used in the examples bundled with Flot. You just
+include the excanvas script like this:
+
+  <!--[if lte IE 8]><script language="javascript" type="text/javascript" src="excanvas.min.js"></script><![endif]-->
+
+If it's not working on your development IE 6.0, check that it has
+support for VML which Excanvas is relying on. It appears that some
+stripped down versions used for test environments on virtual machines
+lack the VML support.
+
+You can also try using Flashcanvas (see
+http://code.google.com/p/flashcanvas/), which uses Flash to do the
+emulation. Although Flash can be a bit slower to load than VML, if
+you've got a lot of points, the Flash version can be much faster
+overall. Flot contains some wrapper code for activating Excanvas which
+Flashcanvas is compatible with.
+
+You need at least jQuery 1.2.6, but try at least 1.3.2 for interactive
+charts because of performance improvements in event handling.
+
+
+Basic usage
+-----------
+
+Create a placeholder div to put the graph in:
+
+   <div id="placeholder"></div>
+
+You need to set the width and height of this div, otherwise the plot
+library doesn't know how to scale the graph. You can do it inline like
+this:
+
+   <div id="placeholder" style="width:600px;height:300px"></div>
+
+You can also do it with an external stylesheet. Make sure that the
+placeholder isn't within something with a display:none CSS property -
+in that case, Flot has trouble measuring label dimensions which
+results in garbled looks and might have trouble measuring the
+placeholder dimensions which is fatal (it'll throw an exception).
+
+Then when the div is ready in the DOM, which is usually on document
+ready, run the plot function:
+
+  $.plot($("#placeholder"), data, options);
+
+Here, data is an array of data series and options is an object with
+settings if you want to customize the plot. Take a look at the
+examples for some ideas of what to put in or look at the reference
+in the file "API.txt". Here's a quick example that'll draw a line from
+(0, 0) to (1, 1):
+
+  $.plot($("#placeholder"), [ [[0, 0], [1, 1]] ], { yaxis: { max: 1 } });
+
+The plot function immediately draws the chart and then returns a plot
+object with a couple of methods.
+
+
+What's with the name?
+---------------------
+
+First: it's pronounced with a short o, like "plot". Not like "flawed".
+
+So "Flot" rhymes with "plot".
+
+And if you look up "flot" in a Danish-to-English dictionary, some up
+the words that come up are "good-looking", "attractive", "stylish",
+"smart", "impressive", "extravagant". One of the main goals with Flot
+is pretty looks.

data/public/flot/examples/ajax.html

@@ -0,0 +1,143 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+ <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+    <title>Flot Examples</title>
+    <link href="layout.css" rel="stylesheet" type="text/css">
+    <!--[if lte IE 8]><script language="javascript" type="text/javascript" src="../excanvas.min.js"></script><![endif]-->
+    <script language="javascript" type="text/javascript" src="../jquery.js"></script>
+    <script language="javascript" type="text/javascript" src="../jquery.flot.js"></script>
+ </head>
+    <body>
+    <h1>Flot Examples</h1>
+
+    <div id="placeholder" style="width:600px;height:300px;"></div>
+
+    <p>Example of loading data dynamically with AJAX. Percentage change in GDP (source: <a href="http://epp.eurostat.ec.europa.eu/tgm/table.do?tab=table&init=1&plugin=1&language=en&pcode=tsieb020">Eurostat</a>). Click the buttons below.</p>
+
+    <p>The data is fetched over HTTP, in this case directly from text
+    files. Usually the URL would point to some web server handler
+    (e.g. a PHP page or Java/.NET/Python/Ruby on Rails handler) that
+    extracts it from a database and serializes it to JSON.</p>
+
+    <p>
+      <input class="fetchSeries" type="button" value="First dataset"> -
+      <a href="data-eu-gdp-growth.json">data</a> -
+      <span></span>
+    </p>
+
+    <p>
+      <input class="fetchSeries" type="button" value="Second dataset"> -
+      <a href="data-japan-gdp-growth.json">data</a> -
+      <span></span>
+    </p>
+
+    <p>
+      <input class="fetchSeries" type="button" value="Third dataset"> -
+      <a href="data-usa-gdp-growth.json">data</a> -
+      <span></span>
+    </p>
+
+    <p>If you combine AJAX with setTimeout, you can poll the server
+       for new data.</p>
+
+    <p>
+      <input class="dataUpdate" type="button" value="Poll for data">
+    </p>
+
+<script type="text/javascript">
+$(function () {
+    var options = {
+        lines: { show: true },
+        points: { show: true },
+        xaxis: { tickDecimals: 0, tickSize: 1 }
+    };
+    var data = [];
+    var placeholder = $("#placeholder");
+    
+    $.plot(placeholder, data, options);
+
+    
+    // fetch one series, adding to what we got
+    var alreadyFetched = {};
+    
+    $("input.fetchSeries").click(function () {
+        var button = $(this);
+        
+        // find the URL in the link right next to us 
+        var dataurl = button.siblings('a').attr('href');
+
+        // then fetch the data with jQuery
+        function onDataReceived(series) {
+            // extract the first coordinate pair so you can see that
+            // data is now an ordinary Javascript object
+            var firstcoordinate = '(' + series.data[0][0] + ', ' + series.data[0][1] + ')';
+
+            button.siblings('span').text('Fetched ' + series.label + ', first point: ' + firstcoordinate);
+
+            // let's add it to our current data
+            if (!alreadyFetched[series.label]) {
+                alreadyFetched[series.label] = true;
+                data.push(series);
+            }
+            
+            // and plot all we got
+            $.plot(placeholder, data, options);
+         }
+        
+        $.ajax({
+            url: dataurl,
+            method: 'GET',
+            dataType: 'json',
+            success: onDataReceived
+        });
+    });
+
+
+    // initiate a recurring data update
+    $("input.dataUpdate").click(function () {
+        // reset data
+        data = [];
+        alreadyFetched = {};
+        
+        $.plot(placeholder, data, options);
+
+        var iteration = 0;
+        
+        function fetchData() {
+            ++iteration;
+
+            function onDataReceived(series) {
+                // we get all the data in one go, if we only got partial
+                // data, we could merge it with what we already got
+                data = [ series ];
+                
+                $.plot($("#placeholder"), data, options);
+            }
+        
+            $.ajax({
+                // usually, we'll just call the same URL, a script
+                // connected to a database, but in this case we only
+                // have static example files so we need to modify the
+                // URL
+                url: "data-eu-gdp-growth-" + iteration + ".json",
+                method: 'GET',
+                dataType: 'json',
+                success: onDataReceived
+            });
+            
+            if (iteration < 5)
+                setTimeout(fetchData, 1000);
+            else {
+                data = [];
+                alreadyFetched = {};
+            }
+        }
+
+        setTimeout(fetchData, 1000);
+    });
+});
+</script>
+
+ </body>
+</html>

data/public/flot/examples/annotating.html

@@ -0,0 +1,75 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+ <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+    <title>Flot Examples</title>
+    <link href="layout.css" rel="stylesheet" type="text/css">
+    <!--[if lte IE 8]><script language="javascript" type="text/javascript" src="../excanvas.min.js"></script><![endif]-->
+    <script language="javascript" type="text/javascript" src="../jquery.js"></script>
+    <script language="javascript" type="text/javascript" src="../jquery.flot.js"></script>
+ </head>
+    <body>
+    <h1>Flot Examples</h1>
+
+    <div id="placeholder" style="width:600px;height:300px;"></div>
+
+    <p>Flot has support for simple background decorations such as
+    lines and rectangles. They can be useful for marking up certain
+    areas. You can easily add any HTML you need with standard DOM
+    manipulation, e.g. for labels. For drawing custom shapes there is
+    also direct access to the canvas.</p>
+
+<script type="text/javascript">
+$(function () {
+    // generate a dataset
+    var d1 = [];
+    for (var i = 0; i < 20; ++i)
+        d1.push([i, Math.sin(i)]);
+    
+    var data = [{ data: d1, label: "Pressure", color: "#333" }];
+
+    // setup background areas
+    var markings = [
+        { color: '#f6f6f6', yaxis: { from: 1 } },
+        { color: '#f6f6f6', yaxis: { to: -1 } },
+        { color: '#000', lineWidth: 1, xaxis: { from: 2, to: 2 } },
+        { color: '#000', lineWidth: 1, xaxis: { from: 8, to: 8 } }
+    ];
+    
+    var placeholder = $("#placeholder");
+    
+    // plot it
+    var plot = $.plot(placeholder, data, {
+        bars: { show: true, barWidth: 0.5, fill: 0.9 },
+        xaxis: { ticks: [], autoscaleMargin: 0.02 },
+        yaxis: { min: -2, max: 2 },
+        grid: { markings: markings }
+    });
+
+    // add labels
+    var o;
+
+    o = plot.pointOffset({ x: 2, y: -1.2});
+    // we just append it to the placeholder which Flot already uses
+    // for positioning
+    placeholder.append('<div style="position:absolute;left:' + (o.left + 4) + 'px;top:' + o.top + 'px;color:#666;font-size:smaller">Warming up</div>');
+
+    o = plot.pointOffset({ x: 8, y: -1.2});
+    placeholder.append('<div style="position:absolute;left:' + (o.left + 4) + 'px;top:' + o.top + 'px;color:#666;font-size:smaller">Actual measurements</div>');
+
+    // draw a little arrow on top of the last label to demonstrate
+    // canvas drawing
+    var ctx = plot.getCanvas().getContext("2d");
+    ctx.beginPath();
+    o.left += 4;
+    ctx.moveTo(o.left, o.top);
+    ctx.lineTo(o.left, o.top - 10);
+    ctx.lineTo(o.left + 10, o.top - 5);
+    ctx.lineTo(o.left, o.top);
+    ctx.fillStyle = "#000";
+    ctx.fill();
+});
+</script>
+
+ </body>
+</html>