forked from rfunduk/flot
-
Notifications
You must be signed in to change notification settings - Fork 0
/
API.txt
697 lines (525 loc) · 24.5 KB
/
API.txt
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
Flot Reference
--------------
Consider a call to the plot function:
var plot = $.plot(placeholder, data, options)
The placeholder is a jQuery object that the plot will be put into.
This placeholder needs to have its width and height set as explained
in the README. 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.
The format of the data is documented below, as is the available
options. The "plot" object returned has some members 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:
[ series1, series2, ... ]
A series can either be raw data or an object with properties. The raw
data format is an array of points*:
[ [x1, y1], [x2, y2], ... ]
E.g.
[ [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
accidentally retrieve data from the database and serialize them
directly to JSON without noticing the wrong type.
If a null is specified as a point or if one of the coordinates is null
or NaN or couldn't be converted to a number, the point is ignored. As
a special case, a null value for lines is interpreted as a line
segment end, i.e. the two points before and after the null value are
not connected.
The format of a single series object is as follows:
{
color: color or number,
data: rawdata,
label: string,
lines: specific lines options,
bars: specific bars options,
points: specific points options,
hints: specific hints options,
shadowSize: 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:
{
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 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:
[ { label: "Foo", data: [ [10, 1], [17, -14], [30, 5] ] },
{ label: "Bar", data: [ [11, 13], [19, 11], [30, -7] ] } ]
*: If the data series has 'deltas' enabled then you must not only
specify the x and y points of the data but also the delta to be used
for this data point, eg. [x,y,d] rather than [x,y] (see section
below on delta series'.
Plot Options
------------
All options are completely optional. They are documented individually
below, to change them you just specify them in an object, e.g.
var options = {
lines: { show: true },
points: { show: true }
};
$.plot(placeholder, data, options);
Customizing the legend
======================
legend: {
show: boolean
labelFormatter: null or (fn: string -> string)
labelBoxBorderColor: color
noColumns: number
position: "ne" or "nw" or "se" or "sw"
margin: number of pixels
backgroundColor: null or color
backgroundOpacity: number in 0.0 - 1.0
container: null or jQuery object
}
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:
labelFormatter: function(label) {
return '<a href="' + label + '">' + label + '</a>';
}
"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. "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 to put the legend table into.
The "position" and "margin" etc. options will then be ignored.
Customizing the axes
====================
xaxis, yaxis: {
mode: null or "time"
min: null or number
max: null or number
autoscaleMargin: null or number
labelWidth: null or number
labelHeight: null or number
ticks: null or number or ticks array or (fn: range -> ticks array)
tickSize: number or array
minTickSize: number or array
tickFormatter: (fn: number, object -> string) or string
tickDecimals: null or number
}
The two axes have the same kind of options. 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 next section.
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.
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 axis and
0.02 for the y axis which seems appropriate for most cases.
"labelWidth" and "labelHeight" specifies the maximum size of the tick
labels in pixels. They're useful in case you need to align several
plots.
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 ticks,
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:
ticks: [0, 1.2, 2.4]
Or like this (you can mix the two if you like):
ticks: [[0, "zero"], [1.2, "one mark"], [2.4, "two marks"]]
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:
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 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:
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:
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";
}
Time series data
================
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. 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
alert((new Date()).getTime())
Normally you want the timestamps to be displayed according to a
certain time zone, usually the time zone in which the data has been
produced. However, Flot always displays timestamps according to UTC.
It has to as the only 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 unpredictably with the time
zone and daylight savings of each visitor.
So given that there's no good support for custom time zones in
Javascript, you'll have to take care of this server-side.
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. If
you've already got the real UTC timestamp, it's too late to pretend -
but you can fix it up by adding the time zone offset, e.g. for
UTC+0200 you would add 2 hours to the timestamp. Then it'll look right
on the plot.
In PHP you can get an appropriate timestamp with
'strtotime("2002-02-20 UTC") * 1000', in Python with
'calendar.timegm(datetime_object.timetuple()) * 1000', in .NET with
something like:
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 (int)(time.Ticks / 10000);
}
Javascript also has some support for parsing date strings, so it is
possible to generate the timestamps client-side if you need to.
Once you've got 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, not Date
objects.
Tick generation and formatting can also be controlled separately
through the following axis options:
xaxis, yaxis: {
minTickSize
timeformat: null or format string
monthNames: null or array of size 12 of strings
}
Here "timeformat" is a format string to use. You might use it like
this:
xaxis: {
mode: "time",
timeformat: "%y/%m/%d"
}
This will result in tick labels like "2000/12/24". The following
specifiers are supported
%h': hours
%H': hours (left-padded with a zero)
%M': minutes (left-padded with a zero)
%S': seconds (left-padded with a zero)
%d': day of month (1-31)
%m': month (1-12)
%y': year (four digits)
%b': month name (customizable)
You can customize the month names with the "monthNames" option. For
instance, for Danish you might specify:
monthName: ["jan", "feb", "mar", "apr", "maj", "jun", "jul", "aug", "sep", "okt", "nov", "dec"]
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:
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
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
===========================
lines, points, bars: {
show: boolean
lineWidth: number
fill: boolean or number
fillColor: color
}
points: {
radius: number
}
bars: {
barWidth: number
}
deltas: {
show: boolean
lineColor: color (defaults to #333333)
markerWidth: number
markerColor: color (defaults to lineColor)
}
hints: {
showColorBox: boolean
showSeriesLabel: boolean
labelFormatter: fn: or leave it alone to get the defalt
hintFormatter: fn: or leave it alone to get the defalt
backgroundColor: color or null (for auto-detect)
backgroundOpacity: number
}
colors: [ color1, color2, ... ]
shadowSize: number
The most important options are "lines", "points" and "bars" that
specifies whether and how lines, points and bars should be shown for
each data series. You can specify them independently of each other,
and Flot will happily draw each of them in turn, e.g.
var options = {
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.
"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), 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).
"barWidth" is the width of the bars in units of the x axis, 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.
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:
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.
"shadowSize" is the default size of shadows in pixels. Set it to 0 to
remove shadows.
"deltas" are a lot like enabling bars or showing a marker on the grid except
that it is a bit more dynamic (giving a somewhat 'boxplot' feel), each data
point can have a different 'base value' that the actual y-value will be
compared against. For example, perhaps you want to show the temperature each
day and delta the datapoint against the yearly average on that day (or
against another city, etc).
"hints" are essentially tooltips that get formatted according to the format
function assigned to either an individual series or to all hints. The function
should return a string. Here are the default formatters:
function defaultHintFormatter(x, y) {
return "<strong>x:</strong> " + x.toFixed(2) +
" <strong>y:</strong> " + y.toFixed(2);
}
function defaultLabelFormatter(label) {
return "<span style='font-size:1.2em;'>" + label + "</span>";
}
'defaultHintFormatter' is the formatter for the actual datapoint.
'defaultLabelFormatter' is the formatter for the series label. 'showColorBox'
is whether the color of the series will appear in the tooltip like it does
in the legend. 'showSeriesLabel' is whether the label of the series is inserted
into the hint at all.
Customizing the grid
====================
grid: {
color: color
backgroundColor: color or null
tickColor: color
labelMargin: number
coloredAreas: array of areas or (fn: plot area -> array of areas)
coloredAreasColor: color
borderWidth: number
clickable: boolean
}
The grid is the thing with the two axes and a number of ticks. "color"
is the color of the grid itself whereas "backgroundColor" specifies
the background color inside the grid area. The default value of null
means that the background is transparent. You should only need to set
backgroundColor if want the grid area to be a different color from the
page color. Otherwise you might as well just set the background color
of the page with CSS.
"tickColor" is the color of the ticks and "labelMargin" is the spacing
between tick labels and the grid. Note that you can style the tick
labels with CSS, e.g. to change the color. They have class "tickLabel".
"borderWidth" is the width of the border around the plot. Set it to 0
to disable the border.
"coloredAreas" is an array of areas that will be drawn on top of the
background. You can either specify an array of objects with { x1, y1,
x2, y2 } or a function that returns such an array given the plot area
as { xmin, xmax, ymin, ymax }. The default color of the areas are
"coloredAreasColor". You can override the color of individual areas by
specifying "color" in the area object.
Here's an example array:
coloredAreas: [ { x1: 0, y1: 10, x2: 2, y2: 15, 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 { x1: 0, x2: 2 } means an area that
extends from the top to the bottom of the plot in the x range 0-2.
An example function might look like this:
coloredAreas: function (plotarea) {
var areas = [];
for (var x = Math.floor(plotarea.xmin); x < plotarea.xmax; x += 2)
areas.push({ x1: x, x2: x + 1 });
return areas;
}
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
an object { x: number, y: number } as parameter when one occurs. You can
use it like this:
plot = $.plot($("#placeholder"), [ d ], { grid: { clickable: true } });
$("#placeholder").bind("plotclick", function (e, result) {
// result.selected.x and result.selected.y are the datapoint matched
// and the raw click locations are in result.raw.x/y
});
If you set 'hoverable' to true, the plot will fire a hover event more or
less continuously while your mouse travels. You can use it like this:
plot = $.plot($('#placeholder'), [d], { grid: { hoverable: true } } );
$('#placeholder').bind('plotmouseover', function(e, result) {
// result.selected contains the matched point and result.raw
// contains the raw mouse co-ordinates, like plotclick
} );
Both of these handlers can benefit from the new function 'highlightSelected'
which take a datapoint of the form { x: xval, y: yval } and draws 'fake'
points on the graph at that location. To do this you must specify some options
for how you want it displayed, eg:
options.grid.mouseOverHighlight = "black";
options.grid.mouseOverFill = "red";
// and then call
plot.highlightSelected( result.selected );
... will cause highlighted points (when hovering or clicking) to be drawn
with black borders and a red center. If you specify a mouseOverHighlight
but not mouseOverFill, the fill will default to white (just like regular
points on the graph). Note that this also means that you could pass
result.raw instead to draw a point 'in the middle of nowhere', or any other
coordinates:
plot.highlightSelected({ x: result.selected.x, y: result.selected.y + 1 });
Keep in mind one major limitation of the hovering system. It can be _very_
slow with lots of data. To curb this problem, upon the initial generation
of a graph the library will now sort the data, but only if hovering is enabled.
If your data is already sorted (and you're sure) then you can change this
behavior with options.sortData = false. Once the data is sorted we can do
some simple math to limit our traversal of the data series, making the hovering
calculations faster at the expense of 'loading time' (the sorting isn't too
large of a hit, it seems).
The matching area is currently set to 15px, this should be an acceptable
default. If you need to change it you can override this setting with
options.grid.mouseCatchingArea = pixels.
If you need to mark some specific value on the x- or y-axis, you can define
markers that will be drawn on the grid.
markers: [
{ value: x-or-y-position,
width: thickness-of-marker,
color: color,
axis: 'x' (horizontal) or 'y' (vertical) },
...
]
You can list as many markers as you like, they're drawn on top of the grid
but under (before) any data series.
Customizing the selection
=========================
selection: {
mode: null or "x" or "y" or "xy",
color: color
}
You enable selection support by setting the mode to one of "x", "y" or
"xy". In "x" mode, the user will only be able to specify the x range,
similarly for "y" mode. For "xy", the selection becomes a rectangle
where both ranges can be specified. "color" is color of the selection.
When selection support is enabled, a "selected" event will be emitted
on the DOM element you passed into the plot function. The event
handler gets one extra parameter with the area selected, like this:
placeholder.bind("selected", function(event, area) {
// area selected is area.x1 to area.x2 and area.y1 to area.y2
});
Plot Members
------------
The Plot object returned from the plot function has the following
members:
- clearSelection()
Clear the selection rectangle.
- setSelection(area)
Set the selection rectangle. The passed in area should have the
members x1 and x2 if the selection mode is "x" and y1 and y2 if
the selection mode is "y" and both x1, x2 and y1, y2 if the
selection mode is "xy", like this:
setSelection({ x1: 0, x2: 10, y1: 40, y2: 60});
setSelection will trigger the "selected" event when called so you
may have to do a bit of shortcircuiting to prevent an eternal loop
if you invoke the method inside the "selected" handler.
- 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 the members "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.
- 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 plot if you now
that the axis won't change. Put in the new data with
setData(newdata) and call draw() afterwards, and you're good to
go.
- getData()
Returns the data currently used. The data series returned are
normalized with missing settings filled in. So for instance to
find out what color Flot has assigned to the data series, you
could do this:
var series = plot.getData();
for (var i = 0; i < series.length; ++i)
alert([i].color);
- 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 canvas.