PLUGINS.txt

Writing plugins
---------------

To make a new plugin, create an init function and a set of options (if
needed), stuff it into an object and put it in the $.plot.plugins
array. For example:

  function myCoolPluginInit(plot) { plot.coolstring = "Hello!" };
  var myCoolOptions = { coolstuff: { show: true } }
  $.plot.plugins.push({ init: myCoolPluginInit, options: myCoolOptions });

  // now when $.plot is called, the returned object will have the
  // attribute "coolstring"

Now, given that the plugin might run in many different places, it's
a good idea to avoid leaking names. We can avoid this by wrapping the
above lines in an anonymous function which we call 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);

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.

 
Options guidelines
==================
   
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.

If the plugin needs series-specific options, 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 the
defaults in case the plugin user doesn't specify any. Again, 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.

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.