root / hci / trunk / eneraptor-web-app / web-app / js / flot / PLUGINS.txt @ 11
History | View | Annotate | Download (3.17 KB)
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. |