1 files changed, 105 insertions, 0 deletions
diff --git a/PLUGINS.txt b/PLUGINS.txt
new file mode 100644
index 0000000..00bf2e5
--- /dev/null
+++ b/PLUGINS.txt
@@ -0,0 +1,105 @@
+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.