11Writing plugins
22---------------
33
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:
4+ All you need to do to make a new plugin is creating an init function
5+ and a set of options (if needed), stuffing it into an object and
6+ putting it in the $.plot.plugins array. For example:
77
8- function myCoolPluginInit(plot) { plot.coolstring = "Hello!" };
9- var myCoolOptions = { coolstuff: { show: true } }
10- $.plot.plugins.push({ init: myCoolPluginInit, options: myCoolOptions }) ;
8+ function myCoolPluginInit(plot) {
9+ plot.coolstring = "Hello!";
10+ } ;
1111
12- // now when $.plot is called, the returned object will have the
12+ $.plot.plugins.push({ init: myCoolPluginInit, options: { ... } });
13+
14+ // if $.plot is called, it will return a plot object with the
1315 // attribute "coolstring"
1416
1517Now, 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+ a good idea to avoid leaking names. The usual trick here is wrap the
19+ above lines in an anonymous function which is called immediately, like
1820this: (function () { inner code ... })(). To make it even more robust
1921in case $ is not bound to jQuery but some other Javascript library, we
2022can write it as
@@ -24,6 +26,13 @@ can write it as
2426 // ...
2527 })(jQuery);
2628
29+ There's a complete example below, but you should also check out the
30+ plugins bundled with Flot.
31+
32+
33+ Complete example
34+ ----------------
35+
2736Here is a simple debug plugin which alerts each of the series in the
2837plot. It has a single option that control whether it is enabled and
2938how much info to output:
@@ -75,16 +84,41 @@ This simple plugin illustrates a couple of points:
7584 - Variables in the init function can be used to store plot-specific
7685 state between the hooks.
7786
87+ The two last points are important because there may be multiple plots
88+ on the same page, and you'd want to make sure they are not mixed up.
89+
90+
91+ Shutting down a plugin
92+ ----------------------
93+
94+ Each plot object has a shutdown hook which is run when plot.shutdown()
95+ is called. This usually mostly happens in case another plot is made on
96+ top of an existing one.
97+
98+ The purpose of the hook is to give you a chance to unbind any event
99+ handlers you've registered and remove any extra DOM things you've
100+ inserted.
101+
102+ The problem with event handlers is that you can have registered a
103+ handler which is run in some point in the future, e.g. with
104+ setTimeout(). Meanwhile, the plot may have been shutdown and removed,
105+ but because your event handler is still referencing it, it can't be
106+ garbage collected yet, and worse, if your handler eventually runs, it
107+ may overwrite stuff on a completely different plot.
108+
78109
79- Options guidelines
80- ==================
110+ Some hints on the options
111+ -------------------------
81112
82113Plugins should always support appropriate options to enable/disable
83114them because the plugin user may have several plots on the same page
84- where only one should use the plugin.
115+ where only one should use the plugin. In most cases it's probably a
116+ good idea if the plugin is turned off rather than on per default, just
117+ like most of the powerful features in Flot.
85118
86- If the plugin needs series-specific options, you can put them in
87- "series" in the options object, e.g.
119+ If the plugin needs options that are specific to each series, like the
120+ points or lines options in core Flot, you can put them in "series" in
121+ the options object, e.g.
88122
89123 var options = {
90124 series: {
@@ -95,10 +129,8 @@ If the plugin needs series-specific options, you can put them in
95129 }
96130 }
97131
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.
132+ Then they will be copied by Flot into each series, providing default
133+ values in case none are specified.
102134
103135Think hard and long about naming the options. These names are going to
104136be public API, and code is going to depend on them if the plugin is
0 commit comments