You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
106 lines
3.2 KiB
Plaintext
106 lines
3.2 KiB
Plaintext
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.
|