flotjs v0.1.3

flot.js

About

flot.js is a Javascript plotting library using HTML5 canvas. Based off of a fork of https://github.com/flot/flot, flot.js has made the following major changes:

• Removed jQuery as a dependency
• Exposes a simple events API
• Library is as a UMD (Universal Module Definition) module

flot.js kept nearly all of the existing API the same with one major change that should be noted:

• Events
  • jquery.flot.js used jQuery Event system. This is why EventEmitter was introduced. Now if you want to "trigger" events, you do so with the Plot instance. For example, listening on events:

    // before
    $(placeholder).bind('plothover', function(e){});
    
    // now
    plot.bind('plothover', function(e){});

    And for triggering events:

    // before
    $(placeholder).trigger('plotselected', [r]);
    
    // after
    plot.emit('plotselected', event, r);

    IMPORTANT: Noticed that the triggering event example, we pass in arguments not as an array AND we passed the event object. This is because jQuery always passed in a jQuery event object as its first argument. Something thats worth mentioning.
  • What about the DOM events??
    • The "eventHolder" is no longer available. Instead, it has been replaced with the actualy <canvas class="flot-overlay"> element. You should attach whatever DOM event you wish on this element. For example:

      // before:
      plot.hooks.bindEvents.push(function(plot, eventHolder) {
        eventHolder.bind('mouseover', onMouseOver);
        eventHolder.mousedown(onMouseDown);
        eventHolder.on('click', onClick);
      });
      plot.hooks.shutdown.push(function(plot, eventHolder) {
        eventHolder.unbind('mouseover', onMouseOver);
        eventHolder.unbind('mousedown', onMouseDown);
        eventHolder.off('click', onClick);
      });
      
      // now:
      
      plot.hooks.bindEvents.push(function(plot, overlayElem) {
        overlayElem.addEventListener('click', onClick);      // IE9+
        overlayElem.attachEvent('onmousedown', onMouseDown); // < IE9
        // or better yet, use `dom-tools` since it's already a dep.
        DOMTools.attachEventListener(overlayElem, 'mouseover', onMouseOver); // Any IE version
      });
      plot.hooks.shutdown.push(function(plot, eventHolder) {
        eventHolder.removeEventListener('click', onClick);
        eventHolder.detachEvent('onmousedown', onMouseDown);
        DOMTools.removeEventListener(overlayElem, 'mouseover', onMouseOver);
      });

Check out the examples in examples/index.html page. Most of them have been updated with flot.js.

Why should you use this over the original version?

If your project does not require jQuery this would be best suited for you. If you're already using jQuery, you should use the original version.

Browser support

flot.js supports:

• IE8+
• Chrome
• Firefox
• Safari
• Opera 10+

Dependencies

Although jQuery is no longer required, in order to replace the missing pieces two other dependencies are required: dom-tools and EventEmitter

It may sound silly that we remove one and added two more libraries, if you do NOT need jQuery you can save a lot of overhead.

Using closure-compiler:

• jquery-1.12.0.min.js is roughly 33.15KB gzipped or 95.17KB uncompressed.
• jquery-2.2.0.min.js is roughly 29.29KB gzipped or 83.67KB uncompressed.
• dom-utils.min.js and EventEmitter.min.js combined for 2.76KB gzipped or 8.36KB uncompressed.
  • dom-utils.min.js (v0.1.1) is roughly 1.86KB gzipped or 5.45KB uncompressed.
  • EventEmitter.min.js (v4.3.0) is roughly 1.03KB gzipped or 2.91KB uncompressed.

Installation

Browser via script tag

Just include the Javascript file after you've included dom-tools and EventEmitter.

Browser via AMD

If the script is loaded into a page containing an AMD loader (such as RequireJS), use it like this:

require(['flot'], function(Plot) {
    var plot = new Plot(document.getElementById('placeholder'), [], {});
});

node.js or Browser via Browserify

Install the file via npm (bower will come soon):

npm install flotjs --save

...and then require it

var Plot = require('flotjs');

Heads up!

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]-->

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:

new Plot(document.getElementById("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 API reference. Here's a quick example that'll draw a line from (0, 0) to (1, 1):

new Plot(document.getElementById("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 of the words that come up are "good-looking", "attractive", "stylish", "smart", "impressive", "extravagant". One of the main goals with Flot is pretty looks.

Notes about the examples

In order to have a useful, functional example of time-series plots using time zones, date.js from timezone-js (released under the Apache 2.0 license) and the Olson time zone database (released to the public domain) have been included in the examples directory. They are used in examples/axes-time-zones/index.html.