|
|
1 |
Flot Reference |
|
|
2 |
-------------- |
|
|
3 |
|
|
|
4 |
Consider a call to the plot function: |
|
|
5 |
|
|
|
6 |
var plot = $.plot(placeholder, data, options) |
|
|
7 |
|
|
|
8 |
The placeholder is a jQuery object or DOM element or jQuery expression |
|
|
9 |
that the plot will be put into. This placeholder needs to have its |
|
|
10 |
width and height set as explained in the README (go read that now if |
|
|
11 |
you haven't, it's short). The plot will modify some properties of the |
|
|
12 |
placeholder so it's recommended you simply pass in a div that you |
|
|
13 |
don't use for anything else. Make sure you check any fancy styling |
|
|
14 |
you apply to the div, e.g. background images have been reported to be a |
|
|
15 |
problem on IE 7. |
|
|
16 |
|
|
|
17 |
The format of the data is documented below, as is the available |
|
|
18 |
options. The "plot" object returned has some methods you can call. |
|
|
19 |
These are documented separately below. |
|
|
20 |
|
|
|
21 |
Note that in general Flot gives no guarantees if you change any of the |
|
|
22 |
objects you pass in to the plot function or get out of it since |
|
|
23 |
they're not necessarily deep-copied. |
|
|
24 |
|
|
|
25 |
|
|
|
26 |
Data Format |
|
|
27 |
----------- |
|
|
28 |
|
|
|
29 |
The data is an array of data series: |
|
|
30 |
|
|
|
31 |
[ series1, series2, ... ] |
|
|
32 |
|
|
|
33 |
A series can either be raw data or an object with properties. The raw |
|
|
34 |
data format is an array of points: |
|
|
35 |
|
|
|
36 |
[ [x1, y1], [x2, y2], ... ] |
|
|
37 |
|
|
|
38 |
E.g. |
|
|
39 |
|
|
|
40 |
[ [1, 3], [2, 14.01], [3.5, 3.14] ] |
|
|
41 |
|
|
|
42 |
Note that to simplify the internal logic in Flot both the x and y |
|
|
43 |
values must be numbers (even if specifying time series, see below for |
|
|
44 |
how to do this). This is a common problem because you might retrieve |
|
|
45 |
data from the database and serialize them directly to JSON without |
|
|
46 |
noticing the wrong type. If you're getting mysterious errors, double |
|
|
47 |
check that you're inputting numbers and not strings. |
|
|
48 |
|
|
|
49 |
If a null is specified as a point or if one of the coordinates is null |
|
|
50 |
or couldn't be converted to a number, the point is ignored when |
|
|
51 |
drawing. As a special case, a null value for lines is interpreted as a |
|
|
52 |
line segment end, i.e. the points before and after the null value are |
|
|
53 |
not connected. |
|
|
54 |
|
|
|
55 |
Lines and points take two coordinates. For bars, you can specify a |
|
|
56 |
third coordinate which is the bottom of the bar (defaults to 0). |
|
|
57 |
|
|
|
58 |
The format of a single series object is as follows: |
|
|
59 |
|
|
|
60 |
{ |
|
|
61 |
color: color or number |
|
|
62 |
data: rawdata |
|
|
63 |
label: string |
|
|
64 |
lines: specific lines options |
|
|
65 |
bars: specific bars options |
|
|
66 |
points: specific points options |
|
|
67 |
xaxis: 1 or 2 |
|
|
68 |
yaxis: 1 or 2 |
|
|
69 |
clickable: boolean |
|
|
70 |
hoverable: boolean |
|
|
71 |
shadowSize: number |
|
|
72 |
} |
|
|
73 |
|
|
|
74 |
You don't have to specify any of them except the data, the rest are |
|
|
75 |
options that will get default values. Typically you'd only specify |
|
|
76 |
label and data, like this: |
|
|
77 |
|
|
|
78 |
{ |
|
|
79 |
label: "y = 3", |
|
|
80 |
data: [[0, 3], [10, 3]] |
|
|
81 |
} |
|
|
82 |
|
|
|
83 |
The label is used for the legend, if you don't specify one, the series |
|
|
84 |
will not show up in the legend. |
|
|
85 |
|
|
|
86 |
If you don't specify color, the series will get a color from the |
|
|
87 |
auto-generated colors. The color is either a CSS color specification |
|
|
88 |
(like "rgb(255, 100, 123)") or an integer that specifies which of |
|
|
89 |
auto-generated colors to select, e.g. 0 will get color no. 0, etc. |
|
|
90 |
|
|
|
91 |
The latter is mostly useful if you let the user add and remove series, |
|
|
92 |
in which case you can hard-code the color index to prevent the colors |
|
|
93 |
from jumping around between the series. |
|
|
94 |
|
|
|
95 |
The "xaxis" and "yaxis" options specify which axis to use, specify 2 |
|
|
96 |
to get the secondary axis (x axis at top or y axis to the right). |
|
|
97 |
E.g., you can use this to make a dual axis plot by specifying |
|
|
98 |
{ yaxis: 2 } for one data series. |
|
|
99 |
|
|
|
100 |
"clickable" and "hoverable" can be set to false to disable |
|
|
101 |
interactivity for specific series if interactivity is turned on in |
|
|
102 |
the plot, see below. |
|
|
103 |
|
|
|
104 |
The rest of the options are all documented below as they are the same |
|
|
105 |
as the default options passed in via the options parameter in the plot |
|
|
106 |
commmand. When you specify them for a specific data series, they will |
|
|
107 |
override the default options for the plot for that data series. |
|
|
108 |
|
|
|
109 |
Here's a complete example of a simple data specification: |
|
|
110 |
|
|
|
111 |
[ { label: "Foo", data: [ [10, 1], [17, -14], [30, 5] ] }, |
|
|
112 |
{ label: "Bar", data: [ [11, 13], [19, 11], [30, -7] ] } ] |
|
|
113 |
|
|
|
114 |
|
|
|
115 |
Plot Options |
|
|
116 |
------------ |
|
|
117 |
|
|
|
118 |
All options are completely optional. They are documented individually |
|
|
119 |
below, to change them you just specify them in an object, e.g. |
|
|
120 |
|
|
|
121 |
var options = { |
|
|
122 |
series: { |
|
|
123 |
lines: { show: true }, |
|
|
124 |
points: { show: true } |
|
|
125 |
} |
|
|
126 |
}; |
|
|
127 |
|
|
|
128 |
$.plot(placeholder, data, options); |
|
|
129 |
|
|
|
130 |
|
|
|
131 |
Customizing the legend |
|
|
132 |
====================== |
|
|
133 |
|
|
|
134 |
legend: { |
|
|
135 |
show: boolean |
|
|
136 |
labelFormatter: null or (fn: string, series object -> string) |
|
|
137 |
labelBoxBorderColor: color |
|
|
138 |
noColumns: number |
|
|
139 |
position: "ne" or "nw" or "se" or "sw" |
|
|
140 |
margin: number of pixels or [x margin, y margin] |
|
|
141 |
backgroundColor: null or color |
|
|
142 |
backgroundOpacity: number between 0 and 1 |
|
|
143 |
container: null or jQuery object/DOM element/jQuery expression |
|
|
144 |
} |
|
|
145 |
|
|
|
146 |
The legend is generated as a table with the data series labels and |
|
|
147 |
small label boxes with the color of the series. If you want to format |
|
|
148 |
the labels in some way, e.g. make them to links, you can pass in a |
|
|
149 |
function for "labelFormatter". Here's an example that makes them |
|
|
150 |
clickable: |
|
|
151 |
|
|
|
152 |
labelFormatter: function(label, series) { |
|
|
153 |
// series is the series object for the label |
|
|
154 |
return '<a href="#' + label + '">' + label + '</a>'; |
|
|
155 |
} |
|
|
156 |
|
|
|
157 |
"noColumns" is the number of columns to divide the legend table into. |
|
|
158 |
"position" specifies the overall placement of the legend within the |
|
|
159 |
plot (top-right, top-left, etc.) and margin the distance to the plot |
|
|
160 |
edge (this can be either a number or an array of two numbers like [x, |
|
|
161 |
y]). "backgroundColor" and "backgroundOpacity" specifies the |
|
|
162 |
background. The default is a partly transparent auto-detected |
|
|
163 |
background. |
|
|
164 |
|
|
|
165 |
If you want the legend to appear somewhere else in the DOM, you can |
|
|
166 |
specify "container" as a jQuery object/expression to put the legend |
|
|
167 |
table into. The "position" and "margin" etc. options will then be |
|
|
168 |
ignored. Note that Flot will overwrite the contents of the container. |
|
|
169 |
|
|
|
170 |
|
|
|
171 |
Customizing the axes |
|
|
172 |
==================== |
|
|
173 |
|
|
|
174 |
xaxis, yaxis, x2axis, y2axis: { |
|
|
175 |
mode: null or "time" |
|
|
176 |
min: null or number |
|
|
177 |
max: null or number |
|
|
178 |
autoscaleMargin: null or number |
|
|
179 |
|
|
|
180 |
labelWidth: null or number |
|
|
181 |
labelHeight: null or number |
|
|
182 |
|
|
|
183 |
transform: null or fn: number -> number |
|
|
184 |
inverseTransform: null or fn: number -> number |
|
|
185 |
|
|
|
186 |
ticks: null or number or ticks array or (fn: range -> ticks array) |
|
|
187 |
tickSize: number or array |
|
|
188 |
minTickSize: number or array |
|
|
189 |
tickFormatter: (fn: number, object -> string) or string |
|
|
190 |
tickDecimals: null or number |
|
|
191 |
} |
|
|
192 |
|
|
|
193 |
All axes have the same kind of options. The "mode" option |
|
|
194 |
determines how the data is interpreted, the default of null means as |
|
|
195 |
decimal numbers. Use "time" for time series data, see the next section. |
|
|
196 |
|
|
|
197 |
The options "min"/"max" are the precise minimum/maximum value on the |
|
|
198 |
scale. If you don't specify either of them, a value will automatically |
|
|
199 |
be chosen based on the minimum/maximum data values. |
|
|
200 |
|
|
|
201 |
The "autoscaleMargin" is a bit esoteric: it's the fraction of margin |
|
|
202 |
that the scaling algorithm will add to avoid that the outermost points |
|
|
203 |
ends up on the grid border. Note that this margin is only applied |
|
|
204 |
when a min or max value is not explicitly set. If a margin is |
|
|
205 |
specified, the plot will furthermore extend the axis end-point to the |
|
|
206 |
nearest whole tick. The default value is "null" for the x axis and |
|
|
207 |
0.02 for the y axis which seems appropriate for most cases. |
|
|
208 |
|
|
|
209 |
"labelWidth" and "labelHeight" specifies a fixed size of the tick |
|
|
210 |
labels in pixels. They're useful in case you need to align several |
|
|
211 |
plots. |
|
|
212 |
|
|
|
213 |
"transform" and "inverseTransform" are callbacks you can put in to |
|
|
214 |
change the way the data is drawn. You can design a function to |
|
|
215 |
compress or expand certain parts of the axis non-linearly, e.g. |
|
|
216 |
suppress weekends or compress far away points with a logarithm or some |
|
|
217 |
other means. When Flot draws the plot, each value is first put through |
|
|
218 |
the transform function. Here's an example, the x axis can be turned |
|
|
219 |
into a natural logarithm axis with the following code: |
|
|
220 |
|
|
|
221 |
xaxis: { |
|
|
222 |
transform: function (v) { return Math.log(v); }, |
|
|
223 |
inverseTransform: function (v) { return Math.exp(v); } |
|
|
224 |
} |
|
|
225 |
|
|
|
226 |
Note that for finding extrema, Flot assumes that the transform |
|
|
227 |
function does not reorder values (monotonicity is assumed). |
|
|
228 |
|
|
|
229 |
The inverseTransform is simply the inverse of the transform function |
|
|
230 |
(so v == inverseTransform(transform(v)) for all relevant v). It is |
|
|