Permalink
Browse files

Cleanup and markup standardization.

  • Loading branch information...
1 parent 7cdc593 commit 5145b0a0c51168af0fb8da01188de2725e19efa6 @dnschnur dnschnur committed Jul 16, 2012
Showing with 48 additions and 43 deletions.
  1. +48 −43 PLUGINS.md
View
@@ -1,18 +1,19 @@
-Writing plugins
----------------
+## Writing plugins ##
All you need to do to make a new plugin is creating an init function
and a set of options (if needed), stuffing it into an object and
putting it in the $.plot.plugins array. For example:
- function myCoolPluginInit(plot) {
- plot.coolstring = "Hello!";
- };
+```js
+function myCoolPluginInit(plot) {
+ plot.coolstring = "Hello!";
+};
- $.plot.plugins.push({ init: myCoolPluginInit, options: { ... } });
+$.plot.plugins.push({ init: myCoolPluginInit, options: { ... } });
- // if $.plot is called, it will return a plot object with the
- // attribute "coolstring"
+// if $.plot is called, it will return a plot object with the
+// attribute "coolstring"
+```
Now, given that the plugin might run in many different places, it's
a good idea to avoid leaking names. The usual trick here is wrap the
@@ -21,61 +22,65 @@ this: (function () { inner code ... })(). To make it even more robust
in case $ is not bound to jQuery but some other Javascript library, we
can write it as
- (function ($) {
- // plugin definition
- // ...
- })(jQuery);
+```js
+(function ($) {
+ // plugin definition
+ // ...
+})(jQuery);
+```
There's a complete example below, but you should also check out the
plugins bundled with Flot.
-Complete example
-----------------
+## Complete example ##
Here is a simple debug plugin which alerts each of the series in the
plot. It has a single option that control whether it is enabled and
how much info to output:
- (function ($) {
- function init(plot) {
+```js
+(function ($) {
+ function init(plot) {
var debugLevel = 1;
-
+
function checkDebugEnabled(plot, options) {
- if (options.debug) {
+ if (options.debug) {
debugLevel = options.debug;
-
plot.hooks.processDatapoints.push(alertSeries);
- }
}
+ }
- function alertSeries(plot, series, datapoints) {
- var msg = "series " + series.label;
- if (debugLevel > 1)
+ function alertSeries(plot, series, datapoints) {
+ var msg = "series " + series.label;
+ if (debugLevel > 1) {
msg += " with " + series.data.length + " points";
- alert(msg);
+ alert(msg);
}
-
+
plot.hooks.processOptions.push(checkDebugEnabled);
- }
+ }
- var options = { debug: 0 };
+ var options = { debug: 0 };
- $.plot.plugins.push({
- init: init,
- options: options,
- name: "simpledebug",
- version: "0.1"
- });
- })(jQuery);
+ $.plot.plugins.push({
+ init: init,
+ options: options,
+ name: "simpledebug",
+ version: "0.1"
+ });
+})(jQuery);
+```
We also define "name" and "version". It's not used by Flot, but might
be helpful for other plugins in resolving dependencies.
Put the above in a file named "jquery.flot.debug.js", include it in an
HTML page and then it can be used with:
+```js
$.plot($("#placeholder"), [...], { debug: 2 });
+```
This simple plugin illustrates a couple of points:
@@ -88,8 +93,7 @@ The two last points are important because there may be multiple plots
on the same page, and you'd want to make sure they are not mixed up.
-Shutting down a plugin
-----------------------
+## Shutting down a plugin ##
Each plot object has a shutdown hook which is run when plot.shutdown()
is called. This usually mostly happens in case another plot is made on
@@ -107,8 +111,7 @@ garbage collected yet, and worse, if your handler eventually runs, it
may overwrite stuff on a completely different plot.
-Some hints on the options
--------------------------
+## Some hints on the options ##
Plugins should always support appropriate options to enable/disable
them because the plugin user may have several plots on the same page
@@ -120,14 +123,16 @@ If the plugin needs options that are specific to each series, like the
points or lines options in core Flot, you can put them in "series" in
the options object, e.g.
- var options = {
- series: {
+```js
+var options = {
+ series: {
downsample: {
- algorithm: null,
- maxpoints: 1000
+ algorithm: null,
+ maxpoints: 1000
}
- }
}
+}
+```
Then they will be copied by Flot into each series, providing default
values in case none are specified.

0 comments on commit 5145b0a

Please sign in to comment.