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