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