File: API.md

package info (click to toggle)
flot 0.8.3+dfsg-1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, sid, stretch
  • size: 1,828 kB
  • ctags: 457
  • sloc: makefile: 49; sh: 48
file content (1498 lines) | stat: -rw-r--r-- 53,572 bytes parent folder | download | duplicates (3)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
# Flot Reference #

**Table of Contents**

[Introduction](#introduction)
| [Data Format](#data-format)
| [Plot Options](#plot-options)
| [Customizing the legend](#customizing-the-legend)
| [Customizing the axes](#customizing-the-axes)
| [Multiple axes](#multiple-axes)
| [Time series data](#time-series-data)
| [Customizing the data series](#customizing-the-data-series)
| [Customizing the grid](#customizing-the-grid)
| [Specifying gradients](#specifying-gradients)
| [Plot Methods](#plot-methods)
| [Hooks](#hooks)
| [Plugins](#plugins)
| [Version number](#version-number)

---

## Introduction ##

Consider a call to the plot function:

```js
var plot = $.plot(placeholder, data, options)
```

The placeholder is a jQuery object or DOM element or jQuery expression
that the plot will be put into. This placeholder needs to have its
width and height set as explained in the [README](README.md) (go read that now if
you haven't, it's short). The plot will modify some properties of the
placeholder so it's recommended you simply pass in a div that you
don't use for anything else. Make sure you check any fancy styling
you apply to the div, e.g. background images have been reported to be a
problem on IE 7.

The plot function can also be used as a jQuery chainable property.  This form
naturally can't return the plot object directly, but you can still access it
via the 'plot' data key, like this:

```js
var plot = $("#placeholder").plot(data, options).data("plot");
```

The format of the data is documented below, as is the available
options. The plot object returned from the call has some methods you
can call. These are documented separately below.

Note that in general Flot gives no guarantees if you change any of the
objects you pass in to the plot function or get out of it since
they're not necessarily deep-copied.


## Data Format ##

The data is an array of data series:

```js
[ series1, series2, ... ]
```

A series can either be raw data or an object with properties. The raw
data format is an array of points:

```js
[ [x1, y1], [x2, y2], ... ]
```

E.g.

```js
[ [1, 3], [2, 14.01], [3.5, 3.14] ]
```

Note that to simplify the internal logic in Flot both the x and y
values must be numbers (even if specifying time series, see below for
how to do this). This is a common problem because you might retrieve
data from the database and serialize them directly to JSON without
noticing the wrong type. If you're getting mysterious errors, double
check that you're inputting numbers and not strings.

If a null is specified as a point or if one of the coordinates is null
or couldn't be converted to a number, the point is ignored when
drawing. As a special case, a null value for lines is interpreted as a
line segment end, i.e. the points before and after the null value are
not connected.

Lines and points take two coordinates. For filled lines and bars, you
can specify a third coordinate which is the bottom of the filled
area/bar (defaults to 0).

The format of a single series object is as follows:

```js
{
    color: color or number
    data: rawdata
    label: string
    lines: specific lines options
    bars: specific bars options
    points: specific points options
    xaxis: number
    yaxis: number
    clickable: boolean
    hoverable: boolean
    shadowSize: number
    highlightColor: color or number
}
```

You don't have to specify any of them except the data, the rest are
options that will get default values. Typically you'd only specify
label and data, like this:

```js
{
    label: "y = 3",
    data: [[0, 3], [10, 3]]
}
```

The label is used for the legend, if you don't specify one, the series
will not show up in the legend.

If you don't specify color, the series will get a color from the
auto-generated colors. The color is either a CSS color specification
(like "rgb(255, 100, 123)") or an integer that specifies which of
auto-generated colors to select, e.g. 0 will get color no. 0, etc.

The latter is mostly useful if you let the user add and remove series,
in which case you can hard-code the color index to prevent the colors
from jumping around between the series.

The "xaxis" and "yaxis" options specify which axis to use. The axes
are numbered from 1 (default), so { yaxis: 2} means that the series
should be plotted against the second y axis.

"clickable" and "hoverable" can be set to false to disable
interactivity for specific series if interactivity is turned on in
the plot, see below.

The rest of the options are all documented below as they are the same
as the default options passed in via the options parameter in the plot
commmand. When you specify them for a specific data series, they will
override the default options for the plot for that data series.

Here's a complete example of a simple data specification:

```js
[ { label: "Foo", data: [ [10, 1], [17, -14], [30, 5] ] },
  { label: "Bar", data: [ [11, 13], [19, 11], [30, -7] ] }
]
```


## Plot Options ##

All options are completely optional. They are documented individually
below, to change them you just specify them in an object, e.g.

```js
var options = {
    series: {
        lines: { show: true },
        points: { show: true }
    }
};
	
$.plot(placeholder, data, options);
```


## Customizing the legend ##

```js
legend: {
    show: boolean
    labelFormatter: null or (fn: string, series object -> string)
    labelBoxBorderColor: color
    noColumns: number
    position: "ne" or "nw" or "se" or "sw"
    margin: number of pixels or [x margin, y margin]
    backgroundColor: null or color
    backgroundOpacity: number between 0 and 1
    container: null or jQuery object/DOM element/jQuery expression
    sorted: null/false, true, "ascending", "descending", "reverse", or a comparator
}
```

The legend is generated as a table with the data series labels and
small label boxes with the color of the series. If you want to format
the labels in some way, e.g. make them to links, you can pass in a
function for "labelFormatter". Here's an example that makes them
clickable:

```js
labelFormatter: function(label, series) {
    // series is the series object for the label
    return '<a href="#' + label + '">' + label + '</a>';
}
```

To prevent a series from showing up in the legend, simply have the function
return null.

"noColumns" is the number of columns to divide the legend table into.
"position" specifies the overall placement of the legend within the
plot (top-right, top-left, etc.) and margin the distance to the plot
edge (this can be either a number or an array of two numbers like [x,
y]). "backgroundColor" and "backgroundOpacity" specifies the
background. The default is a partly transparent auto-detected
background.

If you want the legend to appear somewhere else in the DOM, you can
specify "container" as a jQuery object/expression to put the legend
table into. The "position" and "margin" etc. options will then be
ignored. Note that Flot will overwrite the contents of the container.

Legend entries appear in the same order as their series by default. If "sorted"
is "reverse" then they appear in the opposite order from their series. To sort
them alphabetically, you can specify true, "ascending" or "descending", where
true and "ascending" are equivalent.

You can also provide your own comparator function that accepts two
objects with "label" and "color" properties, and returns zero if they
are equal, a positive value if the first is greater than the second,
and a negative value if the first is less than the second.

```js
sorted: function(a, b) {
    // sort alphabetically in ascending order
    return a.label == b.label ? 0 : (
        a.label > b.label ? 1 : -1
    )
}
```


## Customizing the axes ##

```js
xaxis, yaxis: {
    show: null or true/false
    position: "bottom" or "top" or "left" or "right"
    mode: null or "time" ("time" requires jquery.flot.time.js plugin)
    timezone: null, "browser" or timezone (only makes sense for mode: "time")

    color: null or color spec
    tickColor: null or color spec
    font: null or font spec object

    min: null or number
    max: null or number
    autoscaleMargin: null or number
    
    transform: null or fn: number -> number
    inverseTransform: null or fn: number -> number
    
    ticks: null or number or ticks array or (fn: axis -> ticks array)
    tickSize: number or array
    minTickSize: number or array
    tickFormatter: (fn: number, object -> string) or string
    tickDecimals: null or number

    labelWidth: null or number
    labelHeight: null or number
    reserveSpace: null or true
    
    tickLength: null or number

    alignTicksWithAxis: null or number
}
```

All axes have the same kind of options. The following describes how to
configure one axis, see below for what to do if you've got more than
one x axis or y axis.

If you don't set the "show" option (i.e. it is null), visibility is
auto-detected, i.e. the axis will show up if there's data associated
with it. You can override this by setting the "show" option to true or
false.

The "position" option specifies where the axis is placed, bottom or
top for x axes, left or right for y axes. The "mode" option determines
how the data is interpreted, the default of null means as decimal
numbers. Use "time" for time series data; see the time series data
section. The time plugin (jquery.flot.time.js) is required for time
series support.

The "color" option determines the color of the line and ticks for the axis, and
defaults to the grid color with transparency. For more fine-grained control you
can also set the color of the ticks separately with "tickColor".

You can customize the font and color used to draw the axis tick labels with CSS
or directly via the "font" option. When "font" is null - the default - each
tick label is given the 'flot-tick-label' class. For compatibility with Flot
0.7 and earlier the labels are also given the 'tickLabel' class, but this is
deprecated and scheduled to be removed with the release of version 1.0.0.

To enable more granular control over styles, labels are divided between a set
of text containers, with each holding the labels for one axis. These containers
are given the classes 'flot-[x|y]-axis', and 'flot-[x|y]#-axis', where '#' is
the number of the axis when there are multiple axes.  For example, the x-axis
labels for a simple plot with only a single x-axis might look like this:

```html
<div class='flot-x-axis flot-x1-axis'>
    <div class='flot-tick-label'>January 2013</div>
    ...
</div>
```

For direct control over label styles you can also provide "font" as an object
with this format:

```js
{
    size: 11,
    lineHeight: 13,
    style: "italic",
    weight: "bold",
    family: "sans-serif",
    variant: "small-caps",
    color: "#545454"
}
```

The size and lineHeight must be expressed in pixels; CSS units such as 'em'
or 'smaller' are not allowed.

The options "min"/"max" are the precise minimum/maximum value on the
scale. If you don't specify either of them, a value will automatically
be chosen based on the minimum/maximum data values. Note that Flot
always examines all the data values you feed to it, even if a
restriction on another axis may make some of them invisible (this
makes interactive use more stable).

The "autoscaleMargin" is a bit esoteric: it's the fraction of margin
that the scaling algorithm will add to avoid that the outermost points
ends up on the grid border. Note that this margin is only applied when
a min or max value is not explicitly set. If a margin is specified,
the plot will furthermore extend the axis end-point to the nearest
whole tick. The default value is "null" for the x axes and 0.02 for y
axes which seems appropriate for most cases.

"transform" and "inverseTransform" are callbacks you can put in to
change the way the data is drawn. You can design a function to
compress or expand certain parts of the axis non-linearly, e.g.
suppress weekends or compress far away points with a logarithm or some
other means. When Flot draws the plot, each value is first put through
the transform function. Here's an example, the x axis can be turned
into a natural logarithm axis with the following code:

```js
xaxis: {
    transform: function (v) { return Math.log(v); },
    inverseTransform: function (v) { return Math.exp(v); }
}
```

Similarly, for reversing the y axis so the values appear in inverse
order:

```js
yaxis: {
    transform: function (v) { return -v; },
    inverseTransform: function (v) { return -v; }
}
```

Note that for finding extrema, Flot assumes that the transform
function does not reorder values (it should be monotone).

The inverseTransform is simply the inverse of the transform function
(so v == inverseTransform(transform(v)) for all relevant v). It is
required for converting from canvas coordinates to data coordinates,
e.g. for a mouse interaction where a certain pixel is clicked. If you
don't use any interactive features of Flot, you may not need it.


The rest of the options deal with the ticks.

If you don't specify any ticks, a tick generator algorithm will make
some for you. The algorithm has two passes. It first estimates how
many ticks would be reasonable and uses this number to compute a nice
round tick interval size. Then it generates the ticks.

You can specify how many ticks the algorithm aims for by setting
"ticks" to a number. The algorithm always tries to generate reasonably
round tick values so even if you ask for three ticks, you might get
five if that fits better with the rounding. If you don't want any
ticks at all, set "ticks" to 0 or an empty array.

Another option is to skip the rounding part and directly set the tick
interval size with "tickSize". If you set it to 2, you'll get ticks at
2, 4, 6, etc. Alternatively, you can specify that you just don't want
ticks at a size less than a specific tick size with "minTickSize".
Note that for time series, the format is an array like [2, "month"],
see the next section.

If you want to completely override the tick algorithm, you can specify
an array for "ticks", either like this:

```js
ticks: [0, 1.2, 2.4]
```

Or like this where the labels are also customized:

```js
ticks: [[0, "zero"], [1.2, "one mark"], [2.4, "two marks"]]
```

You can mix the two if you like.
  
For extra flexibility you can specify a function as the "ticks"
parameter. The function will be called with an object with the axis
min and max and should return a ticks array. Here's a simplistic tick
generator that spits out intervals of pi, suitable for use on the x
axis for trigonometric functions:

```js
function piTickGenerator(axis) {
    var res = [], i = Math.floor(axis.min / Math.PI);
    do {
        var v = i * Math.PI;
        res.push([v, i + "\u03c0"]);
        ++i;
    } while (v < axis.max);
    return res;
}
```

You can control how the ticks look like with "tickDecimals", the
number of decimals to display (default is auto-detected).

Alternatively, for ultimate control over how ticks are formatted you can
provide a function to "tickFormatter". The function is passed two
parameters, the tick value and an axis object with information, and
should return a string. The default formatter looks like this:

```js
function formatter(val, axis) {
    return val.toFixed(axis.tickDecimals);
}
```

The axis object has "min" and "max" with the range of the axis,
"tickDecimals" with the number of decimals to round the value to and
"tickSize" with the size of the interval between ticks as calculated
by the automatic axis scaling algorithm (or specified by you). Here's
an example of a custom formatter:

```js
function suffixFormatter(val, axis) {
    if (val > 1000000)
        return (val / 1000000).toFixed(axis.tickDecimals) + " MB";
    else if (val > 1000)
        return (val / 1000).toFixed(axis.tickDecimals) + " kB";
    else
        return val.toFixed(axis.tickDecimals) + " B";
}
```

"labelWidth" and "labelHeight" specifies a fixed size of the tick
labels in pixels. They're useful in case you need to align several
plots. "reserveSpace" means that even if an axis isn't shown, Flot
should reserve space for it - it is useful in combination with
labelWidth and labelHeight for aligning multi-axis charts.

"tickLength" is the length of the tick lines in pixels. By default, the
innermost axes will have ticks that extend all across the plot, while
any extra axes use small ticks. A value of null means use the default,
while a number means small ticks of that length - set it to 0 to hide
the lines completely.

If you set "alignTicksWithAxis" to the number of another axis, e.g.
alignTicksWithAxis: 1, Flot will ensure that the autogenerated ticks
of this axis are aligned with the ticks of the other axis. This may
improve the looks, e.g. if you have one y axis to the left and one to
the right, because the grid lines will then match the ticks in both
ends. The trade-off is that the forced ticks won't necessarily be at
natural places.


## Multiple axes ##

If you need more than one x axis or y axis, you need to specify for
each data series which axis they are to use, as described under the
format of the data series, e.g. { data: [...], yaxis: 2 } specifies
that a series should be plotted against the second y axis.

To actually configure that axis, you can't use the xaxis/yaxis options
directly - instead there are two arrays in the options:

```js
xaxes: []
yaxes: []
```

Here's an example of configuring a single x axis and two y axes (we
can leave options of the first y axis empty as the defaults are fine):

```js
{
    xaxes: [ { position: "top" } ],
    yaxes: [ { }, { position: "right", min: 20 } ]
}
```

The arrays get their default values from the xaxis/yaxis settings, so
say you want to have all y axes start at zero, you can simply specify
yaxis: { min: 0 } instead of adding a min parameter to all the axes.

Generally, the various interfaces in Flot dealing with data points
either accept an xaxis/yaxis parameter to specify which axis number to
use (starting from 1), or lets you specify the coordinate directly as
x2/x3/... or x2axis/x3axis/... instead of "x" or "xaxis".


## Time series data ##

Please note that it is now required to include the time plugin,
jquery.flot.time.js, for time series support.

Time series are a bit more difficult than scalar data because
calendars don't follow a simple base 10 system. For many cases, Flot
abstracts most of this away, but it can still be a bit difficult to
get the data into Flot. So we'll first discuss the data format.

The time series support in Flot is based on Javascript timestamps,
i.e. everywhere a time value is expected or handed over, a Javascript
timestamp number is used. This is a number, not a Date object. A
Javascript timestamp is the number of milliseconds since January 1,
1970 00:00:00 UTC. This is almost the same as Unix timestamps, except it's
in milliseconds, so remember to multiply by 1000!

You can see a timestamp like this

```js
alert((new Date()).getTime())
```

There are different schools of thought when it comes to display of
timestamps. Many will want the timestamps to be displayed according to
a certain time zone, usually the time zone in which the data has been
produced. Some want the localized experience, where the timestamps are
displayed according to the local time of the visitor. Flot supports
both. Optionally you can include a third-party library to get
additional timezone support.

Default behavior is that Flot always displays timestamps according to
UTC. The reason being that the core Javascript Date object does not
support other fixed time zones. Often your data is at another time
zone, so it may take a little bit of tweaking to work around this
limitation.

The easiest way to think about it is to pretend that the data
production time zone is UTC, even if it isn't. So if you have a
datapoint at 2002-02-20 08:00, you can generate a timestamp for eight
o'clock UTC even if it really happened eight o'clock UTC+0200.

In PHP you can get an appropriate timestamp with:

```php
strtotime("2002-02-20 UTC") * 1000
```

In Python you can get it with something like:

```python
calendar.timegm(datetime_object.timetuple()) * 1000
```
In Ruby you can get it using the `#to_i` method on the
[`Time`](http://apidock.com/ruby/Time/to_i) object. If you're using the
`active_support` gem (default for Ruby on Rails applications) `#to_i` is also
available on the `DateTime` and `ActiveSupport::TimeWithZone` objects. You
simply need to multiply the result by 1000:

```ruby
Time.now.to_i * 1000     # => 1383582043000
# ActiveSupport examples:
DateTime.now.to_i * 1000 # => 1383582043000
ActiveSupport::TimeZone.new('Asia/Shanghai').now.to_i * 1000
# => 1383582043000
```

In .NET you can get it with something like:

```aspx
public static int GetJavascriptTimestamp(System.DateTime input)
{
    System.TimeSpan span = new System.TimeSpan(System.DateTime.Parse("1/1/1970").Ticks);
    System.DateTime time = input.Subtract(span);
    return (long)(time.Ticks / 10000);
}
```

Javascript also has some support for parsing date strings, so it is
possible to generate the timestamps manually client-side.

If you've already got the real UTC timestamp, it's too late to use the
pretend trick described above. But you can fix up the timestamps by
adding the time zone offset, e.g. for UTC+0200 you would add 2 hours
to the UTC timestamp you got. Then it'll look right on the plot. Most
programming environments have some means of getting the timezone
offset for a specific date (note that you need to get the offset for
each individual timestamp to account for daylight savings).

The alternative with core Javascript is to interpret the timestamps
according to the time zone that the visitor is in, which means that
the ticks will shift with the time zone and daylight savings of each
visitor. This behavior is enabled by setting the axis option
"timezone" to the value "browser".

If you need more time zone functionality than this, there is still
another option. If you include the "timezone-js" library
<https://github.com/mde/timezone-js> in the page and set axis.timezone
to a value recognized by said library, Flot will use timezone-js to
interpret the timestamps according to that time zone.

Once you've gotten the timestamps into the data and specified "time"
as the axis mode, Flot will automatically generate relevant ticks and
format them. As always, you can tweak the ticks via the "ticks" option
- just remember that the values should be timestamps (numbers), not
Date objects.

Tick generation and formatting can also be controlled separately
through the following axis options:

```js
minTickSize: array
timeformat: null or format string
monthNames: null or array of size 12 of strings
dayNames: null or array of size 7 of strings
twelveHourClock: boolean
```

Here "timeformat" is a format string to use. You might use it like
this:

```js
xaxis: {
    mode: "time",
    timeformat: "%Y/%m/%d"
}
```

This will result in tick labels like "2000/12/24". A subset of the
standard strftime specifiers are supported (plus the nonstandard %q):

```js
%a: weekday name (customizable)
%b: month name (customizable)
%d: day of month, zero-padded (01-31)
%e: day of month, space-padded ( 1-31)
%H: hours, 24-hour time, zero-padded (00-23)
%I: hours, 12-hour time, zero-padded (01-12)
%m: month, zero-padded (01-12)
%M: minutes, zero-padded (00-59)
%q: quarter (1-4)
%S: seconds, zero-padded (00-59)
%y: year (two digits)
%Y: year (four digits)
%p: am/pm
%P: AM/PM (uppercase version of %p)
%w: weekday as number (0-6, 0 being Sunday)
```

Flot 0.8 switched from %h to the standard %H hours specifier. The %h specifier
is still available, for backwards-compatibility, but is deprecated and
scheduled to be removed permanently with the release of version 1.0.

You can customize the month names with the "monthNames" option. For
instance, for Danish you might specify:

```js
monthNames: ["jan", "feb", "mar", "apr", "maj", "jun", "jul", "aug", "sep", "okt", "nov", "dec"]
```

Similarly you can customize the weekday names with the "dayNames"
option. An example in French:

```js
dayNames: ["dim", "lun", "mar", "mer", "jeu", "ven", "sam"]
```

If you set "twelveHourClock" to true, the autogenerated timestamps
will use 12 hour AM/PM timestamps instead of 24 hour. This only
applies if you have not set "timeformat". Use the "%I" and "%p" or
"%P" options if you want to build your own format string with 12-hour
times.

If the Date object has a strftime property (and it is a function), it
will be used instead of the built-in formatter. Thus you can include
a strftime library such as http://hacks.bluesmoon.info/strftime/ for
more powerful date/time formatting.

If everything else fails, you can control the formatting by specifying
a custom tick formatter function as usual. Here's a simple example
which will format December 24 as 24/12:

```js
tickFormatter: function (val, axis) {
    var d = new Date(val);
    return d.getUTCDate() + "/" + (d.getUTCMonth() + 1);
}
```

Note that for the time mode "tickSize" and "minTickSize" are a bit
special in that they are arrays on the form "[value, unit]" where unit
is one of "second", "minute", "hour", "day", "month" and "year". So
you can specify

```js
minTickSize: [1, "month"]
```

to get a tick interval size of at least 1 month and correspondingly,
if axis.tickSize is [2, "day"] in the tick formatter, the ticks have
been produced with two days in-between.


## Customizing the data series ##

```js
series: {
    lines, points, bars: {
        show: boolean
        lineWidth: number
        fill: boolean or number
        fillColor: null or color/gradient
    }

    lines, bars: {
        zero: boolean
    }

    points: {
        radius: number
        symbol: "circle" or function
    }

    bars: {
        barWidth: number
        align: "left", "right" or "center"
        horizontal: boolean
    }

    lines: {
        steps: boolean
    }

    shadowSize: number
    highlightColor: color or number
}

colors: [ color1, color2, ... ]
```

The options inside "series: {}" are copied to each of the series. So
you can specify that all series should have bars by putting it in the
global options, or override it for individual series by specifying
bars in a particular the series object in the array of data.
  
The most important options are "lines", "points" and "bars" that
specify whether and how lines, points and bars should be shown for
each data series. In case you don't specify anything at all, Flot will
default to showing lines (you can turn this off with
lines: { show: false }). You can specify the various types
independently of each other, and Flot will happily draw each of them
in turn (this is probably only useful for lines and points), e.g.

```js
var options = {
    series: {
        lines: { show: true, fill: true, fillColor: "rgba(255, 255, 255, 0.8)" },
        points: { show: true, fill: false }
    }
};
```

"lineWidth" is the thickness of the line or outline in pixels. You can
set it to 0 to prevent a line or outline from being drawn; this will
also hide the shadow.

"fill" is whether the shape should be filled. For lines, this produces
area graphs. You can use "fillColor" to specify the color of the fill.
If "fillColor" evaluates to false (default for everything except
points which are filled with white), the fill color is auto-set to the
color of the data series. You can adjust the opacity of the fill by
setting fill to a number between 0 (fully transparent) and 1 (fully
opaque).

For bars, fillColor can be a gradient, see the gradient documentation
below. "barWidth" is the width of the bars in units of the x axis (or
the y axis if "horizontal" is true), contrary to most other measures
that are specified in pixels. For instance, for time series the unit
is milliseconds so 24 * 60 * 60 * 1000 produces bars with the width of
a day. "align" specifies whether a bar should be left-aligned
(default), right-aligned or centered on top of the value it represents. 
When "horizontal" is on, the bars are drawn horizontally, i.e. from the 
y axis instead of the x axis; note that the bar end points are still
defined in the same way so you'll probably want to swap the
coordinates if you've been plotting vertical bars first.

Area and bar charts normally start from zero, regardless of the data's range.
This is because they convey information through size, and starting from a
different value would distort their meaning. In cases where the fill is purely
for decorative purposes, however, "zero" allows you to override this behavior.
It defaults to true for filled lines and bars; setting it to false tells the
series to use the same automatic scaling as an un-filled line.

For lines, "steps" specifies whether two adjacent data points are
connected with a straight (possibly diagonal) line or with first a
horizontal and then a vertical line. Note that this transforms the
data by adding extra points.

For points, you can specify the radius and the symbol. The only
built-in symbol type is circles, for other types you can use a plugin
or define them yourself by specifying a callback:

```js
function cross(ctx, x, y, radius, shadow) {
    var size = radius * Math.sqrt(Math.PI) / 2;
    ctx.moveTo(x - size, y - size);
    ctx.lineTo(x + size, y + size);
    ctx.moveTo(x - size, y + size);
    ctx.lineTo(x + size, y - size);
}
```

The parameters are the drawing context, x and y coordinates of the
center of the point, a radius which corresponds to what the circle
would have used and whether the call is to draw a shadow (due to
limited canvas support, shadows are currently faked through extra
draws). It's good practice to ensure that the area covered by the
symbol is the same as for the circle with the given radius, this
ensures that all symbols have approximately the same visual weight.

"shadowSize" is the default size of shadows in pixels. Set it to 0 to
remove shadows.

"highlightColor" is the default color of the translucent overlay used
to highlight the series when the mouse hovers over it.

The "colors" array specifies a default color theme to get colors for
the data series from. You can specify as many colors as you like, like
this:

```js
colors: ["#d18b2c", "#dba255", "#919733"]
```

If there are more data series than colors, Flot will try to generate
extra colors by lightening and darkening colors in the theme.


## Customizing the grid ##

```js
grid: {
    show: boolean
    aboveData: boolean
    color: color
    backgroundColor: color/gradient or null
    margin: number or margin object
    labelMargin: number
    axisMargin: number
    markings: array of markings or (fn: axes -> array of markings)
    borderWidth: number or object with "top", "right", "bottom" and "left" properties with different widths
    borderColor: color or null or object with "top", "right", "bottom" and "left" properties with different colors
    minBorderMargin: number or null
    clickable: boolean
    hoverable: boolean
    autoHighlight: boolean
    mouseActiveRadius: number
}

interaction: {
    redrawOverlayInterval: number or -1
}
```

The grid is the thing with the axes and a number of ticks. Many of the
things in the grid are configured under the individual axes, but not
all. "color" is the color of the grid itself whereas "backgroundColor"
specifies the background color inside the grid area, here null means
that the background is transparent. You can also set a gradient, see
the gradient documentation below.

You can turn off the whole grid including tick labels by setting
"show" to false. "aboveData" determines whether the grid is drawn
above the data or below (below is default).

"margin" is the space in pixels between the canvas edge and the grid,
which can be either a number or an object with individual margins for
each side, in the form:

```js
margin: {
    top: top margin in pixels
    left: left margin in pixels
    bottom: bottom margin in pixels
    right: right margin in pixels
}
```

"labelMargin" is the space in pixels between tick labels and axis
line, and "axisMargin" is the space in pixels between axes when there
are two next to each other.

"borderWidth" is the width of the border around the plot. Set it to 0
to disable the border. Set it to an object with "top", "right",
"bottom" and "left" properties to use different widths. You can
also set "borderColor" if you want the border to have a different color
than the grid lines. Set it to an object with "top", "right", "bottom"
and "left" properties to use different colors. "minBorderMargin" controls
the default minimum margin around the border - it's used to make sure
that points aren't accidentally clipped by the canvas edge so by default
the value is computed from the point radius.

"markings" is used to draw simple lines and rectangular areas in the
background of the plot. You can either specify an array of ranges on
the form { xaxis: { from, to }, yaxis: { from, to } } (with multiple
axes, you can specify coordinates for other axes instead, e.g. as
x2axis/x3axis/...) or with a function that returns such an array given
the axes for the plot in an object as the first parameter.

You can set the color of markings by specifying "color" in the ranges
object. Here's an example array:

```js
markings: [ { xaxis: { from: 0, to: 2 }, yaxis: { from: 10, to: 10 }, color: "#bb0000" }, ... ]
```

If you leave out one of the values, that value is assumed to go to the
border of the plot. So for example if you only specify { xaxis: {
from: 0, to: 2 } } it means an area that extends from the top to the
bottom of the plot in the x range 0-2.

A line is drawn if from and to are the same, e.g.

```js
markings: [ { yaxis: { from: 1, to: 1 } }, ... ]
```

would draw a line parallel to the x axis at y = 1. You can control the
line width with "lineWidth" in the range object.

An example function that makes vertical stripes might look like this:

```js
markings: function (axes) {
    var markings = [];
    for (var x = Math.floor(axes.xaxis.min); x < axes.xaxis.max; x += 2)
        markings.push({ xaxis: { from: x, to: x + 1 } });
    return markings;
}
```

If you set "clickable" to true, the plot will listen for click events
on the plot area and fire a "plotclick" event on the placeholder with
a position and a nearby data item object as parameters. The coordinates
are available both in the unit of the axes (not in pixels) and in
global screen coordinates.

Likewise, if you set "hoverable" to true, the plot will listen for
mouse move events on the plot area and fire a "plothover" event with
the same parameters as the "plotclick" event. If "autoHighlight" is
true (the default), nearby data items are highlighted automatically.
If needed, you can disable highlighting and control it yourself with
the highlight/unhighlight plot methods described elsewhere.

You can use "plotclick" and "plothover" events like this:

```js
$.plot($("#placeholder"), [ d ], { grid: { clickable: true } });

$("#placeholder").bind("plotclick", function (event, pos, item) {
    alert("You clicked at " + pos.x + ", " + pos.y);
    // axis coordinates for other axes, if present, are in pos.x2, pos.x3, ...
    // if you need global screen coordinates, they are pos.pageX, pos.pageY

    if (item) {
        highlight(item.series, item.datapoint);
        alert("You clicked a point!");
    }
});
```

The item object in this example is either null or a nearby object on the form:

```js
item: {
    datapoint: the point, e.g. [0, 2]
    dataIndex: the index of the point in the data array
    series: the series object
    seriesIndex: the index of the series
    pageX, pageY: the global screen coordinates of the point
}
```

For instance, if you have specified the data like this 

```js
$.plot($("#placeholder"), [ { label: "Foo", data: [[0, 10], [7, 3]] } ], ...);
```

and the mouse is near the point (7, 3), "datapoint" is [7, 3],
"dataIndex" will be 1, "series" is a normalized series object with
among other things the "Foo" label in series.label and the color in
series.color, and "seriesIndex" is 0. Note that plugins and options
that transform the data can shift the indexes from what you specified
in the original data array.

If you use the above events to update some other information and want
to clear out that info in case the mouse goes away, you'll probably
also need to listen to "mouseout" events on the placeholder div.

"mouseActiveRadius" specifies how far the mouse can be from an item
and still activate it. If there are two or more points within this
radius, Flot chooses the closest item. For bars, the top-most bar
(from the latest specified data series) is chosen.

If you want to disable interactivity for a specific data series, you
can set "hoverable" and "clickable" to false in the options for that
series, like this:

```js
{ data: [...], label: "Foo", clickable: false }
```

"redrawOverlayInterval" specifies the maximum time to delay a redraw
of interactive things (this works as a rate limiting device). The
default is capped to 60 frames per second. You can set it to -1 to
disable the rate limiting.


## Specifying gradients ##

A gradient is specified like this:

```js
{ colors: [ color1, color2, ... ] }
```

For instance, you might specify a background on the grid going from
black to gray like this:

```js
grid: {
    backgroundColor: { colors: ["#000", "#999"] }
}
```

For the series you can specify the gradient as an object that
specifies the scaling of the brightness and the opacity of the series
color, e.g.

```js
{ colors: [{ opacity: 0.8 }, { brightness: 0.6, opacity: 0.8 } ] }
```

where the first color simply has its alpha scaled, whereas the second
is also darkened. For instance, for bars the following makes the bars
gradually disappear, without outline:

```js
bars: {
    show: true,
    lineWidth: 0,
    fill: true,
    fillColor: { colors: [ { opacity: 0.8 }, { opacity: 0.1 } ] }
}
```

Flot currently only supports vertical gradients drawn from top to
bottom because that's what works with IE.


## Plot Methods ##

The Plot object returned from the plot function has some methods you
can call:

 - highlight(series, datapoint)

    Highlight a specific datapoint in the data series. You can either
    specify the actual objects, e.g. if you got them from a
    "plotclick" event, or you can specify the indices, e.g.
    highlight(1, 3) to highlight the fourth point in the second series
    (remember, zero-based indexing).

 - unhighlight(series, datapoint) or unhighlight()

    Remove the highlighting of the point, same parameters as
    highlight.

    If you call unhighlight with no parameters, e.g. as
    plot.unhighlight(), all current highlights are removed.

 - setData(data)

    You can use this to reset the data used. Note that axis scaling,
    ticks, legend etc. will not be recomputed (use setupGrid() to do
    that). You'll probably want to call draw() afterwards.

    You can use this function to speed up redrawing a small plot if
    you know that the axes won't change. Put in the new data with
    setData(newdata), call draw(), and you're good to go. Note that
    for large datasets, almost all the time is consumed in draw()
    plotting the data so in this case don't bother.

 - setupGrid()

    Recalculate and set axis scaling, ticks, legend etc.

    Note that because of the drawing model of the canvas, this
    function will immediately redraw (actually reinsert in the DOM)
    the labels and the legend, but not the actual tick lines because
    they're drawn on the canvas. You need to call draw() to get the
    canvas redrawn.

 - draw()

    Redraws the plot canvas.

 - triggerRedrawOverlay()

    Schedules an update of an overlay canvas used for drawing
    interactive things like a selection and point highlights. This
    is mostly useful for writing plugins. The redraw doesn't happen
    immediately, instead a timer is set to catch multiple successive
    redraws (e.g. from a mousemove). You can get to the overlay by
    setting up a drawOverlay hook.

 - width()/height()

    Gets the width and height of the plotting area inside the grid.
    This is smaller than the canvas or placeholder dimensions as some
    extra space is needed (e.g. for labels).

 - offset()

    Returns the offset of the plotting area inside the grid relative
    to the document, useful for instance for calculating mouse
    positions (event.pageX/Y minus this offset is the pixel position
    inside the plot).

 - pointOffset({ x: xpos, y: ypos })

    Returns the calculated offset of the data point at (x, y) in data
    space within the placeholder div. If you are working with multiple
    axes, you can specify the x and y axis references, e.g. 

    ```js
      o = pointOffset({ x: xpos, y: ypos, xaxis: 2, yaxis: 3 })
      // o.left and o.top now contains the offset within the div
    ````

 - resize()

    Tells Flot to resize the drawing canvas to the size of the
    placeholder. You need to run setupGrid() and draw() afterwards as
    canvas resizing is a destructive operation. This is used
    internally by the resize plugin.

 - shutdown()

    Cleans up any event handlers Flot has currently registered. This
    is used internally.

There are also some members that let you peek inside the internal
workings of Flot which is useful in some cases. Note that if you change
something in the objects returned, you're changing the objects used by
Flot to keep track of its state, so be careful.

  - getData()

    Returns an array of the data series currently used in normalized
    form with missing settings filled in according to the global
    options. So for instance to find out what color Flot has assigned
    to the data series, you could do this:

    ```js
    var series = plot.getData();
    for (var i = 0; i < series.length; ++i)
        alert(series[i].color);
    ```

    A notable other interesting field besides color is datapoints
    which has a field "points" with the normalized data points in a
    flat array (the field "pointsize" is the increment in the flat
    array to get to the next point so for a dataset consisting only of
    (x,y) pairs it would be 2).

  - getAxes()

    Gets an object with the axes. The axes are returned as the
    attributes of the object, so for instance getAxes().xaxis is the
    x axis.

    Various things are stuffed inside an axis object, e.g. you could
    use getAxes().xaxis.ticks to find out what the ticks are for the
    xaxis. Two other useful attributes are p2c and c2p, functions for
    transforming from data point space to the canvas plot space and
    back. Both returns values that are offset with the plot offset.
    Check the Flot source code for the complete set of attributes (or
    output an axis with console.log() and inspect it).

    With multiple axes, the extra axes are returned as x2axis, x3axis,
    etc., e.g. getAxes().y2axis is the second y axis. You can check
    y2axis.used to see whether the axis is associated with any data
    points and y2axis.show to see if it is currently shown. 
 
  - getPlaceholder()

    Returns placeholder that the plot was put into. This can be useful
    for plugins for adding DOM elements or firing events.

  - getCanvas()

    Returns the canvas used for drawing in case you need to hack on it
    yourself. You'll probably need to get the plot offset too.
  
  - getPlotOffset()

    Gets the offset that the grid has within the canvas as an object
    with distances from the canvas edges as "left", "right", "top",
    "bottom". I.e., if you draw a circle on the canvas with the center
    placed at (left, top), its center will be at the top-most, left
    corner of the grid.

  - getOptions()

    Gets the options for the plot, normalized, with default values
    filled in. You get a reference to actual values used by Flot, so
    if you modify the values in here, Flot will use the new values.
    If you change something, you probably have to call draw() or
    setupGrid() or triggerRedrawOverlay() to see the change.
    

## Hooks ##

In addition to the public methods, the Plot object also has some hooks
that can be used to modify the plotting process. You can install a
callback function at various points in the process, the function then
gets access to the internal data structures in Flot.

Here's an overview of the phases Flot goes through:

  1. Plugin initialization, parsing options
  
  2. Constructing the canvases used for drawing

  3. Set data: parsing data specification, calculating colors,
     copying raw data points into internal format,
     normalizing them, finding max/min for axis auto-scaling

  4. Grid setup: calculating axis spacing, ticks, inserting tick
     labels, the legend

  5. Draw: drawing the grid, drawing each of the series in turn

  6. Setting up event handling for interactive features

  7. Responding to events, if any

  8. Shutdown: this mostly happens in case a plot is overwritten 

Each hook is simply a function which is put in the appropriate array.
You can add them through the "hooks" option, and they are also available
after the plot is constructed as the "hooks" attribute on the returned
plot object, e.g.

```js
  // define a simple draw hook
  function hellohook(plot, canvascontext) { alert("hello!"); };

  // pass it in, in an array since we might want to specify several
  var plot = $.plot(placeholder, data, { hooks: { draw: [hellohook] } });

  // we can now find it again in plot.hooks.draw[0] unless a plugin
  // has added other hooks
```

The available hooks are described below. All hook callbacks get the
plot object as first parameter. You can find some examples of defined
hooks in the plugins bundled with Flot.

 - processOptions  [phase 1]

    ```function(plot, options)```
   
    Called after Flot has parsed and merged options. Useful in the
    instance where customizations beyond simple merging of default
    values is needed. A plugin might use it to detect that it has been
    enabled and then turn on or off other options.

 
 - processRawData  [phase 3]

    ```function(plot, series, data, datapoints)```
 
    Called before Flot copies and normalizes the raw data for the given
    series. If the function fills in datapoints.points with normalized
    points and sets datapoints.pointsize to the size of the points,
    Flot will skip the copying/normalization step for this series.
   
    In any case, you might be interested in setting datapoints.format,
    an array of objects for specifying how a point is normalized and
    how it interferes with axis scaling. It accepts the following options:

    ```js
    {
        x, y: boolean,
        number: boolean,
        required: boolean,
        defaultValue: value,
        autoscale: boolean
    }
    ```

    "x" and "y" specify whether the value is plotted against the x or y axis,
    and is currently used only to calculate axis min-max ranges. The default
    format array, for example, looks like this:

    ```js
    [
        { x: true, number: true, required: true },
        { y: true, number: true, required: true }
    ]
    ```

    This indicates that a point, i.e. [0, 25], consists of two values, with the
    first being plotted on the x axis and the second on the y axis.

    If "number" is true, then the value must be numeric, and is set to null if
    it cannot be converted to a number.

    "defaultValue" provides a fallback in case the original value is null. This
    is for instance handy for bars, where one can omit the third coordinate
    (the bottom of the bar), which then defaults to zero.

    If "required" is true, then the value must exist (be non-null) for the
    point as a whole to be valid. If no value is provided, then the entire
    point is cleared out with nulls, turning it into a gap in the series.

    "autoscale" determines whether the value is considered when calculating an
    automatic min-max range for the axes that the value is plotted against.

 - processDatapoints  [phase 3]

    ```function(plot, series, datapoints)```

    Called after normalization of the given series but before finding
    min/max of the data points. This hook is useful for implementing data
    transformations. "datapoints" contains the normalized data points in
    a flat array as datapoints.points with the size of a single point
    given in datapoints.pointsize. Here's a simple transform that
    multiplies all y coordinates by 2:

    ```js
    function multiply(plot, series, datapoints) {
        var points = datapoints.points, ps = datapoints.pointsize;
        for (var i = 0; i < points.length; i += ps)
            points[i + 1] *= 2;
    }
    ```

    Note that you must leave datapoints in a good condition as Flot
    doesn't check it or do any normalization on it afterwards.

 - processOffset  [phase 4]

    ```function(plot, offset)```

    Called after Flot has initialized the plot's offset, but before it
    draws any axes or plot elements. This hook is useful for customizing
    the margins between the grid and the edge of the canvas. "offset" is
    an object with attributes "top", "bottom", "left" and "right",
    corresponding to the margins on the four sides of the plot.

 - drawBackground [phase 5]

    ```function(plot, canvascontext)```

    Called before all other drawing operations. Used to draw backgrounds
    or other custom elements before the plot or axes have been drawn.

 - drawSeries  [phase 5]

    ```function(plot, canvascontext, series)```

    Hook for custom drawing of a single series. Called just before the
    standard drawing routine has been called in the loop that draws
    each series.

 - draw  [phase 5]

    ```function(plot, canvascontext)```

    Hook for drawing on the canvas. Called after the grid is drawn
    (unless it's disabled or grid.aboveData is set) and the series have
    been plotted (in case any points, lines or bars have been turned
    on). For examples of how to draw things, look at the source code.

 - bindEvents  [phase 6]

    ```function(plot, eventHolder)```

    Called after Flot has setup its event handlers. Should set any
    necessary event handlers on eventHolder, a jQuery object with the
    canvas, e.g.

    ```js
    function (plot, eventHolder) {
        eventHolder.mousedown(function (e) {
            alert("You pressed the mouse at " + e.pageX + " " + e.pageY);
        });
    }
    ```

    Interesting events include click, mousemove, mouseup/down. You can
    use all jQuery events. Usually, the event handlers will update the
    state by drawing something (add a drawOverlay hook and call
    triggerRedrawOverlay) or firing an externally visible event for
    user code. See the crosshair plugin for an example.
     
    Currently, eventHolder actually contains both the static canvas
    used for the plot itself and the overlay canvas used for
    interactive features because some versions of IE get the stacking
    order wrong. The hook only gets one event, though (either for the
    overlay or for the static canvas).

    Note that custom plot events generated by Flot are not generated on
    eventHolder, but on the div placeholder supplied as the first
    argument to the plot call. You can get that with
    plot.getPlaceholder() - that's probably also the one you should use
    if you need to fire a custom event.

 - drawOverlay  [phase 7]

    ```function (plot, canvascontext)```

    The drawOverlay hook is used for interactive things that need a
    canvas to draw on. The model currently used by Flot works the way
    that an extra overlay canvas is positioned on top of the static
    canvas. This overlay is cleared and then completely redrawn
    whenever something interesting happens. This hook is called when
    the overlay canvas is to be redrawn.

    "canvascontext" is the 2D context of the overlay canvas. You can
    use this to draw things. You'll most likely need some of the
    metrics computed by Flot, e.g. plot.width()/plot.height(). See the
    crosshair plugin for an example.

 - shutdown  [phase 8]

    ```function (plot, eventHolder)```

    Run when plot.shutdown() is called, which usually only happens in
    case a plot is overwritten by a new plot. If you're writing a
    plugin that adds extra DOM elements or event handlers, you should
    add a callback to clean up after you. Take a look at the section in
    the [PLUGINS](PLUGINS.md) document for more info.

   
## Plugins ##

Plugins extend the functionality of Flot. To use a plugin, simply
include its Javascript file after Flot in the HTML page.

If you're worried about download size/latency, you can concatenate all
the plugins you use, and Flot itself for that matter, into one big file
(make sure you get the order right), then optionally run it through a
Javascript minifier such as YUI Compressor.

Here's a brief explanation of how the plugin plumbings work:

Each plugin registers itself in the global array $.plot.plugins. When
you make a new plot object with $.plot, Flot goes through this array
calling the "init" function of each plugin and merging default options
from the "option" attribute of the plugin. The init function gets a
reference to the plot object created and uses this to register hooks
and add new public methods if needed.

See the [PLUGINS](PLUGINS.md) document for details on how to write a plugin. As the
above description hints, it's actually pretty easy.


## Version number ##

The version number of Flot is available in ```$.plot.version```.