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

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

Initial release

File size: 52.3 KB
Line 
1# Flot Reference #
2
3**Table of Contents**
4
5[Introduction](#introduction)
6| [Data Format](#data-format)
7| [Plot Options](#plot-options)
8| [Customizing the legend](#customizing-the-legend)
9| [Customizing the axes](#customizing-the-axes)
10| [Multiple axes](#multiple-axes)
11| [Time series data](#time-series-data)
12| [Customizing the data series](#customizing-the-data-series)
13| [Customizing the grid](#customizing-the-grid)
14| [Specifying gradients](#specifying-gradients)
15| [Plot Methods](#plot-methods)
16| [Hooks](#hooks)
17| [Plugins](#plugins)
18| [Version number](#version-number)
19
20---
21
22## Introduction ##
23
24Consider a call to the plot function:
25
26```js
27var plot = $.plot(placeholder, data, options)
28```
29
30The placeholder is a jQuery object or DOM element or jQuery expression
31that the plot will be put into. This placeholder needs to have its
32width and height set as explained in the [README](README.md) (go read that now if
33you haven't, it's short). The plot will modify some properties of the
34placeholder so it's recommended you simply pass in a div that you
35don't use for anything else. Make sure you check any fancy styling
36you apply to the div, e.g. background images have been reported to be a
37problem on IE 7.
38
39The plot function can also be used as a jQuery chainable property.  This form
40naturally can't return the plot object directly, but you can still access it
41via the 'plot' data key, like this:
42
43```js
44var plot = $("#placeholder").plot(data, options).data("plot");
45```
46
47The format of the data is documented below, as is the available
48options. The plot object returned from the call has some methods you
49can call. These are documented separately below.
50
51Note that in general Flot gives no guarantees if you change any of the
52objects you pass in to the plot function or get out of it since
53they're not necessarily deep-copied.
54
55
56## Data Format ##
57
58The data is an array of data series:
59
60```js
61[ series1, series2, ... ]
62```
63
64A series can either be raw data or an object with properties. The raw
65data format is an array of points:
66
67```js
68[ [x1, y1], [x2, y2], ... ]
69```
70
71E.g.
72
73```js
74[ [1, 3], [2, 14.01], [3.5, 3.14] ]
75```
76
77Note that to simplify the internal logic in Flot both the x and y
78values must be numbers (even if specifying time series, see below for
79how to do this). This is a common problem because you might retrieve
80data from the database and serialize them directly to JSON without
81noticing the wrong type. If you're getting mysterious errors, double
82check that you're inputting numbers and not strings.
83
84If a null is specified as a point or if one of the coordinates is null
85or couldn't be converted to a number, the point is ignored when
86drawing. As a special case, a null value for lines is interpreted as a
87line segment end, i.e. the points before and after the null value are
88not connected.
89
90Lines and points take two coordinates. For filled lines and bars, you
91can specify a third coordinate which is the bottom of the filled
92area/bar (defaults to 0).
93
94The format of a single series object is as follows:
95
96```js
97{
98    color: color or number
99    data: rawdata
100    label: string
101    lines: specific lines options
102    bars: specific bars options
103    points: specific points options
104    xaxis: number
105    yaxis: number
106    clickable: boolean
107    hoverable: boolean
108    shadowSize: number
109    highlightColor: color or number
110}
111```
112
113You don't have to specify any of them except the data, the rest are
114options that will get default values. Typically you'd only specify
115label and data, like this:
116
117```js
118{
119    label: "y = 3",
120    data: [[0, 3], [10, 3]]
121}
122```
123
124The label is used for the legend, if you don't specify one, the series
125will not show up in the legend.
126
127If you don't specify color, the series will get a color from the
128auto-generated colors. The color is either a CSS color specification
129(like "rgb(255, 100, 123)") or an integer that specifies which of
130auto-generated colors to select, e.g. 0 will get color no. 0, etc.
131
132The latter is mostly useful if you let the user add and remove series,
133in which case you can hard-code the color index to prevent the colors
134from jumping around between the series.
135
136The "xaxis" and "yaxis" options specify which axis to use. The axes
137are numbered from 1 (default), so { yaxis: 2} means that the series
138should be plotted against the second y axis.
139
140"clickable" and "hoverable" can be set to false to disable
141interactivity for specific series if interactivity is turned on in
142the plot, see below.
143
144The rest of the options are all documented below as they are the same
145as the default options passed in via the options parameter in the plot
146commmand. When you specify them for a specific data series, they will
147override the default options for the plot for that data series.
148
149Here's a complete example of a simple data specification:
150
151```js
152[ { label: "Foo", data: [ [10, 1], [17, -14], [30, 5] ] },
153  { label: "Bar", data: [ [11, 13], [19, 11], [30, -7] ] }
154]
155```
156
157
158## Plot Options ##
159
160All options are completely optional. They are documented individually
161below, to change them you just specify them in an object, e.g.
162
163```js
164var options = {
165    series: {
166        lines: { show: true },
167        points: { show: true }
168    }
169};
170       
171$.plot(placeholder, data, options);
172```
173
174
175## Customizing the legend ##
176
177```js
178legend: {
179    show: boolean
180    labelFormatter: null or (fn: string, series object -> string)
181    labelBoxBorderColor: color
182    noColumns: number
183    position: "ne" or "nw" or "se" or "sw"
184    margin: number of pixels or [x margin, y margin]
185    backgroundColor: null or color
186    backgroundOpacity: number between 0 and 1
187    container: null or jQuery object/DOM element/jQuery expression
188    sorted: null/false, true, "ascending", "descending", "reverse", or a comparator
189}
190```
191
192The legend is generated as a table with the data series labels and
193small label boxes with the color of the series. If you want to format
194the labels in some way, e.g. make them to links, you can pass in a
195function for "labelFormatter". Here's an example that makes them
196clickable:
197
198```js
199labelFormatter: function(label, series) {
200    // series is the series object for the label
201    return '<a href="#' + label + '">' + label + '</a>';
202}
203```
204
205To prevent a series from showing up in the legend, simply have the function
206return null.
207
208"noColumns" is the number of columns to divide the legend table into.
209"position" specifies the overall placement of the legend within the
210plot (top-right, top-left, etc.) and margin the distance to the plot
211edge (this can be either a number or an array of two numbers like [x,
212y]). "backgroundColor" and "backgroundOpacity" specifies the
213background. The default is a partly transparent auto-detected
214background.
215
216If you want the legend to appear somewhere else in the DOM, you can
217specify "container" as a jQuery object/expression to put the legend
218table into. The "position" and "margin" etc. options will then be
219ignored. Note that Flot will overwrite the contents of the container.
220
221Legend entries appear in the same order as their series by default. If "sorted"
222is "reverse" then they appear in the opposite order from their series. To sort
223them alphabetically, you can specify true, "ascending" or "descending", where
224true and "ascending" are equivalent.
225
226You can also provide your own comparator function that accepts two
227objects with "label" and "color" properties, and returns zero if they
228are equal, a positive value if the first is greater than the second,
229and a negative value if the first is less than the second.
230
231```js
232sorted: function(a, b) {
233    // sort alphabetically in ascending order
234    return a.label == b.label ? 0 : (
235        a.label > b.label ? 1 : -1
236    )
237}
238```
239
240
241## Customizing the axes ##
242
243```js
244xaxis, yaxis: {
245    show: null or true/false
246    position: "bottom" or "top" or "left" or "right"
247    mode: null or "time" ("time" requires jquery.flot.time.js plugin)
248    timezone: null, "browser" or timezone (only makes sense for mode: "time")
249
250    color: null or color spec
251    tickColor: null or color spec
252    font: null or font spec object
253
254    min: null or number
255    max: null or number
256    autoscaleMargin: null or number
257   
258    transform: null or fn: number -> number
259    inverseTransform: null or fn: number -> number
260   
261    ticks: null or number or ticks array or (fn: axis -> ticks array)
262    tickSize: number or array
263    minTickSize: number or array
264    tickFormatter: (fn: number, object -> string) or string
265    tickDecimals: null or number
266
267    labelWidth: null or number
268    labelHeight: null or number
269    reserveSpace: null or true
270   
271    tickLength: null or number
272
273    alignTicksWithAxis: null or number
274}
275```
276
277All axes have the same kind of options. The following describes how to
278configure one axis, see below for what to do if you've got more than
279one x axis or y axis.
280
281If you don't set the "show" option (i.e. it is null), visibility is
282auto-detected, i.e. the axis will show up if there's data associated
283with it. You can override this by setting the "show" option to true or
284false.
285
286The "position" option specifies where the axis is placed, bottom or
287top for x axes, left or right for y axes. The "mode" option determines
288how the data is interpreted, the default of null means as decimal
289numbers. Use "time" for time series data; see the time series data
290section. The time plugin (jquery.flot.time.js) is required for time
291series support.
292
293The "color" option determines the color of the line and ticks for the axis, and
294defaults to the grid color with transparency. For more fine-grained control you
295can also set the color of the ticks separately with "tickColor".
296
297You can customize the font and color used to draw the axis tick labels with CSS
298or directly via the "font" option. When "font" is null - the default - each
299tick label is given the 'flot-tick-label' class. For compatibility with Flot
3000.7 and earlier the labels are also given the 'tickLabel' class, but this is
301deprecated and scheduled to be removed with the release of version 1.0.0.
302
303To enable more granular control over styles, labels are divided between a set
304of text containers, with each holding the labels for one axis. These containers
305are given the classes 'flot-[x|y]-axis', and 'flot-[x|y]#-axis', where '#' is
306the number of the axis when there are multiple axes.  For example, the x-axis
307labels for a simple plot with only a single x-axis might look like this:
308
309```html
310<div class='flot-x-axis flot-x1-axis'>
311    <div class='flot-tick-label'>January 2013</div>
312    ...
313</div>
314```
315
316For direct control over label styles you can also provide "font" as an object
317with this format:
318
319```js
320{
321    size: 11,
322    lineHeight: 13,
323    style: "italic",
324    weight: "bold",
325    family: "sans-serif",
326    variant: "small-caps",
327    color: "#545454"
328}
329```
330
331The size and lineHeight must be expressed in pixels; CSS units such as 'em'
332or 'smaller' are not allowed.
333
334The options "min"/"max" are the precise minimum/maximum value on the
335scale. If you don't specify either of them, a value will automatically
336be chosen based on the minimum/maximum data values. Note that Flot
337always examines all the data values you feed to it, even if a
338restriction on another axis may make some of them invisible (this
339makes interactive use more stable).
340
341The "autoscaleMargin" is a bit esoteric: it's the fraction of margin
342that the scaling algorithm will add to avoid that the outermost points
343ends up on the grid border. Note that this margin is only applied when
344a min or max value is not explicitly set. If a margin is specified,
345the plot will furthermore extend the axis end-point to the nearest
346whole tick. The default value is "null" for the x axes and 0.02 for y
347axes which seems appropriate for most cases.
348
349"transform" and "inverseTransform" are callbacks you can put in to
350change the way the data is drawn. You can design a function to
351compress or expand certain parts of the axis non-linearly, e.g.
352suppress weekends or compress far away points with a logarithm or some
353other means. When Flot draws the plot, each value is first put through
354the transform function. Here's an example, the x axis can be turned
355into a natural logarithm axis with the following code:
356
357```js
358xaxis: {
359    transform: function (v) { return Math.log(v); },
360    inverseTransform: function (v) { return Math.exp(v); }
361}
362```
363
364Similarly, for reversing the y axis so the values appear in inverse
365order:
366
367```js
368yaxis: {
369    transform: function (v) { return -v; },
370    inverseTransform: function (v) { return -v; }
371}
372```
373
374Note that for finding extrema, Flot assumes that the transform
375function does not reorder values (it should be monotone).
376
377The inverseTransform is simply the inverse of the transform function
378(so v == inverseTransform(transform(v)) for all relevant v). It is
379required for converting from canvas coordinates to data coordinates,
380e.g. for a mouse interaction where a certain pixel is clicked. If you
381don't use any interactive features of Flot, you may not need it.
382
383
384The rest of the options deal with the ticks.
385
386If you don't specify any ticks, a tick generator algorithm will make
387some for you. The algorithm has two passes. It first estimates how
388many ticks would be reasonable and uses this number to compute a nice
389round tick interval size. Then it generates the ticks.
390
391You can specify how many ticks the algorithm aims for by setting
392"ticks" to a number. The algorithm always tries to generate reasonably
393round tick values so even if you ask for three ticks, you might get
394five if that fits better with the rounding. If you don't want any
395ticks at all, set "ticks" to 0 or an empty array.
396
397Another option is to skip the rounding part and directly set the tick
398interval size with "tickSize". If you set it to 2, you'll get ticks at
3992, 4, 6, etc. Alternatively, you can specify that you just don't want
400ticks at a size less than a specific tick size with "minTickSize".
401Note that for time series, the format is an array like [2, "month"],
402see the next section.
403
404If you want to completely override the tick algorithm, you can specify
405an array for "ticks", either like this:
406
407```js
408ticks: [0, 1.2, 2.4]
409```
410
411Or like this where the labels are also customized:
412
413```js
414ticks: [[0, "zero"], [1.2, "one mark"], [2.4, "two marks"]]
415```
416
417You can mix the two if you like.
418 
419For extra flexibility you can specify a function as the "ticks"
420parameter. The function will be called with an object with the axis
421min and max and should return a ticks array. Here's a simplistic tick
422generator that spits out intervals of pi, suitable for use on the x
423axis for trigonometric functions:
424
425```js
426function piTickGenerator(axis) {
427    var res = [], i = Math.floor(axis.min / Math.PI);
428    do {
429        var v = i * Math.PI;
430        res.push([v, i + "\u03c0"]);
431        ++i;
432    } while (v < axis.max);
433    return res;
434}
435```
436
437You can control how the ticks look like with "tickDecimals", the
438number of decimals to display (default is auto-detected).
439
440Alternatively, for ultimate control over how ticks are formatted you can
441provide a function to "tickFormatter". The function is passed two
442parameters, the tick value and an axis object with information, and
443should return a string. The default formatter looks like this:
444
445```js
446function formatter(val, axis) {
447    return val.toFixed(axis.tickDecimals);
448}
449```
450
451The axis object has "min" and "max" with the range of the axis,
452"tickDecimals" with the number of decimals to round the value to and
453"tickSize" with the size of the interval between ticks as calculated
454by the automatic axis scaling algorithm (or specified by you). Here's
455an example of a custom formatter:
456
457```js
458function suffixFormatter(val, axis) {
459    if (val > 1000000)
460        return (val / 1000000).toFixed(axis.tickDecimals) + " MB";
461    else if (val > 1000)
462        return (val / 1000).toFixed(axis.tickDecimals) + " kB";
463    else
464        return val.toFixed(axis.tickDecimals) + " B";
465}
466```
467
468"labelWidth" and "labelHeight" specifies a fixed size of the tick
469labels in pixels. They're useful in case you need to align several
470plots. "reserveSpace" means that even if an axis isn't shown, Flot
471should reserve space for it - it is useful in combination with
472labelWidth and labelHeight for aligning multi-axis charts.
473
474"tickLength" is the length of the tick lines in pixels. By default, the
475innermost axes will have ticks that extend all across the plot, while
476any extra axes use small ticks. A value of null means use the default,
477while a number means small ticks of that length - set it to 0 to hide
478the lines completely.
479
480If you set "alignTicksWithAxis" to the number of another axis, e.g.
481alignTicksWithAxis: 1, Flot will ensure that the autogenerated ticks
482of this axis are aligned with the ticks of the other axis. This may
483improve the looks, e.g. if you have one y axis to the left and one to
484the right, because the grid lines will then match the ticks in both
485ends. The trade-off is that the forced ticks won't necessarily be at
486natural places.
487
488
489## Multiple axes ##
490
491If you need more than one x axis or y axis, you need to specify for
492each data series which axis they are to use, as described under the
493format of the data series, e.g. { data: [...], yaxis: 2 } specifies
494that a series should be plotted against the second y axis.
495
496To actually configure that axis, you can't use the xaxis/yaxis options
497directly - instead there are two arrays in the options:
498
499```js
500xaxes: []
501yaxes: []
502```
503
504Here's an example of configuring a single x axis and two y axes (we
505can leave options of the first y axis empty as the defaults are fine):
506
507```js
508{
509    xaxes: [ { position: "top" } ],
510    yaxes: [ { }, { position: "right", min: 20 } ]
511}
512```
513
514The arrays get their default values from the xaxis/yaxis settings, so
515say you want to have all y axes start at zero, you can simply specify
516yaxis: { min: 0 } instead of adding a min parameter to all the axes.
517
518Generally, the various interfaces in Flot dealing with data points
519either accept an xaxis/yaxis parameter to specify which axis number to
520use (starting from 1), or lets you specify the coordinate directly as
521x2/x3/... or x2axis/x3axis/... instead of "x" or "xaxis".
522
523
524## Time series data ##
525
526Please note that it is now required to include the time plugin,
527jquery.flot.time.js, for time series support.
528
529Time series are a bit more difficult than scalar data because
530calendars don't follow a simple base 10 system. For many cases, Flot
531abstracts most of this away, but it can still be a bit difficult to
532get the data into Flot. So we'll first discuss the data format.
533
534The time series support in Flot is based on Javascript timestamps,
535i.e. everywhere a time value is expected or handed over, a Javascript
536timestamp number is used. This is a number, not a Date object. A
537Javascript timestamp is the number of milliseconds since January 1,
5381970 00:00:00 UTC. This is almost the same as Unix timestamps, except it's
539in milliseconds, so remember to multiply by 1000!
540
541You can see a timestamp like this
542
543```js
544alert((new Date()).getTime())
545```
546
547There are different schools of thought when it comes to display of
548timestamps. Many will want the timestamps to be displayed according to
549a certain time zone, usually the time zone in which the data has been
550produced. Some want the localized experience, where the timestamps are
551displayed according to the local time of the visitor. Flot supports
552both. Optionally you can include a third-party library to get
553additional timezone support.
554
555Default behavior is that Flot always displays timestamps according to
556UTC. The reason being that the core Javascript Date object does not
557support other fixed time zones. Often your data is at another time
558zone, so it may take a little bit of tweaking to work around this
559limitation.
560
561The easiest way to think about it is to pretend that the data
562production time zone is UTC, even if it isn't. So if you have a
563datapoint at 2002-02-20 08:00, you can generate a timestamp for eight
564o'clock UTC even if it really happened eight o'clock UTC+0200.
565
566In PHP you can get an appropriate timestamp with:
567
568```php
569strtotime("2002-02-20 UTC") * 1000
570```
571
572In Python you can get it with something like:
573
574```python
575calendar.timegm(datetime_object.timetuple()) * 1000
576```
577In Ruby you can get it using the `#to_i` method on the
578[`Time`](http://apidock.com/ruby/Time/to_i) object. If you're using the
579`active_support` gem (default for Ruby on Rails applications) `#to_i` is also
580available on the `DateTime` and `ActiveSupport::TimeWithZone` objects. You
581simply need to multiply the result by 1000:
582
583```ruby
584Time.now.to_i * 1000     # => 1383582043000
585# ActiveSupport examples:
586DateTime.now.to_i * 1000 # => 1383582043000
587ActiveSupport::TimeZone.new('Asia/Shanghai').now.to_i * 1000
588# => 1383582043000
589```
590
591In .NET you can get it with something like:
592
593```aspx
594public static int GetJavascriptTimestamp(System.DateTime input)
595{
596    System.TimeSpan span = new System.TimeSpan(System.DateTime.Parse("1/1/1970").Ticks);
597    System.DateTime time = input.Subtract(span);
598    return (long)(time.Ticks / 10000);
599}
600```
601
602Javascript also has some support for parsing date strings, so it is
603possible to generate the timestamps manually client-side.
604
605If you've already got the real UTC timestamp, it's too late to use the
606pretend trick described above. But you can fix up the timestamps by
607adding the time zone offset, e.g. for UTC+0200 you would add 2 hours
608to the UTC timestamp you got. Then it'll look right on the plot. Most
609programming environments have some means of getting the timezone
610offset for a specific date (note that you need to get the offset for
611each individual timestamp to account for daylight savings).
612
613The alternative with core Javascript is to interpret the timestamps
614according to the time zone that the visitor is in, which means that
615the ticks will shift with the time zone and daylight savings of each
616visitor. This behavior is enabled by setting the axis option
617"timezone" to the value "browser".
618
619If you need more time zone functionality than this, there is still
620another option. If you include the "timezone-js" library
621<https://github.com/mde/timezone-js> in the page and set axis.timezone
622to a value recognized by said library, Flot will use timezone-js to
623interpret the timestamps according to that time zone.
624
625Once you've gotten the timestamps into the data and specified "time"
626as the axis mode, Flot will automatically generate relevant ticks and
627format them. As always, you can tweak the ticks via the "ticks" option
628- just remember that the values should be timestamps (numbers), not
629Date objects.
630
631Tick generation and formatting can also be controlled separately
632through the following axis options:
633
634```js
635minTickSize: array
636timeformat: null or format string
637monthNames: null or array of size 12 of strings
638dayNames: null or array of size 7 of strings
639twelveHourClock: boolean
640```
641
642Here "timeformat" is a format string to use. You might use it like
643this:
644
645```js
646xaxis: {
647    mode: "time",
648    timeformat: "%Y/%m/%d"
649}
650```
651
652This will result in tick labels like "2000/12/24". A subset of the
653standard strftime specifiers are supported (plus the nonstandard %q):
654
655```js
656%a: weekday name (customizable)
657%b: month name (customizable)
658%d: day of month, zero-padded (01-31)
659%e: day of month, space-padded ( 1-31)
660%H: hours, 24-hour time, zero-padded (00-23)
661%I: hours, 12-hour time, zero-padded (01-12)
662%m: month, zero-padded (01-12)
663%M: minutes, zero-padded (00-59)
664%q: quarter (1-4)
665%S: seconds, zero-padded (00-59)
666%y: year (two digits)
667%Y: year (four digits)
668%p: am/pm
669%P: AM/PM (uppercase version of %p)
670%w: weekday as number (0-6, 0 being Sunday)
671```
672
673Flot 0.8 switched from %h to the standard %H hours specifier. The %h specifier
674is still available, for backwards-compatibility, but is deprecated and
675scheduled to be removed permanently with the release of version 1.0.
676
677You can customize the month names with the "monthNames" option. For
678instance, for Danish you might specify:
679
680```js
681monthNames: ["jan", "feb", "mar", "apr", "maj", "jun", "jul", "aug", "sep", "okt", "nov", "dec"]
682```
683
684Similarly you can customize the weekday names with the "dayNames"
685option. An example in French:
686
687```js
688dayNames: ["dim", "lun", "mar", "mer", "jeu", "ven", "sam"]
689```
690
691If you set "twelveHourClock" to true, the autogenerated timestamps
692will use 12 hour AM/PM timestamps instead of 24 hour. This only
693applies if you have not set "timeformat". Use the "%I" and "%p" or
694"%P" options if you want to build your own format string with 12-hour
695times.
696
697If the Date object has a strftime property (and it is a function), it
698will be used instead of the built-in formatter. Thus you can include
699a strftime library such as http://hacks.bluesmoon.info/strftime/ for
700more powerful date/time formatting.
701
702If everything else fails, you can control the formatting by specifying
703a custom tick formatter function as usual. Here's a simple example
704which will format December 24 as 24/12:
705
706```js
707tickFormatter: function (val, axis) {
708    var d = new Date(val);
709    return d.getUTCDate() + "/" + (d.getUTCMonth() + 1);
710}
711```
712
713Note that for the time mode "tickSize" and "minTickSize" are a bit
714special in that they are arrays on the form "[value, unit]" where unit
715is one of "second", "minute", "hour", "day", "month" and "year". So
716you can specify
717
718```js
719minTickSize: [1, "month"]
720```
721
722to get a tick interval size of at least 1 month and correspondingly,
723if axis.tickSize is [2, "day"] in the tick formatter, the ticks have
724been produced with two days in-between.
725
726
727## Customizing the data series ##
728
729```js
730series: {
731    lines, points, bars: {
732        show: boolean
733        lineWidth: number
734        fill: boolean or number
735        fillColor: null or color/gradient
736    }
737
738    lines, bars: {
739        zero: boolean
740    }
741
742    points: {
743        radius: number
744        symbol: "circle" or function
745    }
746
747    bars: {
748        barWidth: number
749        align: "left", "right" or "center"
750        horizontal: boolean
751    }
752
753    lines: {
754        steps: boolean
755    }
756
757    shadowSize: number
758    highlightColor: color or number
759}
760
761colors: [ color1, color2, ... ]
762```
763
764The options inside "series: {}" are copied to each of the series. So
765you can specify that all series should have bars by putting it in the
766global options, or override it for individual series by specifying
767bars in a particular the series object in the array of data.
768 
769The most important options are "lines", "points" and "bars" that
770specify whether and how lines, points and bars should be shown for
771each data series. In case you don't specify anything at all, Flot will
772default to showing lines (you can turn this off with
773lines: { show: false }). You can specify the various types
774independently of each other, and Flot will happily draw each of them
775in turn (this is probably only useful for lines and points), e.g.
776
777```js
778var options = {
779    series: {
780        lines: { show: true, fill: true, fillColor: "rgba(255, 255, 255, 0.8)" },
781        points: { show: true, fill: false }
782    }
783};
784```
785
786"lineWidth" is the thickness of the line or outline in pixels. You can
787set it to 0 to prevent a line or outline from being drawn; this will
788also hide the shadow.
789
790"fill" is whether the shape should be filled. For lines, this produces
791area graphs. You can use "fillColor" to specify the color of the fill.
792If "fillColor" evaluates to false (default for everything except
793points which are filled with white), the fill color is auto-set to the
794color of the data series. You can adjust the opacity of the fill by
795setting fill to a number between 0 (fully transparent) and 1 (fully
796opaque).
797
798For bars, fillColor can be a gradient, see the gradient documentation
799below. "barWidth" is the width of the bars in units of the x axis (or
800the y axis if "horizontal" is true), contrary to most other measures
801that are specified in pixels. For instance, for time series the unit
802is milliseconds so 24 * 60 * 60 * 1000 produces bars with the width of
803a day. "align" specifies whether a bar should be left-aligned
804(default), right-aligned or centered on top of the value it represents.
805When "horizontal" is on, the bars are drawn horizontally, i.e. from the
806y axis instead of the x axis; note that the bar end points are still
807defined in the same way so you'll probably want to swap the
808coordinates if you've been plotting vertical bars first.
809
810Area and bar charts normally start from zero, regardless of the data's range.
811This is because they convey information through size, and starting from a
812different value would distort their meaning. In cases where the fill is purely
813for decorative purposes, however, "zero" allows you to override this behavior.
814It defaults to true for filled lines and bars; setting it to false tells the
815series to use the same automatic scaling as an un-filled line.
816
817For lines, "steps" specifies whether two adjacent data points are
818connected with a straight (possibly diagonal) line or with first a
819horizontal and then a vertical line. Note that this transforms the
820data by adding extra points.
821
822For points, you can specify the radius and the symbol. The only
823built-in symbol type is circles, for other types you can use a plugin
824or define them yourself by specifying a callback:
825
826```js
827function cross(ctx, x, y, radius, shadow) {
828    var size = radius * Math.sqrt(Math.PI) / 2;
829    ctx.moveTo(x - size, y - size);
830    ctx.lineTo(x + size, y + size);
831    ctx.moveTo(x - size, y + size);
832    ctx.lineTo(x + size, y - size);
833}
834```
835
836The parameters are the drawing context, x and y coordinates of the
837center of the point, a radius which corresponds to what the circle
838would have used and whether the call is to draw a shadow (due to
839limited canvas support, shadows are currently faked through extra
840draws). It's good practice to ensure that the area covered by the
841symbol is the same as for the circle with the given radius, this
842ensures that all symbols have approximately the same visual weight.
843
844"shadowSize" is the default size of shadows in pixels. Set it to 0 to
845remove shadows.
846
847"highlightColor" is the default color of the translucent overlay used
848to highlight the series when the mouse hovers over it.
849
850The "colors" array specifies a default color theme to get colors for
851the data series from. You can specify as many colors as you like, like
852this:
853
854```js
855colors: ["#d18b2c", "#dba255", "#919733"]
856```
857
858If there are more data series than colors, Flot will try to generate
859extra colors by lightening and darkening colors in the theme.
860
861
862## Customizing the grid ##
863
864```js
865grid: {
866    show: boolean
867    aboveData: boolean
868    color: color
869    backgroundColor: color/gradient or null
870    margin: number or margin object
871    labelMargin: number
872    axisMargin: number
873    markings: array of markings or (fn: axes -> array of markings)
874    borderWidth: number or object with "top", "right", "bottom" and "left" properties with different widths
875    borderColor: color or null or object with "top", "right", "bottom" and "left" properties with different colors
876    minBorderMargin: number or null
877    clickable: boolean
878    hoverable: boolean
879    autoHighlight: boolean
880    mouseActiveRadius: number
881}
882
883interaction: {
884    redrawOverlayInterval: number or -1
885}
886```
887
888The grid is the thing with the axes and a number of ticks. Many of the
889things in the grid are configured under the individual axes, but not
890all. "color" is the color of the grid itself whereas "backgroundColor"
891specifies the background color inside the grid area, here null means
892that the background is transparent. You can also set a gradient, see
893the gradient documentation below.
894
895You can turn off the whole grid including tick labels by setting
896"show" to false. "aboveData" determines whether the grid is drawn
897above the data or below (below is default).
898
899"margin" is the space in pixels between the canvas edge and the grid,
900which can be either a number or an object with individual margins for
901each side, in the form:
902
903```js
904margin: {
905    top: top margin in pixels
906    left: left margin in pixels
907    bottom: bottom margin in pixels
908    right: right margin in pixels
909}
910```
911
912"labelMargin" is the space in pixels between tick labels and axis
913line, and "axisMargin" is the space in pixels between axes when there
914are two next to each other.
915
916"borderWidth" is the width of the border around the plot. Set it to 0
917to disable the border. Set it to an object with "top", "right",
918"bottom" and "left" properties to use different widths. You can
919also set "borderColor" if you want the border to have a different color
920than the grid lines. Set it to an object with "top", "right", "bottom"
921and "left" properties to use different colors. "minBorderMargin" controls
922the default minimum margin around the border - it's used to make sure
923that points aren't accidentally clipped by the canvas edge so by default
924the value is computed from the point radius.
925
926"markings" is used to draw simple lines and rectangular areas in the
927background of the plot. You can either specify an array of ranges on
928the form { xaxis: { from, to }, yaxis: { from, to } } (with multiple
929axes, you can specify coordinates for other axes instead, e.g. as
930x2axis/x3axis/...) or with a function that returns such an array given
931the axes for the plot in an object as the first parameter.
932
933You can set the color of markings by specifying "color" in the ranges
934object. Here's an example array:
935
936```js
937markings: [ { xaxis: { from: 0, to: 2 }, yaxis: { from: 10, to: 10 }, color: "#bb0000" }, ... ]
938```
939
940If you leave out one of the values, that value is assumed to go to the
941border of the plot. So for example if you only specify { xaxis: {
942from: 0, to: 2 } } it means an area that extends from the top to the
943bottom of the plot in the x range 0-2.
944
945A line is drawn if from and to are the same, e.g.
946
947```js
948markings: [ { yaxis: { from: 1, to: 1 } }, ... ]
949```
950
951would draw a line parallel to the x axis at y = 1. You can control the
952line width with "lineWidth" in the range object.
953
954An example function that makes vertical stripes might look like this:
955
956```js
957markings: function (axes) {
958    var markings = [];
959    for (var x = Math.floor(axes.xaxis.min); x < axes.xaxis.max; x += 2)
960        markings.push({ xaxis: { from: x, to: x + 1 } });
961    return markings;
962}
963```
964
965If you set "clickable" to true, the plot will listen for click events
966on the plot area and fire a "plotclick" event on the placeholder with
967a position and a nearby data item object as parameters. The coordinates
968are available both in the unit of the axes (not in pixels) and in
969global screen coordinates.
970
971Likewise, if you set "hoverable" to true, the plot will listen for
972mouse move events on the plot area and fire a "plothover" event with
973the same parameters as the "plotclick" event. If "autoHighlight" is
974true (the default), nearby data items are highlighted automatically.
975If needed, you can disable highlighting and control it yourself with
976the highlight/unhighlight plot methods described elsewhere.
977
978You can use "plotclick" and "plothover" events like this:
979
980```js
981$.plot($("#placeholder"), [ d ], { grid: { clickable: true } });
982
983$("#placeholder").bind("plotclick", function (event, pos, item) {
984    alert("You clicked at " + pos.x + ", " + pos.y);
985    // axis coordinates for other axes, if present, are in pos.x2, pos.x3, ...
986    // if you need global screen coordinates, they are pos.pageX, pos.pageY
987
988    if (item) {
989        highlight(item.series, item.datapoint);
990        alert("You clicked a point!");
991    }
992});
993```
994
995The item object in this example is either null or a nearby object on the form:
996
997```js
998item: {
999    datapoint: the point, e.g. [0, 2]
1000    dataIndex: the index of the point in the data array
1001    series: the series object
1002    seriesIndex: the index of the series
1003    pageX, pageY: the global screen coordinates of the point
1004}
1005```
1006
1007For instance, if you have specified the data like this
1008
1009```js
1010$.plot($("#placeholder"), [ { label: "Foo", data: [[0, 10], [7, 3]] } ], ...);
1011```
1012
1013and the mouse is near the point (7, 3), "datapoint" is [7, 3],
1014"dataIndex" will be 1, "series" is a normalized series object with
1015among other things the "Foo" label in series.label and the color in
1016series.color, and "seriesIndex" is 0. Note that plugins and options
1017that transform the data can shift the indexes from what you specified
1018in the original data array.
1019
1020If you use the above events to update some other information and want
1021to clear out that info in case the mouse goes away, you'll probably
1022also need to listen to "mouseout" events on the placeholder div.
1023
1024"mouseActiveRadius" specifies how far the mouse can be from an item
1025and still activate it. If there are two or more points within this
1026radius, Flot chooses the closest item. For bars, the top-most bar
1027(from the latest specified data series) is chosen.
1028
1029If you want to disable interactivity for a specific data series, you
1030can set "hoverable" and "clickable" to false in the options for that
1031series, like this:
1032
1033```js
1034{ data: [...], label: "Foo", clickable: false }
1035```
1036
1037"redrawOverlayInterval" specifies the maximum time to delay a redraw
1038of interactive things (this works as a rate limiting device). The
1039default is capped to 60 frames per second. You can set it to -1 to
1040disable the rate limiting.
1041
1042
1043## Specifying gradients ##
1044
1045A gradient is specified like this:
1046
1047```js
1048{ colors: [ color1, color2, ... ] }
1049```
1050
1051For instance, you might specify a background on the grid going from
1052black to gray like this:
1053
1054```js
1055grid: {
1056    backgroundColor: { colors: ["#000", "#999"] }
1057}
1058```
1059
1060For the series you can specify the gradient as an object that
1061specifies the scaling of the brightness and the opacity of the series
1062color, e.g.
1063
1064```js
1065{ colors: [{ opacity: 0.8 }, { brightness: 0.6, opacity: 0.8 } ] }
1066```
1067
1068where the first color simply has its alpha scaled, whereas the second
1069is also darkened. For instance, for bars the following makes the bars
1070gradually disappear, without outline:
1071
1072```js
1073bars: {
1074    show: true,
1075    lineWidth: 0,
1076    fill: true,
1077    fillColor: { colors: [ { opacity: 0.8 }, { opacity: 0.1 } ] }
1078}
1079```
1080
1081Flot currently only supports vertical gradients drawn from top to
1082bottom because that's what works with IE.
1083
1084
1085## Plot Methods ##
1086
1087The Plot object returned from the plot function has some methods you
1088can call:
1089
1090 - highlight(series, datapoint)
1091
1092    Highlight a specific datapoint in the data series. You can either
1093    specify the actual objects, e.g. if you got them from a
1094    "plotclick" event, or you can specify the indices, e.g.
1095    highlight(1, 3) to highlight the fourth point in the second series
1096    (remember, zero-based indexing).
1097
1098 - unhighlight(series, datapoint) or unhighlight()
1099
1100    Remove the highlighting of the point, same parameters as
1101    highlight.
1102
1103    If you call unhighlight with no parameters, e.g. as
1104    plot.unhighlight(), all current highlights are removed.
1105
1106 - setData(data)
1107
1108    You can use this to reset the data used. Note that axis scaling,
1109    ticks, legend etc. will not be recomputed (use setupGrid() to do
1110    that). You'll probably want to call draw() afterwards.
1111
1112    You can use this function to speed up redrawing a small plot if
1113    you know that the axes won't change. Put in the new data with
1114    setData(newdata), call draw(), and you're good to go. Note that
1115    for large datasets, almost all the time is consumed in draw()
1116    plotting the data so in this case don't bother.
1117
1118 - setupGrid()
1119
1120    Recalculate and set axis scaling, ticks, legend etc.
1121
1122    Note that because of the drawing model of the canvas, this
1123    function will immediately redraw (actually reinsert in the DOM)
1124    the labels and the legend, but not the actual tick lines because
1125    they're drawn on the canvas. You need to call draw() to get the
1126    canvas redrawn.
1127
1128 - draw()
1129
1130    Redraws the plot canvas.
1131
1132 - triggerRedrawOverlay()
1133
1134    Schedules an update of an overlay canvas used for drawing
1135    interactive things like a selection and point highlights. This
1136    is mostly useful for writing plugins. The redraw doesn't happen
1137    immediately, instead a timer is set to catch multiple successive
1138    redraws (e.g. from a mousemove). You can get to the overlay by
1139    setting up a drawOverlay hook.
1140
1141 - width()/height()
1142
1143    Gets the width and height of the plotting area inside the grid.
1144    This is smaller than the canvas or placeholder dimensions as some
1145    extra space is needed (e.g. for labels).
1146
1147 - offset()
1148
1149    Returns the offset of the plotting area inside the grid relative
1150    to the document, useful for instance for calculating mouse
1151    positions (event.pageX/Y minus this offset is the pixel position
1152    inside the plot).
1153
1154 - pointOffset({ x: xpos, y: ypos })
1155
1156    Returns the calculated offset of the data point at (x, y) in data
1157    space within the placeholder div. If you are working with multiple
1158    axes, you can specify the x and y axis references, e.g.
1159
1160    ```js
1161      o = pointOffset({ x: xpos, y: ypos, xaxis: 2, yaxis: 3 })
1162      // o.left and o.top now contains the offset within the div
1163    ````
1164
1165 - resize()
1166
1167    Tells Flot to resize the drawing canvas to the size of the
1168    placeholder. You need to run setupGrid() and draw() afterwards as
1169    canvas resizing is a destructive operation. This is used
1170    internally by the resize plugin.
1171
1172 - shutdown()
1173
1174    Cleans up any event handlers Flot has currently registered. This
1175    is used internally.
1176
1177There are also some members that let you peek inside the internal
1178workings of Flot which is useful in some cases. Note that if you change
1179something in the objects returned, you're changing the objects used by
1180Flot to keep track of its state, so be careful.
1181
1182  - getData()
1183
1184    Returns an array of the data series currently used in normalized
1185    form with missing settings filled in according to the global
1186    options. So for instance to find out what color Flot has assigned
1187    to the data series, you could do this:
1188
1189    ```js
1190    var series = plot.getData();
1191    for (var i = 0; i < series.length; ++i)
1192        alert(series[i].color);
1193    ```
1194
1195    A notable other interesting field besides color is datapoints
1196    which has a field "points" with the normalized data points in a
1197    flat array (the field "pointsize" is the increment in the flat
1198    array to get to the next point so for a dataset consisting only of
1199    (x,y) pairs it would be 2).
1200
1201  - getAxes()
1202
1203    Gets an object with the axes. The axes are returned as the
1204    attributes of the object, so for instance getAxes().xaxis is the
1205    x axis.
1206
1207    Various things are stuffed inside an axis object, e.g. you could
1208    use getAxes().xaxis.ticks to find out what the ticks are for the
1209    xaxis. Two other useful attributes are p2c and c2p, functions for
1210    transforming from data point space to the canvas plot space and
1211    back. Both returns values that are offset with the plot offset.
1212    Check the Flot source code for the complete set of attributes (or
1213    output an axis with console.log() and inspect it).
1214
1215    With multiple axes, the extra axes are returned as x2axis, x3axis,
1216    etc., e.g. getAxes().y2axis is the second y axis. You can check
1217    y2axis.used to see whether the axis is associated with any data
1218    points and y2axis.show to see if it is currently shown.
1219 
1220  - getPlaceholder()
1221
1222    Returns placeholder that the plot was put into. This can be useful
1223    for plugins for adding DOM elements or firing events.
1224
1225  - getCanvas()
1226
1227    Returns the canvas used for drawing in case you need to hack on it
1228    yourself. You'll probably need to get the plot offset too.
1229 
1230  - getPlotOffset()
1231
1232    Gets the offset that the grid has within the canvas as an object
1233    with distances from the canvas edges as "left", "right", "top",
1234    "bottom". I.e., if you draw a circle on the canvas with the center
1235    placed at (left, top), its center will be at the top-most, left
1236    corner of the grid.
1237
1238  - getOptions()
1239
1240    Gets the options for the plot, normalized, with default values
1241    filled in. You get a reference to actual values used by Flot, so
1242    if you modify the values in here, Flot will use the new values.
1243    If you change something, you probably have to call draw() or
1244    setupGrid() or triggerRedrawOverlay() to see the change.
1245   
1246
1247## Hooks ##
1248
1249In addition to the public methods, the Plot object also has some hooks
1250that can be used to modify the plotting process. You can install a
1251callback function at various points in the process, the function then
1252gets access to the internal data structures in Flot.
1253
1254Here's an overview of the phases Flot goes through:
1255
1256  1. Plugin initialization, parsing options
1257 
1258  2. Constructing the canvases used for drawing
1259
1260  3. Set data: parsing data specification, calculating colors,
1261     copying raw data points into internal format,
1262     normalizing them, finding max/min for axis auto-scaling
1263
1264  4. Grid setup: calculating axis spacing, ticks, inserting tick
1265     labels, the legend
1266
1267  5. Draw: drawing the grid, drawing each of the series in turn
1268
1269  6. Setting up event handling for interactive features
1270
1271  7. Responding to events, if any
1272
1273  8. Shutdown: this mostly happens in case a plot is overwritten
1274
1275Each hook is simply a function which is put in the appropriate array.
1276You can add them through the "hooks" option, and they are also available
1277after the plot is constructed as the "hooks" attribute on the returned
1278plot object, e.g.
1279
1280```js
1281  // define a simple draw hook
1282  function hellohook(plot, canvascontext) { alert("hello!"); };
1283
1284  // pass it in, in an array since we might want to specify several
1285  var plot = $.plot(placeholder, data, { hooks: { draw: [hellohook] } });
1286
1287  // we can now find it again in plot.hooks.draw[0] unless a plugin
1288  // has added other hooks
1289```
1290
1291The available hooks are described below. All hook callbacks get the
1292plot object as first parameter. You can find some examples of defined
1293hooks in the plugins bundled with Flot.
1294
1295 - processOptions  [phase 1]
1296
1297    ```function(plot, options)```
1298   
1299    Called after Flot has parsed and merged options. Useful in the
1300    instance where customizations beyond simple merging of default
1301    values is needed. A plugin might use it to detect that it has been
1302    enabled and then turn on or off other options.
1303
1304 
1305 - processRawData  [phase 3]
1306
1307    ```function(plot, series, data, datapoints)```
1308 
1309    Called before Flot copies and normalizes the raw data for the given
1310    series. If the function fills in datapoints.points with normalized
1311    points and sets datapoints.pointsize to the size of the points,
1312    Flot will skip the copying/normalization step for this series.
1313   
1314    In any case, you might be interested in setting datapoints.format,
1315    an array of objects for specifying how a point is normalized and
1316    how it interferes with axis scaling. It accepts the following options:
1317
1318    ```js
1319    {
1320        x, y: boolean,
1321        number: boolean,
1322        required: boolean,
1323        defaultValue: value,
1324        autoscale: boolean
1325    }
1326    ```
1327
1328    "x" and "y" specify whether the value is plotted against the x or y axis,
1329    and is currently used only to calculate axis min-max ranges. The default
1330    format array, for example, looks like this:
1331
1332    ```js
1333    [
1334        { x: true, number: true, required: true },
1335        { y: true, number: true, required: true }
1336    ]
1337    ```
1338
1339    This indicates that a point, i.e. [0, 25], consists of two values, with the
1340    first being plotted on the x axis and the second on the y axis.
1341
1342    If "number" is true, then the value must be numeric, and is set to null if
1343    it cannot be converted to a number.
1344
1345    "defaultValue" provides a fallback in case the original value is null. This
1346    is for instance handy for bars, where one can omit the third coordinate
1347    (the bottom of the bar), which then defaults to zero.
1348
1349    If "required" is true, then the value must exist (be non-null) for the
1350    point as a whole to be valid. If no value is provided, then the entire
1351    point is cleared out with nulls, turning it into a gap in the series.
1352
1353    "autoscale" determines whether the value is considered when calculating an
1354    automatic min-max range for the axes that the value is plotted against.
1355
1356 - processDatapoints  [phase 3]
1357
1358    ```function(plot, series, datapoints)```
1359
1360    Called after normalization of the given series but before finding
1361    min/max of the data points. This hook is useful for implementing data
1362    transformations. "datapoints" contains the normalized data points in
1363    a flat array as datapoints.points with the size of a single point
1364    given in datapoints.pointsize. Here's a simple transform that
1365    multiplies all y coordinates by 2:
1366
1367    ```js
1368    function multiply(plot, series, datapoints) {
1369        var points = datapoints.points, ps = datapoints.pointsize;
1370        for (var i = 0; i < points.length; i += ps)
1371            points[i + 1] *= 2;
1372    }
1373    ```
1374
1375    Note that you must leave datapoints in a good condition as Flot
1376    doesn't check it or do any normalization on it afterwards.
1377
1378 - processOffset  [phase 4]
1379
1380    ```function(plot, offset)```
1381
1382    Called after Flot has initialized the plot's offset, but before it
1383    draws any axes or plot elements. This hook is useful for customizing
1384    the margins between the grid and the edge of the canvas. "offset" is
1385    an object with attributes "top", "bottom", "left" and "right",
1386    corresponding to the margins on the four sides of the plot.
1387
1388 - drawBackground [phase 5]
1389
1390    ```function(plot, canvascontext)```
1391
1392    Called before all other drawing operations. Used to draw backgrounds
1393    or other custom elements before the plot or axes have been drawn.
1394
1395 - drawSeries  [phase 5]
1396
1397    ```function(plot, canvascontext, series)```
1398
1399    Hook for custom drawing of a single series. Called just before the
1400    standard drawing routine has been called in the loop that draws
1401    each series.
1402
1403 - draw  [phase 5]
1404
1405    ```function(plot, canvascontext)```
1406
1407    Hook for drawing on the canvas. Called after the grid is drawn
1408    (unless it's disabled or grid.aboveData is set) and the series have
1409    been plotted (in case any points, lines or bars have been turned
1410    on). For examples of how to draw things, look at the source code.
1411
1412 - bindEvents  [phase 6]
1413
1414    ```function(plot, eventHolder)```
1415
1416    Called after Flot has setup its event handlers. Should set any
1417    necessary event handlers on eventHolder, a jQuery object with the
1418    canvas, e.g.
1419
1420    ```js
1421    function (plot, eventHolder) {
1422        eventHolder.mousedown(function (e) {
1423            alert("You pressed the mouse at " + e.pageX + " " + e.pageY);
1424        });
1425    }
1426    ```
1427
1428    Interesting events include click, mousemove, mouseup/down. You can
1429    use all jQuery events. Usually, the event handlers will update the
1430    state by drawing something (add a drawOverlay hook and call
1431    triggerRedrawOverlay) or firing an externally visible event for
1432    user code. See the crosshair plugin for an example.
1433     
1434    Currently, eventHolder actually contains both the static canvas
1435    used for the plot itself and the overlay canvas used for
1436    interactive features because some versions of IE get the stacking
1437    order wrong. The hook only gets one event, though (either for the
1438    overlay or for the static canvas).
1439
1440    Note that custom plot events generated by Flot are not generated on
1441    eventHolder, but on the div placeholder supplied as the first
1442    argument to the plot call. You can get that with
1443    plot.getPlaceholder() - that's probably also the one you should use
1444    if you need to fire a custom event.
1445
1446 - drawOverlay  [phase 7]
1447
1448    ```function (plot, canvascontext)```
1449
1450    The drawOverlay hook is used for interactive things that need a
1451    canvas to draw on. The model currently used by Flot works the way
1452    that an extra overlay canvas is positioned on top of the static
1453    canvas. This overlay is cleared and then completely redrawn
1454    whenever something interesting happens. This hook is called when
1455    the overlay canvas is to be redrawn.
1456
1457    "canvascontext" is the 2D context of the overlay canvas. You can
1458    use this to draw things. You'll most likely need some of the
1459    metrics computed by Flot, e.g. plot.width()/plot.height(). See the
1460    crosshair plugin for an example.
1461
1462 - shutdown  [phase 8]
1463
1464    ```function (plot, eventHolder)```
1465
1466    Run when plot.shutdown() is called, which usually only happens in
1467    case a plot is overwritten by a new plot. If you're writing a
1468    plugin that adds extra DOM elements or event handlers, you should
1469    add a callback to clean up after you. Take a look at the section in
1470    the [PLUGINS](PLUGINS.md) document for more info.
1471
1472   
1473## Plugins ##
1474
1475Plugins extend the functionality of Flot. To use a plugin, simply
1476include its Javascript file after Flot in the HTML page.
1477
1478If you're worried about download size/latency, you can concatenate all
1479the plugins you use, and Flot itself for that matter, into one big file
1480(make sure you get the order right), then optionally run it through a
1481Javascript minifier such as YUI Compressor.
1482
1483Here's a brief explanation of how the plugin plumbings work:
1484
1485Each plugin registers itself in the global array $.plot.plugins. When
1486you make a new plot object with $.plot, Flot goes through this array
1487calling the "init" function of each plugin and merging default options
1488from the "option" attribute of the plugin. The init function gets a
1489reference to the plot object created and uses this to register hooks
1490and add new public methods if needed.
1491
1492See the [PLUGINS](PLUGINS.md) document for details on how to write a plugin. As the
1493above description hints, it's actually pretty easy.
1494
1495
1496## Version number ##
1497
1498The version number of Flot is available in ```$.plot.version```.
Note: See TracBrowser for help on using the repository browser.