source: appstream-generator/contrib/setup/js_tmp/Flot/PLUGINS.md @ 4841

Last change on this file since 4841 was 4841, checked in by Juanma, 2 years ago

Initial release

File size: 4.2 KB
Line 
1## Writing plugins ##
2
3All you need to do to make a new plugin is creating an init function
4and a set of options (if needed), stuffing it into an object and
5putting it in the $.plot.plugins array. For example:
6
7```js
8function myCoolPluginInit(plot) {
9    plot.coolstring = "Hello!";
10};
11
12$.plot.plugins.push({ init: myCoolPluginInit, options: { ... } });
13
14// if $.plot is called, it will return a plot object with the
15// attribute "coolstring"
16```
17
18Now, given that the plugin might run in many different places, it's
19a good idea to avoid leaking names. The usual trick here is wrap the
20above lines in an anonymous function which is called immediately, like
21this: (function () { inner code ... })(). To make it even more robust
22in case $ is not bound to jQuery but some other Javascript library, we
23can write it as
24
25```js
26(function ($) {
27    // plugin definition
28    // ...
29})(jQuery);
30```
31
32There's a complete example below, but you should also check out the
33plugins bundled with Flot.
34
35
36## Complete example ##
37 
38Here is a simple debug plugin which alerts each of the series in the
39plot. It has a single option that control whether it is enabled and
40how much info to output:
41
42```js
43(function ($) {
44    function init(plot) {
45        var debugLevel = 1;
46
47        function checkDebugEnabled(plot, options) {
48            if (options.debug) {
49                debugLevel = options.debug;
50                plot.hooks.processDatapoints.push(alertSeries);
51            }
52        }
53
54        function alertSeries(plot, series, datapoints) {
55            var msg = "series " + series.label;
56            if (debugLevel > 1) {
57                msg += " with " + series.data.length + " points";
58                alert(msg);
59            }
60        }
61
62        plot.hooks.processOptions.push(checkDebugEnabled);
63    }
64
65    var options = { debug: 0 };
66     
67    $.plot.plugins.push({
68        init: init,
69        options: options,
70        name: "simpledebug",
71        version: "0.1"
72    });
73})(jQuery);
74```
75
76We also define "name" and "version". It's not used by Flot, but might
77be helpful for other plugins in resolving dependencies.
78 
79Put the above in a file named "jquery.flot.debug.js", include it in an
80HTML page and then it can be used with:
81
82```js
83    $.plot($("#placeholder"), [...], { debug: 2 });
84```
85
86This simple plugin illustrates a couple of points:
87
88 - It uses the anonymous function trick to avoid name pollution.
89 - It can be enabled/disabled through an option.
90 - Variables in the init function can be used to store plot-specific
91   state between the hooks.
92
93The two last points are important because there may be multiple plots
94on the same page, and you'd want to make sure they are not mixed up.
95
96
97## Shutting down a plugin ##
98
99Each plot object has a shutdown hook which is run when plot.shutdown()
100is called. This usually mostly happens in case another plot is made on
101top of an existing one.
102
103The purpose of the hook is to give you a chance to unbind any event
104handlers you've registered and remove any extra DOM things you've
105inserted.
106
107The problem with event handlers is that you can have registered a
108handler which is run in some point in the future, e.g. with
109setTimeout(). Meanwhile, the plot may have been shutdown and removed,
110but because your event handler is still referencing it, it can't be
111garbage collected yet, and worse, if your handler eventually runs, it
112may overwrite stuff on a completely different plot.
113
114 
115## Some hints on the options ##
116   
117Plugins should always support appropriate options to enable/disable
118them because the plugin user may have several plots on the same page
119where only one should use the plugin. In most cases it's probably a
120good idea if the plugin is turned off rather than on per default, just
121like most of the powerful features in Flot.
122
123If the plugin needs options that are specific to each series, like the
124points or lines options in core Flot, you can put them in "series" in
125the options object, e.g.
126
127```js
128var options = {
129    series: {
130        downsample: {
131            algorithm: null,
132            maxpoints: 1000
133        }
134    }
135}
136```
137
138Then they will be copied by Flot into each series, providing default
139values in case none are specified.
140
141Think hard and long about naming the options. These names are going to
142be public API, and code is going to depend on them if the plugin is
143successful.
Note: See TracBrowser for help on using the repository browser.