|
|
maxious
|
1 |
Writing plugins |
|
|
|
2 |
--------------- |
|
|
|
3 |
|
|
|
|
4 |
To make a new plugin, create an init function and a set of options (if |
|
|
|
5 |
needed), stuff it into an object and put it in the $.plot.plugins |
|
|
|
6 |
array. For example: |
|
|
|
7 |
|
|
|
|
8 |
function myCoolPluginInit(plot) { plot.coolstring = "Hello!" }; |
|
|
|
9 |
var myCoolOptions = { coolstuff: { show: true } } |
|
|
|
10 |
$.plot.plugins.push({ init: myCoolPluginInit, options: myCoolOptions }); |
|
|
|
11 |
|
|
|
|
12 |
// now when $.plot is called, the returned object will have the |
|
|
|
13 |
// attribute "coolstring" |
|
|
|
14 |
|
|
|
|
15 |
Now, given that the plugin might run in many different places, it's |
|
|
|
16 |
a good idea to avoid leaking names. We can avoid this by wrapping the |
|
|
|
17 |
above lines in an anonymous function which we call immediately, like |
|
|
|
18 |
this: (function () { inner code ... })(). To make it even more robust |
|
|
|
19 |
in case $ is not bound to jQuery but some other Javascript library, we |
|
|
|
20 |
can write it as |
|
|
|
21 |
|
|
|
|
22 |
(function ($) { |
|
|
|
23 |
// plugin definition |
|
|
|
24 |
// ... |
|
|
|
25 |
})(jQuery); |
|
|
|
26 |
|
|
|
|
27 |
Here is a simple debug plugin which alerts each of the series in the |
|
|
|
28 |
plot. It has a single option that control whether it is enabled and |
|
|
|
29 |
how much info to output: |
|
|
|
30 |
|
|
|
|
31 |
(function ($) { |
|
|
|
32 |
function init(plot) { |
|
|
|
33 |
var debugLevel = 1; |
|
|
|
34 |
|
|
|
|
35 |
function checkDebugEnabled(plot, options) { |
|
|
|
36 |
if (options.debug) { |
|
|
|
37 |
debugLevel = options.debug; |
|
|
|
38 |
|
|
|
|
39 |
plot.hooks.processDatapoints.push(alertSeries); |
|
|
|
40 |
} |
|
|
|
41 |
} |
|
|
|
42 |
|
|
|
|
43 |
function alertSeries(plot, series, datapoints) { |
|
|
|
44 |
var msg = "series " + series.label; |
|
|
|
45 |
if (debugLevel > 1) |
|
|
|
46 |
msg += " with " + series.data.length + " points"; |
|
|
|
47 |
alert(msg); |
|
|
|
48 |
} |
|
|
|
49 |
|
|
|
|
50 |
plot.hooks.processOptions.push(checkDebugEnabled); |
|
|
|
51 |
} |
|
|
|
52 |
|
|
|
|
53 |
var options = { debug: 0 }; |
|
|
|
54 |
|
|
|
|
55 |
$.plot.plugins.push({ |
|
|
|
56 |
init: init, |
|
|
|
57 |
options: options, |
|
|
|
58 |
name: "simpledebug", |
|
|
|
59 |
version: "0.1" |
|
|
|
60 |
}); |
|
|
|
61 |
})(jQuery); |
|
|
|
62 |
|
|
|
|
63 |
We also define "name" and "version". It's not used by Flot, but might |
|
|
|
64 |
be helpful for other plugins in resolving dependencies. |
|
|
|
65 |
|
|
|
|
66 |
Put the above in a file named "jquery.flot.debug.js", include it in an |
|
|
|
67 |
HTML page and then it can be used with: |
|
|
|
68 |
|
|
|
|
69 |
$.plot($("#placeholder"), [...], { debug: 2 }); |
|
|
|
70 |
|
|
|
|
71 |
This simple plugin illustrates a couple of points: |
|
|
|
72 |
|
|
|
|
73 |
- It uses the anonymous function trick to avoid name pollution. |
|
|
|
74 |
- It can be enabled/disabled through an option. |
|
|
|
75 |
- Variables in the init function can be used to store plot-specific |
|
|
|
76 |
state between the hooks. |
|
|
|
77 |
|
|
|
|
78 |
|
|
|
|
79 |
Options guidelines |
|
|
|
80 |
================== |
|
|
|
81 |
|
|
|
|
82 |
Plugins should always support appropriate options to enable/disable |
|
|
|
83 |
them because the plugin user may have several plots on the same page |
|
|
|
84 |
where only one should use the plugin. |
|
|
|
85 |
|
|
|
|
86 |
If the plugin needs series-specific options, you can put them in |
|
|
|
87 |
"series" in the options object, e.g. |
|
|
|
88 |
|
|
|
|
89 |
var options = { |
|
|
|
90 |
series: { |
|
|
|
91 |
downsample: { |
|
|
|
92 |
algorithm: null, |
|
|
|
93 |
maxpoints: 1000 |
|
|
|
94 |
} |
|
|
|
95 |
} |
|
|
|
96 |
} |
|
|
|
97 |
|
|
|
|
98 |
Then they will be copied by Flot into each series, providing the |
|
|
|
99 |
defaults in case the plugin user doesn't specify any. Again, in most |
|
|
|
100 |
cases it's probably a good idea if the plugin is turned off rather |
|
|
|
101 |
than on per default, just like most of the powerful features in Flot. |
|
|
|
102 |
|
|
|
|
103 |
Think hard and long about naming the options. These names are going to |
|
|
|
104 |
be public API, and code is going to depend on them if the plugin is |
|
|
|
105 |
successful. |
|
|
|
106 |
|