Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 1396 lines (1077 sloc) 49.376 kB
cc974bd @dnschnur Additional cleanup and markup standardization.
dnschnur authored
1 # Flot Reference #
d2a5a63 First draft, options are not documented yet
olau@iola.dk authored
2
3 Consider a call to the plot function:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
4
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
5 ```js
6 var plot = $.plot(placeholder, data, options)
7 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
8
5785c2d Call $() on passed in elements to support DOM elements/CSS expression…
olau@iola.dk authored
9 The placeholder is a jQuery object or DOM element or jQuery expression
10 that the plot will be put into. This placeholder needs to have its
11 width and height set as explained in the README (go read that now if
12 you haven't, it's short). The plot will modify some properties of the
13 placeholder so it's recommended you simply pass in a div that you
bab1366 Added notice about broken background images on IE 7 based on report f…
olau@iola.dk authored
14 don't use for anything else. Make sure you check any fancy styling
15 you apply to the div, e.g. background images have been reported to be a
16 problem on IE 7.
d2a5a63 First draft, options are not documented yet
olau@iola.dk authored
17
18 The format of the data is documented below, as is the available
bad53ab Revamped internals to add support for extra axes, not just dual (spon…
olau@iola.dk authored
19 options. The plot object returned from the call has some methods you
20 can call. These are documented separately below.
d2a5a63 First draft, options are not documented yet
olau@iola.dk authored
21
f4ffef2 Added support for clicking on the plot, still a bit primitive
olau@iola.dk authored
22 Note that in general Flot gives no guarantees if you change any of the
7a665a1 Added support for line segments and null/NaN values
olau@iola.dk authored
23 objects you pass in to the plot function or get out of it since
24 they're not necessarily deep-copied.
d2a5a63 First draft, options are not documented yet
olau@iola.dk authored
25
26
cc974bd @dnschnur Additional cleanup and markup standardization.
dnschnur authored
27 ## Data Format ##
d2a5a63 First draft, options are not documented yet
olau@iola.dk authored
28
29 The data is an array of data series:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
30
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
31 ```js
32 [ series1, series2, ... ]
33 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
34
d2a5a63 First draft, options are not documented yet
olau@iola.dk authored
35 A series can either be raw data or an object with properties. The raw
36 data format is an array of points:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
37
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
38 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
39 [ [x1, y1], [x2, y2], ... ]
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
40 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
41
d2a5a63 First draft, options are not documented yet
olau@iola.dk authored
42 E.g.
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
43
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
44 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
45 [ [1, 3], [2, 14.01], [3.5, 3.14] ]
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
46 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
47
dfba9f3 Documented the date support, tweaking the API a bit in the process, d…
olau@iola.dk authored
48 Note that to simplify the internal logic in Flot both the x and y
0d15280 Implemented plugin system, introduced experimental hooks system (thre…
olau@iola.dk authored
49 values must be numbers (even if specifying time series, see below for
f8594bd Allow null values in coordinates to have an affect on axis scaling
olau@iola.dk authored
50 how to do this). This is a common problem because you might retrieve
51 data from the database and serialize them directly to JSON without
f4de938 Clarify that it is important not to put in strings
olau@iola.dk authored
52 noticing the wrong type. If you're getting mysterious errors, double
53 check that you're inputting numbers and not strings.
7a665a1 Added support for line segments and null/NaN values
olau@iola.dk authored
54
55 If a null is specified as a point or if one of the coordinates is null
f8594bd Allow null values in coordinates to have an affect on axis scaling
olau@iola.dk authored
56 or couldn't be converted to a number, the point is ignored when
57 drawing. As a special case, a null value for lines is interpreted as a
0d15280 Implemented plugin system, introduced experimental hooks system (thre…
olau@iola.dk authored
58 line segment end, i.e. the points before and after the null value are
cba1486 Convert data coordinates explicitly to numbers
olau@iola.dk authored
59 not connected.
dfba9f3 Documented the date support, tweaking the API a bit in the process, d…
olau@iola.dk authored
60
c3a34cd Support for specifying a bottom for each point for line charts when
olau@iola.dk authored
61 Lines and points take two coordinates. For filled lines and bars, you
62 can specify a third coordinate which is the bottom of the filled
63 area/bar (defaults to 0).
60689d2 Support for partial bars, this is useful for stacked bars
olau@iola.dk authored
64
d2a5a63 First draft, options are not documented yet
olau@iola.dk authored
65 The format of a single series object is as follows:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
66
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
67 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
68 {
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
69 color: color or number
70 data: rawdata
71 label: string
72 lines: specific lines options
73 bars: specific bars options
74 points: specific points options
75 xaxis: number
76 yaxis: number
77 clickable: boolean
78 hoverable: boolean
79 shadowSize: number
070fd83 @dnschnur Added docs for the highlightColor option.
dnschnur authored
80 highlightColor: color or number
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
81 }
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
82 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
83
d2a5a63 First draft, options are not documented yet
olau@iola.dk authored
84 You don't have to specify any of them except the data, the rest are
85 options that will get default values. Typically you'd only specify
86 label and data, like this:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
87
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
88 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
89 {
90 label: "y = 3",
91 data: [[0, 3], [10, 3]]
92 }
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
93 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
94
d2a5a63 First draft, options are not documented yet
olau@iola.dk authored
95 The label is used for the legend, if you don't specify one, the series
96 will not show up in the legend.
97
98 If you don't specify color, the series will get a color from the
99 auto-generated colors. The color is either a CSS color specification
100 (like "rgb(255, 100, 123)") or an integer that specifies which of
101 auto-generated colors to select, e.g. 0 will get color no. 0, etc.
102
103 The latter is mostly useful if you let the user add and remove series,
104 in which case you can hard-code the color index to prevent the colors
105 from jumping around between the series.
106
bad53ab Revamped internals to add support for extra axes, not just dual (spon…
olau@iola.dk authored
107 The "xaxis" and "yaxis" options specify which axis to use. The axes
108 are numbered from 1 (default), so { yaxis: 2} means that the series
109 should be plotted against the second y axis.
7c9ff67 Landed dual axis/hover event/finding nearby datapoints patch
olau@iola.dk authored
110
5587862 Added support for disabling interactivity for specific plots
olau@iola.dk authored
111 "clickable" and "hoverable" can be set to false to disable
112 interactivity for specific series if interactivity is turned on in
0d15280 Implemented plugin system, introduced experimental hooks system (thre…
olau@iola.dk authored
113 the plot, see below.
5587862 Added support for disabling interactivity for specific plots
olau@iola.dk authored
114
d2a5a63 First draft, options are not documented yet
olau@iola.dk authored
115 The rest of the options are all documented below as they are the same
116 as the default options passed in via the options parameter in the plot
117 commmand. When you specify them for a specific data series, they will
118 override the default options for the plot for that data series.
119
dfba9f3 Documented the date support, tweaking the API a bit in the process, d…
olau@iola.dk authored
120 Here's a complete example of a simple data specification:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
121
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
122 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
123 [ { label: "Foo", data: [ [10, 1], [17, -14], [30, 5] ] },
124 { label: "Bar", data: [ [11, 13], [19, 11], [30, -7] ] }
125 ]
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
126 ```
d2a5a63 First draft, options are not documented yet
olau@iola.dk authored
127
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
128
cc974bd @dnschnur Additional cleanup and markup standardization.
dnschnur authored
129 ## Plot Options ##
d2a5a63 First draft, options are not documented yet
olau@iola.dk authored
130
19eb761 Documented more options
olau@iola.dk authored
131 All options are completely optional. They are documented individually
132 below, to change them you just specify them in an object, e.g.
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
133
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
134 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
135 var options = {
136 series: {
137 lines: { show: true },
138 points: { show: true }
139 }
140 };
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
141
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
142 $.plot(placeholder, data, options);
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
143 ```
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
144
145
cc974bd @dnschnur Additional cleanup and markup standardization.
dnschnur authored
146 ## Customizing the legend ##
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
147
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
148 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
149 legend: {
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
150 show: boolean
151 labelFormatter: null or (fn: string, series object -> string)
152 labelBoxBorderColor: color
153 noColumns: number
154 position: "ne" or "nw" or "se" or "sw"
155 margin: number of pixels or [x margin, y margin]
156 backgroundColor: null or color
157 backgroundOpacity: number between 0 and 1
158 container: null or jQuery object/DOM element/jQuery expression
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
159 sorted: null/false, true, "ascending", "descending" or a comparator
160 }
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
161 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
162
19eb761 Documented more options
olau@iola.dk authored
163 The legend is generated as a table with the data series labels and
c81f0af Added labelFormatter option
olau@iola.dk authored
164 small label boxes with the color of the series. If you want to format
165 the labels in some way, e.g. make them to links, you can pass in a
166 function for "labelFormatter". Here's an example that makes them
167 clickable:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
168
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
169 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
170 labelFormatter: function(label, series) {
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
171 // series is the series object for the label
172 return '<a href="#' + label + '">' + label + '</a>';
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
173 }
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
174 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
175
c81f0af Added labelFormatter option
olau@iola.dk authored
176 "noColumns" is the number of columns to divide the legend table into.
177 "position" specifies the overall placement of the legend within the
178 plot (top-right, top-left, etc.) and margin the distance to the plot
ab264f6 legend.margin can now specify horizontal and vertical margins
olau@iola.dk authored
179 edge (this can be either a number or an array of two numbers like [x,
180 y]). "backgroundColor" and "backgroundOpacity" specifies the
c81f0af Added labelFormatter option
olau@iola.dk authored
181 background. The default is a partly transparent auto-detected
182 background.
183
184 If you want the legend to appear somewhere else in the DOM, you can
ab264f6 legend.margin can now specify horizontal and vertical margins
olau@iola.dk authored
185 specify "container" as a jQuery object/expression to put the legend
186 table into. The "position" and "margin" etc. options will then be
187 ignored. Note that Flot will overwrite the contents of the container.
19eb761 Documented more options
olau@iola.dk authored
188
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
189 Legend entries appear in the same order as their series by default. To
190 sort them alphabetically, you can specify "sorted" as tue, "ascending"
191 or "descending", where true and "ascending" are equivalent.
192
193 You can also provide your own comparator function that accepts two
194 objects with "label" and "color" properties, and returns zero if they
195 are equal, a positive value if the first is greater than the second,
196 and a negative value if the first is less than the second.
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
197
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
198 ```js
199 sorted: function(a, b) {
200 // sort alphabetically in ascending order
201 return a.label == b.label ? 0 : (
202 a.label > b.label ? 1 : -1
203 )
204 }
205 ```
206
19eb761 Documented more options
olau@iola.dk authored
207
cc974bd @dnschnur Additional cleanup and markup standardization.
dnschnur authored
208 ## Customizing the axes ##
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
209
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
210 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
211 xaxis, yaxis: {
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
212 show: null or true/false
213 position: "bottom" or "top" or "left" or "right"
214 mode: null or "time" ("time" requires jquery.flot.time.js plugin)
215 timezone: null, "browser" or timezone (only makes sense for mode: "time")
216
217 color: null or color spec
218 tickColor: null or color spec
219 font: null or font spec object
220
221 min: null or number
222 max: null or number
223 autoscaleMargin: null or number
224
225 transform: null or fn: number -> number
226 inverseTransform: null or fn: number -> number
227
228 ticks: null or number or ticks array or (fn: axis -> ticks array)
229 tickSize: number or array
230 minTickSize: number or array
231 tickFormatter: (fn: number, object -> string) or string
232 tickDecimals: null or number
233
234 labelWidth: null or number
235 labelHeight: null or number
236 reserveSpace: null or true
237
238 tickLength: null or number
19eb761 Documented more options
olau@iola.dk authored
239
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
240 alignTicksWithAxis: null or number
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
241 }
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
242 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
243
bad53ab Revamped internals to add support for extra axes, not just dual (spon…
olau@iola.dk authored
244 All axes have the same kind of options. The following describes how to
245 configure one axis, see below for what to do if you've got more than
246 one x axis or y axis.
247
9dcd530 Reformulate the paragraph about the axis show option slightly
olau@iola.dk authored
248 If you don't set the "show" option (i.e. it is null), visibility is
249 auto-detected, i.e. the axis will show up if there's data associated
250 with it. You can override this by setting the "show" option to true or
251 false.
47821c7 Refactor the axis dimension calculations slightly to avoid the whole
olau@iola.dk authored
252
bad53ab Revamped internals to add support for extra axes, not just dual (spon…
olau@iola.dk authored
253 The "position" option specifies where the axis is placed, bottom or
254 top for x axes, left or right for y axes. The "mode" option determines
255 how the data is interpreted, the default of null means as decimal
8542929 @markrcote Moved time-series functionality into a separate plug-in and incorporated
markrcote authored
256 numbers. Use "time" for time series data; see the time series data
257 section. The time plugin (jquery.flot.time.js) is required for time
258 series support.
dfba9f3 Documented the date support, tweaking the API a bit in the process, d…
olau@iola.dk authored
259
947c166 Support for coloring axes, and automatic tick color selection
olau@iola.dk authored
260 The "color" option determines the color of the labels and ticks for
261 the axis (default is the grid color). For more fine-grained control
262 you can also set the color of the ticks separately with "tickColor"
263 (otherwise it's autogenerated as the base color with some
264 transparency).
265
89bbfef @OleLaursen Switch to using canvas text to draw the axis labels, fix a problem wi…
OleLaursen authored
266 You can customize the font used to draw the labels with CSS or
267 directly with "font". The default value of null means that the font is
268 read from the font style on the placeholder element (80% the size of
269 that to be precise). If you set it directly with "font: { ... }", the
270 format is like this:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
271
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
272 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
273 {
274 size: 11,
275 style: "italic",
276 weight: "bold",
277 family: "sans-serif",
278 variant: "small-caps"
279 }
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
280 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
281
dfba9f3 Documented the date support, tweaking the API a bit in the process, d…
olau@iola.dk authored
282 The options "min"/"max" are the precise minimum/maximum value on the
283 scale. If you don't specify either of them, a value will automatically
d769a5b Add note about min/max calculations being based on entire dataset
olau@iola.dk authored
284 be chosen based on the minimum/maximum data values. Note that Flot
285 always examines all the data values you feed to it, even if a
286 restriction on another axis may make some of them invisible (this
287 makes interactive use more stable).
8cf4261 Cleaned up the scaling algorithm and some of the tick stuff
olau@iola.dk authored
288
289 The "autoscaleMargin" is a bit esoteric: it's the fraction of margin
290 that the scaling algorithm will add to avoid that the outermost points
947c166 Support for coloring axes, and automatic tick color selection
olau@iola.dk authored
291 ends up on the grid border. Note that this margin is only applied when
292 a min or max value is not explicitly set. If a margin is specified,
293 the plot will furthermore extend the axis end-point to the nearest
294 whole tick. The default value is "null" for the x axes and 0.02 for y
295 axes which seems appropriate for most cases.
19eb761 Documented more options
olau@iola.dk authored
296
e7a909a Added axis transformation support
olau@iola.dk authored
297 "transform" and "inverseTransform" are callbacks you can put in to
298 change the way the data is drawn. You can design a function to
299 compress or expand certain parts of the axis non-linearly, e.g.
300 suppress weekends or compress far away points with a logarithm or some
301 other means. When Flot draws the plot, each value is first put through
302 the transform function. Here's an example, the x axis can be turned
303 into a natural logarithm axis with the following code:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
304
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
305 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
306 xaxis: {
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
307 transform: function (v) { return Math.log(v); },
308 inverseTransform: function (v) { return Math.exp(v); }
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
309 }
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
310 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
311
26cf412 Add reverse axis example to API
olau@iola.dk authored
312 Similarly, for reversing the y axis so the values appear in inverse
313 order:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
314
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
315 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
316 yaxis: {
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
317 transform: function (v) { return -v; },
318 inverseTransform: function (v) { return -v; }
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
319 }
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
320 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
321
e7a909a Added axis transformation support
olau@iola.dk authored
322 Note that for finding extrema, Flot assumes that the transform
bad53ab Revamped internals to add support for extra axes, not just dual (spon…
olau@iola.dk authored
323 function does not reorder values (it should be monotone).
e7a909a Added axis transformation support
olau@iola.dk authored
324
325 The inverseTransform is simply the inverse of the transform function
326 (so v == inverseTransform(transform(v)) for all relevant v). It is
327 required for converting from canvas coordinates to data coordinates,
328 e.g. for a mouse interaction where a certain pixel is clicked. If you
329 don't use any interactive features of Flot, you may not need it.
330
331
dfba9f3 Documented the date support, tweaking the API a bit in the process, d…
olau@iola.dk authored
332 The rest of the options deal with the ticks.
333
334 If you don't specify any ticks, a tick generator algorithm will make
865688a Some further tweaks to time series handling, implemented support for …
olau@iola.dk authored
335 some for you. The algorithm has two passes. It first estimates how
336 many ticks would be reasonable and uses this number to compute a nice
337 round tick interval size. Then it generates the ticks.
8cf4261 Cleaned up the scaling algorithm and some of the tick stuff
olau@iola.dk authored
338
865688a Some further tweaks to time series handling, implemented support for …
olau@iola.dk authored
339 You can specify how many ticks the algorithm aims for by setting
340 "ticks" to a number. The algorithm always tries to generate reasonably
341 round tick values so even if you ask for three ticks, you might get
60689d2 Support for partial bars, this is useful for stacked bars
olau@iola.dk authored
342 five if that fits better with the rounding. If you don't want any
343 ticks at all, set "ticks" to 0 or an empty array.
19eb761 Documented more options
olau@iola.dk authored
344
865688a Some further tweaks to time series handling, implemented support for …
olau@iola.dk authored
345 Another option is to skip the rounding part and directly set the tick
346 interval size with "tickSize". If you set it to 2, you'll get ticks at
347 2, 4, 6, etc. Alternatively, you can specify that you just don't want
348 ticks at a size less than a specific tick size with "minTickSize".
349 Note that for time series, the format is an array like [2, "month"],
350 see the next section.
8cf4261 Cleaned up the scaling algorithm and some of the tick stuff
olau@iola.dk authored
351
865688a Some further tweaks to time series handling, implemented support for …
olau@iola.dk authored
352 If you want to completely override the tick algorithm, you can specify
353 an array for "ticks", either like this:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
354
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
355 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
356 ticks: [0, 1.2, 2.4]
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
357 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
358
a4c7fa3 Clarify how to set tick labels (issue 144)
olau@iola.dk authored
359 Or like this where the labels are also customized:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
360
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
361 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
362 ticks: [[0, "zero"], [1.2, "one mark"], [2.4, "two marks"]]
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
363 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
364
a4c7fa3 Clarify how to set tick labels (issue 144)
olau@iola.dk authored
365 You can mix the two if you like.
366
19eb761 Documented more options
olau@iola.dk authored
367 For extra flexibility you can specify a function as the "ticks"
368 parameter. The function will be called with an object with the axis
369 min and max and should return a ticks array. Here's a simplistic tick
370 generator that spits out intervals of pi, suitable for use on the x
371 axis for trigonometric functions:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
372
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
373 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
374 function piTickGenerator(axis) {
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
375 var res = [], i = Math.floor(axis.min / Math.PI);
376 do {
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
377 var v = i * Math.PI;
378 res.push([v, i + "\u03c0"]);
379 ++i;
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
380 } while (v < axis.max);
381 return res;
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
382 }
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
383 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
384
865688a Some further tweaks to time series handling, implemented support for …
olau@iola.dk authored
385 You can control how the ticks look like with "tickDecimals", the
386 number of decimals to display (default is auto-detected).
387
bad53ab Revamped internals to add support for extra axes, not just dual (spon…
olau@iola.dk authored
388 Alternatively, for ultimate control over how ticks are formatted you can
08a5c94 Shuffled the explanation of time series support around a bit
olau@iola.dk authored
389 provide a function to "tickFormatter". The function is passed two
6e3c674 Little stylistic fix in API.txt
olau@iola.dk authored
390 parameters, the tick value and an axis object with information, and
08a5c94 Shuffled the explanation of time series support around a bit
olau@iola.dk authored
391 should return a string. The default formatter looks like this:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
392
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
393 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
394 function formatter(val, axis) {
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
395 return val.toFixed(axis.tickDecimals);
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
396 }
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
397 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
398
865688a Some further tweaks to time series handling, implemented support for …
olau@iola.dk authored
399 The axis object has "min" and "max" with the range of the axis,
400 "tickDecimals" with the number of decimals to round the value to and
401 "tickSize" with the size of the interval between ticks as calculated
402 by the automatic axis scaling algorithm (or specified by you). Here's
403 an example of a custom formatter:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
404
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
405 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
406 function suffixFormatter(val, axis) {
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
407 if (val > 1000000)
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
408 return (val / 1000000).toFixed(axis.tickDecimals) + " MB";
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
409 else if (val > 1000)
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
410 return (val / 1000).toFixed(axis.tickDecimals) + " kB";
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
411 else
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
412 return val.toFixed(axis.tickDecimals) + " B";
413 }
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
414 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
415
bad53ab Revamped internals to add support for extra axes, not just dual (spon…
olau@iola.dk authored
416 "labelWidth" and "labelHeight" specifies a fixed size of the tick
417 labels in pixels. They're useful in case you need to align several
47821c7 Refactor the axis dimension calculations slightly to avoid the whole
olau@iola.dk authored
418 plots. "reserveSpace" means that even if an axis isn't shown, Flot
419 should reserve space for it - it is useful in combination with
420 labelWidth and labelHeight for aligning multi-axis charts.
bad53ab Revamped internals to add support for extra axes, not just dual (spon…
olau@iola.dk authored
421
422 "tickLength" is the length of the tick lines in pixels. By default, the
423 innermost axes will have ticks that extend all across the plot, while
424 any extra axes use small ticks. A value of null means use the default,
425 while a number means small ticks of that length - set it to 0 to hide
426 the lines completely.
8155391 Some cleanup in tick generation code, added support for aligning axes
olau@iola.dk authored
427
428 If you set "alignTicksWithAxis" to the number of another axis, e.g.
429 alignTicksWithAxis: 1, Flot will ensure that the autogenerated ticks
430 of this axis are aligned with the ticks of the other axis. This may
431 improve the looks, e.g. if you have one y axis to the left and one to
432 the right, because the grid lines will then match the ticks in both
433 ends. The trade-off is that the forced ticks won't necessarily be at
434 natural places.
435
bad53ab Revamped internals to add support for extra axes, not just dual (spon…
olau@iola.dk authored
436
cc974bd @dnschnur Additional cleanup and markup standardization.
dnschnur authored
437 ## Multiple axes ##
bad53ab Revamped internals to add support for extra axes, not just dual (spon…
olau@iola.dk authored
438
439 If you need more than one x axis or y axis, you need to specify for
440 each data series which axis they are to use, as described under the
441 format of the data series, e.g. { data: [...], yaxis: 2 } specifies
442 that a series should be plotted against the second y axis.
443
444 To actually configure that axis, you can't use the xaxis/yaxis options
445 directly - instead there are two arrays in the options:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
446
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
447 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
448 xaxes: []
449 yaxes: []
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
450 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
451
bad53ab Revamped internals to add support for extra axes, not just dual (spon…
olau@iola.dk authored
452 Here's an example of configuring a single x axis and two y axes (we
453 can leave options of the first y axis empty as the defaults are fine):
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
454
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
455 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
456 {
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
457 xaxes: [ { position: "top" } ],
458 yaxes: [ { }, { position: "right", min: 20 } ]
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
459 }
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
460 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
461
bad53ab Revamped internals to add support for extra axes, not just dual (spon…
olau@iola.dk authored
462 The arrays get their default values from the xaxis/yaxis settings, so
463 say you want to have all y axes start at zero, you can simply specify
464 yaxis: { min: 0 } instead of adding a min parameter to all the axes.
465
466 Generally, the various interfaces in Flot dealing with data points
467 either accept an xaxis/yaxis parameter to specify which axis number to
468 use (starting from 1), or lets you specify the coordinate directly as
469 x2/x3/... or x2axis/x3axis/... instead of "x" or "xaxis".
470
8542929 @markrcote Moved time-series functionality into a separate plug-in and incorporated
markrcote authored
471
cc974bd @dnschnur Additional cleanup and markup standardization.
dnschnur authored
472 ## Time series data ##
dfba9f3 Documented the date support, tweaking the API a bit in the process, d…
olau@iola.dk authored
473
8542929 @markrcote Moved time-series functionality into a separate plug-in and incorporated
markrcote authored
474 Please note that it is now required to include the time plugin,
475 jquery.flot.time.js, for time series support.
476
84a7a27 Display dates according to UTC instead of according to the time zone …
olau@iola.dk authored
477 Time series are a bit more difficult than scalar data because
478 calendars don't follow a simple base 10 system. For many cases, Flot
479 abstracts most of this away, but it can still be a bit difficult to
480 get the data into Flot. So we'll first discuss the data format.
481
dfba9f3 Documented the date support, tweaking the API a bit in the process, d…
olau@iola.dk authored
482 The time series support in Flot is based on Javascript timestamps,
865688a Some further tweaks to time series handling, implemented support for …
olau@iola.dk authored
483 i.e. everywhere a time value is expected or handed over, a Javascript
84a7a27 Display dates according to UTC instead of according to the time zone …
olau@iola.dk authored
484 timestamp number is used. This is a number, not a Date object. A
dfba9f3 Documented the date support, tweaking the API a bit in the process, d…
olau@iola.dk authored
485 Javascript timestamp is the number of milliseconds since January 1,
65cae14 Fixed wording
olau@iola.dk authored
486 1970 00:00:00 UTC. This is almost the same as Unix timestamps, except it's
dfba9f3 Documented the date support, tweaking the API a bit in the process, d…
olau@iola.dk authored
487 in milliseconds, so remember to multiply by 1000!
488
84a7a27 Display dates according to UTC instead of according to the time zone …
olau@iola.dk authored
489 You can see a timestamp like this
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
490
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
491 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
492 alert((new Date()).getTime())
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
493 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
494
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
495 There are different schools of thought when it comes to diplay of
8542929 @markrcote Moved time-series functionality into a separate plug-in and incorporated
markrcote authored
496 timestamps. Many will want the timestamps to be displayed according to
497 a certain time zone, usually the time zone in which the data has been
498 produced. Some want the localized experience, where the timestamps are
499 displayed according to the local time of the visitor. Flot supports
500 both. Optionally you can include a third-party library to get
501 additional timezone support.
dfba9f3 Documented the date support, tweaking the API a bit in the process, d…
olau@iola.dk authored
502
8542929 @markrcote Moved time-series functionality into a separate plug-in and incorporated
markrcote authored
503 Default behavior is that Flot always displays timestamps according to
504 UTC. The reason being that the core Javascript Date object does not
505 support other fixed time zones. Often your data is at another time
506 zone, so it may take a little bit of tweaking to work around this
507 limitation.
84a7a27 Display dates according to UTC instead of according to the time zone …
olau@iola.dk authored
508
509 The easiest way to think about it is to pretend that the data
510 production time zone is UTC, even if it isn't. So if you have a
511 datapoint at 2002-02-20 08:00, you can generate a timestamp for eight
08a5c94 Shuffled the explanation of time series support around a bit
olau@iola.dk authored
512 o'clock UTC even if it really happened eight o'clock UTC+0200.
dfba9f3 Documented the date support, tweaking the API a bit in the process, d…
olau@iola.dk authored
513
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
514 In PHP you can get an appropriate timestamp with:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
515
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
516 ```php
517 strtotime("2002-02-20 UTC") * 1000
518 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
519
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
520 In Python you can get it with something like:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
521
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
522 ```python
523 calendar.timegm(datetime_object.timetuple()) * 1000
524 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
525
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
526 In .NET you can get it with something like:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
527
cc974bd @dnschnur Additional cleanup and markup standardization.
dnschnur authored
528 ```aspx
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
529 public static int GetJavascriptTimestamp(System.DateTime input)
530 {
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
531 System.TimeSpan span = new System.TimeSpan(System.DateTime.Parse("1/1/1970").Ticks);
532 System.DateTime time = input.Subtract(span);
533 return (long)(time.Ticks / 10000);
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
534 }
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
535 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
536
84a7a27 Display dates according to UTC instead of according to the time zone …
olau@iola.dk authored
537 Javascript also has some support for parsing date strings, so it is
08a5c94 Shuffled the explanation of time series support around a bit
olau@iola.dk authored
538 possible to generate the timestamps manually client-side.
539
540 If you've already got the real UTC timestamp, it's too late to use the
541 pretend trick described above. But you can fix up the timestamps by
542 adding the time zone offset, e.g. for UTC+0200 you would add 2 hours
543 to the UTC timestamp you got. Then it'll look right on the plot. Most
544 programming environments have some means of getting the timezone
9b08e82 Added documentation and example for the crosshairs feature
olau@iola.dk authored
545 offset for a specific date (note that you need to get the offset for
546 each individual timestamp to account for daylight savings).
08a5c94 Shuffled the explanation of time series support around a bit
olau@iola.dk authored
547
8542929 @markrcote Moved time-series functionality into a separate plug-in and incorporated
markrcote authored
548 The alternative with core Javascript is to interpret the timestamps
549 according to the time zone that the visitor is in, which means that
550 the ticks will shift with the time zone and daylight savings of each
551 visitor. This behavior is enabled by setting the axis option
552 "timezone" to the value "browser".
553
554 If you need more zime zone functionality than this, there is still
555 another option. If you include the "timezone-js" library
556 <https://github.com/mde/timezone-js> in the page and set axis.timezone
557 to a value recognized by said library, Flot will use timezone-js to
558 interpret the timestamps according to that time zone.
559
60689d2 Support for partial bars, this is useful for stacked bars
olau@iola.dk authored
560 Once you've gotten the timestamps into the data and specified "time"
561 as the axis mode, Flot will automatically generate relevant ticks and
84a7a27 Display dates according to UTC instead of according to the time zone …
olau@iola.dk authored
562 format them. As always, you can tweak the ticks via the "ticks" option
08a5c94 Shuffled the explanation of time series support around a bit
olau@iola.dk authored
563 - just remember that the values should be timestamps (numbers), not
564 Date objects.
dfba9f3 Documented the date support, tweaking the API a bit in the process, d…
olau@iola.dk authored
565
84a7a27 Display dates according to UTC instead of according to the time zone …
olau@iola.dk authored
566 Tick generation and formatting can also be controlled separately
567 through the following axis options:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
568
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
569 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
570 minTickSize: array
571 timeformat: null or format string
572 monthNames: null or array of size 12 of strings
573 dayNames: null or array of size 7 of strings
574 twelveHourClock: boolean
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
575 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
576
dfba9f3 Documented the date support, tweaking the API a bit in the process, d…
olau@iola.dk authored
577 Here "timeformat" is a format string to use. You might use it like
578 this:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
579
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
580 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
581 xaxis: {
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
582 mode: "time"
583 timeformat: "%Y/%m/%d"
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
584 }
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
585 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
586
22ac76c @markrcote Updated docs. Removed %u specifier.
markrcote authored
587 This will result in tick labels like "2000/12/24". A subset of the
588 standard strftime specifiers are supported:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
589
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
590 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
591 %a: weekday name (customizable)
592 %b: month name (customizable)
593 %d: day of month, zero-padded (01-31)
594 %e: day of month, space-padded ( 1-31)
595 %H: hours, 24-hour time, zero-padded (00-23)
596 %I: hours, 12-hour time, zero-padded (01-12)
597 %m: month, zero-padded (01-12)
598 %M: minutes, zero-padded (00-59)
599 %S: seconds, zero-padded (00-59)
600 %y: year (two digits)
601 %Y: year (four digits)
602 %p: am/pm
603 %P: AM/PM (uppercase version of %p)
604 %w: weekday as number (0-6, 0 being Sunday)
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
605 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
606
dfba9f3 Documented the date support, tweaking the API a bit in the process, d…
olau@iola.dk authored
607 You can customize the month names with the "monthNames" option. For
608 instance, for Danish you might specify:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
609
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
610 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
611 monthNames: ["jan", "feb", "mar", "apr", "maj", "jun", "jul", "aug", "sep", "okt", "nov", "dec"]
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
612 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
613
22ac76c @markrcote Updated docs. Removed %u specifier.
markrcote authored
614 Similarly you can customize the weekday names with the "dayNames"
615 option. An example in French:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
616
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
617 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
618 dayNames: ["dim", "lun", "mar", "mer", "jeu", "ven", "sam"]
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
619 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
620
0c54df7 Added support for 12 hour timestamps, patch by Forrest Aldridge
olau@iola.dk authored
621 If you set "twelveHourClock" to true, the autogenerated timestamps
22ac76c @markrcote Updated docs. Removed %u specifier.
markrcote authored
622 will use 12 hour AM/PM timestamps instead of 24 hour. This only
623 applies if you have not set "timeformat". Use the "%I" and "%p" or
624 "%P" options if you want to build your own format string with 12-hour
625 times.
626
627 If the Date object has a strftime property (and it is a function), it
628 will be used instead of the built-in formatter. Thus you can include
629 a strftime library such as http://hacks.bluesmoon.info/strftime/ for
630 more powerful date/time formatting.
d0c96fc Added access to the built-in date formatter through $.plot.formatDate
olau@iola.dk authored
631
dfba9f3 Documented the date support, tweaking the API a bit in the process, d…
olau@iola.dk authored
632 If everything else fails, you can control the formatting by specifying
633 a custom tick formatter function as usual. Here's a simple example
634 which will format December 24 as 24/12:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
635
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
636 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
637 tickFormatter: function (val, axis) {
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
638 var d = new Date(val);
639 return d.getUTCDate() + "/" + (d.getUTCMonth() + 1);
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
640 }
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
641 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
642
865688a Some further tweaks to time series handling, implemented support for …
olau@iola.dk authored
643 Note that for the time mode "tickSize" and "minTickSize" are a bit
644 special in that they are arrays on the form "[value, unit]" where unit
645 is one of "second", "minute", "hour", "day", "month" and "year". So
646 you can specify
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
647
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
648 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
649 minTickSize: [1, "month"]
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
650 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
651
865688a Some further tweaks to time series handling, implemented support for …
olau@iola.dk authored
652 to get a tick interval size of at least 1 month and correspondingly,
653 if axis.tickSize is [2, "day"] in the tick formatter, the ticks have
654 been produced with two days in-between.
655
19eb761 Documented more options
olau@iola.dk authored
656
cc974bd @dnschnur Additional cleanup and markup standardization.
dnschnur authored
657 ## Customizing the data series ##
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
658
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
659 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
660 series: {
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
661 lines, points, bars: {
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
662 show: boolean
663 lineWidth: number
664 fill: boolean or number
665 fillColor: null or color/gradient
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
666 }
19eb761 Documented more options
olau@iola.dk authored
667
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
668 points: {
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
669 radius: number
670 symbol: "circle" or function
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
671 }
672
673 bars: {
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
674 barWidth: number
675 align: "left", "right" or "center"
676 horizontal: boolean
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
677 }
678
679 lines: {
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
680 steps: boolean
0d15280 Implemented plugin system, introduced experimental hooks system (thre…
olau@iola.dk authored
681 }
f6b0832 Added support for coloring the data points below a certain threshold
olau@iola.dk authored
682
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
683 shadowSize: number
070fd83 @dnschnur Added docs for the highlightColor option.
dnschnur authored
684 highlightColor: color or number
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
685 }
686
687 colors: [ color1, color2, ... ]
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
688 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
689
0d15280 Implemented plugin system, introduced experimental hooks system (thre…
olau@iola.dk authored
690 The options inside "series: {}" are copied to each of the series. So
691 you can specify that all series should have bars by putting it in the
692 global options, or override it for individual series by specifying
693 bars in a particular the series object in the array of data.
694
19eb761 Documented more options
olau@iola.dk authored
695 The most important options are "lines", "points" and "bars" that
0d15280 Implemented plugin system, introduced experimental hooks system (thre…
olau@iola.dk authored
696 specify whether and how lines, points and bars should be shown for
dd8b499 Clear up a couple of things related to not showing lines
olau@iola.dk authored
697 each data series. In case you don't specify anything at all, Flot will
698 default to showing lines (you can turn this off with
c3a34cd Support for specifying a bottom for each point for line charts when
olau@iola.dk authored
699 lines: { show: false }). You can specify the various types
dd8b499 Clear up a couple of things related to not showing lines
olau@iola.dk authored
700 independently of each other, and Flot will happily draw each of them
0d15280 Implemented plugin system, introduced experimental hooks system (thre…
olau@iola.dk authored
701 in turn (this is probably only useful for lines and points), e.g.
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
702
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
703 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
704 var options = {
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
705 series: {
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
706 lines: { show: true, fill: true, fillColor: "rgba(255, 255, 255, 0.8)" },
707 points: { show: true, fill: false }
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
708 }
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
709 };
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
710 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
711
dd8b499 Clear up a couple of things related to not showing lines
olau@iola.dk authored
712 "lineWidth" is the thickness of the line or outline in pixels. You can
713 set it to 0 to prevent a line or outline from being drawn; this will
714 also hide the shadow.
f28eb70 Make it possible to set the fill opacity by setting fill to a number
olau@iola.dk authored
715
716 "fill" is whether the shape should be filled. For lines, this produces
717 area graphs. You can use "fillColor" to specify the color of the fill.
718 If "fillColor" evaluates to false (default for everything except
5144848 Clarify that the default fill color of points is white
olau@iola.dk authored
719 points which are filled with white), the fill color is auto-set to the
720 color of the data series. You can adjust the opacity of the fill by
721 setting fill to a number between 0 (fully transparent) and 1 (fully
722 opaque).
5a14a53 Finished documenting the API
olau@iola.dk authored
723
3a1d1e7 Added support for gradient bars
olau@iola.dk authored
724 For bars, fillColor can be a gradient, see the gradient documentation
5081ba4 Clarify that barWidth might also be in unit of the y axis
olau@iola.dk authored
725 below. "barWidth" is the width of the bars in units of the x axis (or
726 the y axis if "horizontal" is true), contrary to most other measures
727 that are specified in pixels. For instance, for time series the unit
728 is milliseconds so 24 * 60 * 60 * 1000 produces bars with the width of
729 a day. "align" specifies whether a bar should be left-aligned
40d886f @lastzero Implemented option to right-align a bar and updated API docs
lastzero authored
730 (default), right-aligned or centered on top of the value it represents.
731 When "horizontal" is on, the bars are drawn horizontally, i.e. from the
732 y axis instead of the x axis; note that the bar end points are still
5081ba4 Clarify that barWidth might also be in unit of the y axis
olau@iola.dk authored
733 defined in the same way so you'll probably want to swap the
734 coordinates if you've been plotting vertical bars first.
19eb761 Documented more options
olau@iola.dk authored
735
89ce1ca Introduce step-wise line charts, extending the data model to have (po…
olau@iola.dk authored
736 For lines, "steps" specifies whether two adjacent data points are
737 connected with a straight (possibly diagonal) line or with first a
0d15280 Implemented plugin system, introduced experimental hooks system (thre…
olau@iola.dk authored
738 horizontal and then a vertical line. Note that this transforms the
739 data by adding extra points.
740
8031f5f Support for customizing the point type through a callback when plotti…
olau@iola.dk authored
741 For points, you can specify the radius and the symbol. The only
742 built-in symbol type is circles, for other types you can use a plugin
743 or define them yourself by specifying a callback:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
744
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
745 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
746 function cross(ctx, x, y, radius, shadow) {
747 var size = radius * Math.sqrt(Math.PI) / 2;
748 ctx.moveTo(x - size, y - size);
749 ctx.lineTo(x + size, y + size);
750 ctx.moveTo(x - size, y + size);
751 ctx.lineTo(x + size, y - size);
752 }
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
753 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
754
8031f5f Support for customizing the point type through a callback when plotti…
olau@iola.dk authored
755 The parameters are the drawing context, x and y coordinates of the
756 center of the point, a radius which corresponds to what the circle
757 would have used and whether the call is to draw a shadow (due to
758 limited canvas support, shadows are currently faked through extra
759 draws). It's good practice to ensure that the area covered by the
760 symbol is the same as for the circle with the given radius, this
761 ensures that all symbols have approximately the same visual weight.
762
0d15280 Implemented plugin system, introduced experimental hooks system (thre…
olau@iola.dk authored
763 "shadowSize" is the default size of shadows in pixels. Set it to 0 to
764 remove shadows.
89ce1ca Introduce step-wise line charts, extending the data model to have (po…
olau@iola.dk authored
765
070fd83 @dnschnur Added docs for the highlightColor option.
dnschnur authored
766 "highlightColor" is the default color of the translucent overlay used
767 to highlight the series when the mouse hovers over it.
768
19eb761 Documented more options
olau@iola.dk authored
769 The "colors" array specifies a default color theme to get colors for
770 the data series from. You can specify as many colors as you like, like
771 this:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
772
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
773 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
774 colors: ["#d18b2c", "#dba255", "#919733"]
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
775 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
776
19eb761 Documented more options
olau@iola.dk authored
777 If there are more data series than colors, Flot will try to generate
778 extra colors by lightening and darkening colors in the theme.
779
780
cc974bd @dnschnur Additional cleanup and markup standardization.
dnschnur authored
781 ## Customizing the grid ##
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
782
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
783 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
784 grid: {
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
785 show: boolean
786 aboveData: boolean
787 color: color
788 backgroundColor: color/gradient or null
789 margin: number or margin object
790 labelMargin: number
791 axisMargin: number
792 markings: array of markings or (fn: axes -> array of markings)
793 borderWidth: number
794 borderColor: color or null
795 minBorderMargin: number or null
796 clickable: boolean
797 hoverable: boolean
798 autoHighlight: boolean
799 mouseActiveRadius: number
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
800 }
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
801
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
802 interaction: {
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
803 redrawOverlayInterval: number or -1
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
804 }
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
805 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
806
947c166 Support for coloring axes, and automatic tick color selection
olau@iola.dk authored
807 The grid is the thing with the axes and a number of ticks. Many of the
808 things in the grid are configured under the individual axes, but not
809 all. "color" is the color of the grid itself whereas "backgroundColor"
810 specifies the background color inside the grid area, here null means
8a78e8f Added support for gradients, currently only used for the grid background
olau@iola.dk authored
811 that the background is transparent. You can also set a gradient, see
3360d27 Option to have the grid on top of the data, important for image plots…
olau@iola.dk authored
812 the gradient documentation below.
813
814 You can turn off the whole grid including tick labels by setting
815f80e Small documentation fixes
olau@iola.dk authored
815 "show" to false. "aboveData" determines whether the grid is drawn
3360d27 Option to have the grid on top of the data, important for image plots…
olau@iola.dk authored
816 above the data or below (below is default).
0759859 @dnschnur Added a grid.margin option
dnschnur authored
817
818 "margin" is the space in pixels between the canvas edge and the grid,
819 which can be either a number or an object with individual margins for
820 each side, in the form:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
821
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
822 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
823 margin: {
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
824 top: top margin in pixels
825 left: left margin in pixels
826 bottom: bottom margin in pixels
827 right: right margin in pixels
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
828 }
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
829 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
830
947c166 Support for coloring axes, and automatic tick color selection
olau@iola.dk authored
831 "labelMargin" is the space in pixels between tick labels and axis
832 line, and "axisMargin" is the space in pixels between axes when there
89bbfef @OleLaursen Switch to using canvas text to draw the axis labels, fix a problem wi…
OleLaursen authored
833 are two next to each other.
fbe4273 New options.grid.minBorderMargin for adjusting the minimum margin pro…
olau@iola.dk authored
834
947c166 Support for coloring axes, and automatic tick color selection
olau@iola.dk authored
835 "borderWidth" is the width of the border around the plot. Set it to 0
836 to disable the border. You can also set "borderColor" if you want the
837 border to have a different color than the grid lines.
fbe4273 New options.grid.minBorderMargin for adjusting the minimum margin pro…
olau@iola.dk authored
838 "minBorderMargin" controls the default minimum margin around the
839 border - it's used to make sure that points aren't accidentally
840 clipped by the canvas edge so by default the value is computed from
841 the point radius.
19eb761 Documented more options
olau@iola.dk authored
842
938928b Support for preventing event in setSelection and revamped coloredArea…
olau@iola.dk authored
843 "markings" is used to draw simple lines and rectangular areas in the
844 background of the plot. You can either specify an array of ranges on
bad53ab Revamped internals to add support for extra axes, not just dual (spon…
olau@iola.dk authored
845 the form { xaxis: { from, to }, yaxis: { from, to } } (with multiple
846 axes, you can specify coordinates for other axes instead, e.g. as
847 x2axis/x3axis/...) or with a function that returns such an array given
848 the axes for the plot in an object as the first parameter.
865688a Some further tweaks to time series handling, implemented support for …
olau@iola.dk authored
849
938928b Support for preventing event in setSelection and revamped coloredArea…
olau@iola.dk authored
850 You can set the color of markings by specifying "color" in the ranges
851 object. Here's an example array:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
852
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
853 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
854 markings: [ { xaxis: { from: 0, to: 2 }, yaxis: { from: 10, to: 10 }, color: "#bb0000" }, ... ]
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
855 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
856
865688a Some further tweaks to time series handling, implemented support for …
olau@iola.dk authored
857 If you leave out one of the values, that value is assumed to go to the
938928b Support for preventing event in setSelection and revamped coloredArea…
olau@iola.dk authored
858 border of the plot. So for example if you only specify { xaxis: {
859 from: 0, to: 2 } } it means an area that extends from the top to the
860 bottom of the plot in the x range 0-2.
861
862 A line is drawn if from and to are the same, e.g.
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
863
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
864 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
865 markings: [ { yaxis: { from: 1, to: 1 } }, ... ]
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
866 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
867
938928b Support for preventing event in setSelection and revamped coloredArea…
olau@iola.dk authored
868 would draw a line parallel to the x axis at y = 1. You can control the
e8d764d Added "pointOffset" for converting a point in data space to an offset
olau@iola.dk authored
869 line width with "lineWidth" in the range object.
865688a Some further tweaks to time series handling, implemented support for …
olau@iola.dk authored
870
bad53ab Revamped internals to add support for extra axes, not just dual (spon…
olau@iola.dk authored
871 An example function that makes vertical stripes might look like this:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
872
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
873 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
874 markings: function (axes) {
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
875 var markings = [];
876 for (var x = Math.floor(axes.xaxis.min); x < axes.xaxis.max; x += 2)
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
877 markings.push({ xaxis: { from: x, to: x + 1 } });
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
878 return markings;
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
879 }
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
880 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
881
f4ffef2 Added support for clicking on the plot, still a bit primitive
olau@iola.dk authored
882 If you set "clickable" to true, the plot will listen for click events
865688a Some further tweaks to time series handling, implemented support for …
olau@iola.dk authored
883 on the plot area and fire a "plotclick" event on the placeholder with
4bc191f Spit out pageX/pageY in "plotclick" and "plothover" events, add primi…
olau@iola.dk authored
884 a position and a nearby data item object as parameters. The coordinates
885 are available both in the unit of the axes (not in pixels) and in
886 global screen coordinates.
7c9ff67 Landed dual axis/hover event/finding nearby datapoints patch
olau@iola.dk authored
887
da9023c Document highlight and related
olau@iola.dk authored
888 Likewise, if you set "hoverable" to true, the plot will listen for
889 mouse move events on the plot area and fire a "plothover" event with
890 the same parameters as the "plotclick" event. If "autoHighlight" is
891 true (the default), nearby data items are highlighted automatically.
892 If needed, you can disable highlighting and control it yourself with
893 the highlight/unhighlight plot methods described elsewhere.
7c9ff67 Landed dual axis/hover event/finding nearby datapoints patch
olau@iola.dk authored
894
895 You can use "plotclick" and "plothover" events like this:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
896
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
897 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
898 $.plot($("#placeholder"), [ d ], { grid: { clickable: true } });
899
900 $("#placeholder").bind("plotclick", function (event, pos, item) {
901 alert("You clicked at " + pos.x + ", " + pos.y);
902 // axis coordinates for other axes, if present, are in pos.x2, pos.x3, ...
903 // if you need global screen coordinates, they are pos.pageX, pos.pageY
904
905 if (item) {
906 highlight(item.series, item.datapoint);
907 alert("You clicked a point!");
908 }
909 });
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
910 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
911
7c9ff67 Landed dual axis/hover event/finding nearby datapoints patch
olau@iola.dk authored
912 The item object in this example is either null or a nearby object on the form:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
913
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
914 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
915 item: {
916 datapoint: the point, e.g. [0, 2]
917 dataIndex: the index of the point in the data array
918 series: the series object
919 seriesIndex: the index of the series
920 pageX, pageY: the global screen coordinates of the point
921 }
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
922 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
923
7c9ff67 Landed dual axis/hover event/finding nearby datapoints patch
olau@iola.dk authored
924 For instance, if you have specified the data like this
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
925
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
926 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
927 $.plot($("#placeholder"), [ { label: "Foo", data: [[0, 10], [7, 3]] } ], ...);
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
928 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
929
0d15280 Implemented plugin system, introduced experimental hooks system (thre…
olau@iola.dk authored
930 and the mouse is near the point (7, 3), "datapoint" is [7, 3],
931 "dataIndex" will be 1, "series" is a normalized series object with
932 among other things the "Foo" label in series.label and the color in
933 series.color, and "seriesIndex" is 0. Note that plugins and options
934 that transform the data can shift the indexes from what you specified
935 in the original data array.
7c9ff67 Landed dual axis/hover event/finding nearby datapoints patch
olau@iola.dk authored
936
da9023c Document highlight and related
olau@iola.dk authored
937 If you use the above events to update some other information and want
938 to clear out that info in case the mouse goes away, you'll probably
939 also need to listen to "mouseout" events on the placeholder div.
940
941 "mouseActiveRadius" specifies how far the mouse can be from an item
942 and still activate it. If there are two or more points within this
20fe8fd Added special-case for highlighting bars
olau@iola.dk authored
943 radius, Flot chooses the closest item. For bars, the top-most bar
944 (from the latest specified data series) is chosen.
f4ffef2 Added support for clicking on the plot, still a bit primitive
olau@iola.dk authored
945
5587862 Added support for disabling interactivity for specific plots
olau@iola.dk authored
946 If you want to disable interactivity for a specific data series, you
947 can set "hoverable" and "clickable" to false in the options for that
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
948 series, like this:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
949
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
950 ```js
951 { data: [...], label: "Foo", clickable: false }
952 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
953
f6cebd3 @OleLaursen Update excanvas and remove previous eventholder work-around to fix ho…
OleLaursen authored
954 "redrawOverlayInterval" specifies the maximum time to delay a redraw
955 of interactive things (this works as a rate limiting device). The
956 default is capped to 60 frames per second. You can set it to -1 to
957 disable the rate limiting.
958
f4ffef2 Added support for clicking on the plot, still a bit primitive
olau@iola.dk authored
959
cc974bd @dnschnur Additional cleanup and markup standardization.
dnschnur authored
960 ## Specifying gradients ##
8a78e8f Added support for gradients, currently only used for the grid background
olau@iola.dk authored
961
962 A gradient is specified like this:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
963
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
964 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
965 { colors: [ color1, color2, ... ] }
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
966 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
967
8a78e8f Added support for gradients, currently only used for the grid background
olau@iola.dk authored
968 For instance, you might specify a background on the grid going from
969 black to gray like this:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
970
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
971 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
972 grid: {
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
973 backgroundColor: { colors: ["#000", "#999"] }
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
974 }
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
975 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
976
3a1d1e7 Added support for gradient bars
olau@iola.dk authored
977 For the series you can specify the gradient as an object that
978 specifies the scaling of the brightness and the opacity of the series
979 color, e.g.
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
980
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
981 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
982 { colors: [{ opacity: 0.8 }, { brightness: 0.6, opacity: 0.8 } ] }
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
983 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
984
3a1d1e7 Added support for gradient bars
olau@iola.dk authored
985 where the first color simply has its alpha scaled, whereas the second
563349c Add example of using gradients with bars
olau@iola.dk authored
986 is also darkened. For instance, for bars the following makes the bars
987 gradually disappear, without outline:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
988
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
989 ```js
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
990 bars: {
991 show: true,
992 lineWidth: 0,
993 fill: true,
994 fillColor: { colors: [ { opacity: 0.8 }, { opacity: 0.1 } ] }
995 }
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
996 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
997
8a78e8f Added support for gradients, currently only used for the grid background
olau@iola.dk authored
998 Flot currently only supports vertical gradients drawn from top to
999 bottom because that's what works with IE.
1000
1001
cc974bd @dnschnur Additional cleanup and markup standardization.
dnschnur authored
1002 ## Plot Methods ##
d2a5a63 First draft, options are not documented yet
olau@iola.dk authored
1003
da9023c Document highlight and related
olau@iola.dk authored
1004 The Plot object returned from the plot function has some methods you
078f25e Fixed description of methods returning internals
olau@iola.dk authored
1005 can call:
d2a5a63 First draft, options are not documented yet
olau@iola.dk authored
1006
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
1007 - highlight(series, datapoint)
da9023c Document highlight and related
olau@iola.dk authored
1008
1009 Highlight a specific datapoint in the data series. You can either
1010 specify the actual objects, e.g. if you got them from a
1011 "plotclick" event, or you can specify the indices, e.g.
0d15280 Implemented plugin system, introduced experimental hooks system (thre…
olau@iola.dk authored
1012 highlight(1, 3) to highlight the fourth point in the second series
1013 (remember, zero-based indexing).
da9023c Document highlight and related
olau@iola.dk authored
1014
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
1015 - unhighlight(series, datapoint) or unhighlight()
0d15280 Implemented plugin system, introduced experimental hooks system (thre…
olau@iola.dk authored
1016
1017 Remove the highlighting of the point, same parameters as
1018 highlight.
da9023c Document highlight and related
olau@iola.dk authored
1019
0d15280 Implemented plugin system, introduced experimental hooks system (thre…
olau@iola.dk authored
1020 If you call unhighlight with no parameters, e.g. as
1021 plot.unhighlight(), all current highlights are removed.
da9023c Document highlight and related
olau@iola.dk authored
1022
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
1023 - setData(data)
2015ca3 Added more members to the Plot object + a few cleanups
olau@iola.dk authored
1024
1025 You can use this to reset the data used. Note that axis scaling,
1026 ticks, legend etc. will not be recomputed (use setupGrid() to do
1027 that). You'll probably want to call draw() afterwards.
1028
f1db197 New option grid.show, set to false to disable the grid
olau@iola.dk authored
1029 You can use this function to speed up redrawing a small plot if
1030 you know that the axes won't change. Put in the new data with
1031 setData(newdata), call draw(), and you're good to go. Note that
1032 for large datasets, almost all the time is consumed in draw()
1033 plotting the data so in this case don't bother.
2015ca3 Added more members to the Plot object + a few cleanups
olau@iola.dk authored
1034
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
1035 - setupGrid()
2015ca3 Added more members to the Plot object + a few cleanups
olau@iola.dk authored
1036
1037 Recalculate and set axis scaling, ticks, legend etc.
1038
1039 Note that because of the drawing model of the canvas, this
1040 function will immediately redraw (actually reinsert in the DOM)
1041 the labels and the legend, but not the actual tick lines because
1042 they're drawn on the canvas. You need to call draw() to get the
1043 canvas redrawn.
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
1044
1045 - draw()
2015ca3 Added more members to the Plot object + a few cleanups
olau@iola.dk authored
1046
d3acc16 Removed work-around for slow jQuery mousemove events (closing issue
olau@iola.dk authored
1047 Redraws the plot canvas.
1048
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
1049 - triggerRedrawOverlay()
d3acc16 Removed work-around for slow jQuery mousemove events (closing issue
olau@iola.dk authored
1050
1051 Schedules an update of an overlay canvas used for drawing
d54a40c Move selection support to a plugin (based on patch from andershol),
olau@iola.dk authored
1052 interactive things like a selection and point highlights. This
d3acc16 Removed work-around for slow jQuery mousemove events (closing issue
olau@iola.dk authored
1053 is mostly useful for writing plugins. The redraw doesn't happen
1054 immediately, instead a timer is set to catch multiple successive
dbc1270 Mention that you can get to the overlay by setting up a drawOverlay hook
olau@iola.dk authored
1055 redraws (e.g. from a mousemove). You can get to the overlay by
1056 setting up a drawOverlay hook.
d3acc16 Removed work-around for slow jQuery mousemove events (closing issue
olau@iola.dk authored
1057
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
1058 - width()/height()
d3acc16 Removed work-around for slow jQuery mousemove events (closing issue
olau@iola.dk authored
1059
1060 Gets the width and height of the plotting area inside the grid.
1061 This is smaller than the canvas or placeholder dimensions as some
1062 extra space is needed (e.g. for labels).
1063
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
1064 - offset()
d3acc16 Removed work-around for slow jQuery mousemove events (closing issue
olau@iola.dk authored
1065
1066 Returns the offset of the plotting area inside the grid relative
1067 to the document, useful for instance for calculating mouse
1068 positions (event.pageX/Y minus this offset is the pixel position
1069 inside the plot).
e8d764d Added "pointOffset" for converting a point in data space to an offset
olau@iola.dk authored
1070
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
1071 - pointOffset({ x: xpos, y: ypos })
e8d764d Added "pointOffset" for converting a point in data space to an offset
olau@iola.dk authored
1072
1073 Returns the calculated offset of the data point at (x, y) in data
4ee1e04 @dnschnur Added processOffset and drawBackground hooks
dnschnur authored
1074 space within the placeholder div. If you are working with multiple
1075 axes, you can specify the x and y axis references, e.g.
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
1076
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
1077 ```js
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
1078 o = pointOffset({ x: xpos, y: ypos, xaxis: 2, yaxis: 3 })
1079 // o.left and o.top now contains the offset within the div
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
1080 ````
4e02781 Refactor replot behaviour so Flot tries to reuse the existing canvas,
olau@iola.dk authored
1081
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
1082 - resize()
4e02781 Refactor replot behaviour so Flot tries to reuse the existing canvas,
olau@iola.dk authored
1083
1084 Tells Flot to resize the drawing canvas to the size of the
1085 placeholder. You need to run setupGrid() and draw() afterwards as
1086 canvas resizing is a destructive operation. This is used
1087 internally by the resize plugin.
1088
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
1089 - shutdown()
4e02781 Refactor replot behaviour so Flot tries to reuse the existing canvas,
olau@iola.dk authored
1090
1091 Cleans up any event handlers Flot has currently registered. This
1092 is used internally.
1093
078f25e Fixed description of methods returning internals
olau@iola.dk authored
1094 There are also some members that let you peek inside the internal
e8d764d Added "pointOffset" for converting a point in data space to an offset
olau@iola.dk authored
1095 workings of Flot which is useful in some cases. Note that if you change
078f25e Fixed description of methods returning internals
olau@iola.dk authored
1096 something in the objects returned, you're changing the objects used by
1097 Flot to keep track of its state, so be careful.
1098
1099 - getData()
1100
0d15280 Implemented plugin system, introduced experimental hooks system (thre…
olau@iola.dk authored
1101 Returns an array of the data series currently used in normalized
078f25e Fixed description of methods returning internals
olau@iola.dk authored
1102 form with missing settings filled in according to the global
1103 options. So for instance to find out what color Flot has assigned
1104 to the data series, you could do this:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
1105
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
1106 ```js
1107 var series = plot.getData();
1108 for (var i = 0; i < series.length; ++i)
078f25e Fixed description of methods returning internals
olau@iola.dk authored
1109 alert(series[i].color);
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
1110 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
1111
0d15280 Implemented plugin system, introduced experimental hooks system (thre…
olau@iola.dk authored
1112 A notable other interesting field besides color is datapoints
1113 which has a field "points" with the normalized data points in a
f1db197 New option grid.show, set to false to disable the grid
olau@iola.dk authored
1114 flat array (the field "pointsize" is the increment in the flat
1115 array to get to the next point so for a dataset consisting only of
1116 (x,y) pairs it would be 2).
078f25e Fixed description of methods returning internals
olau@iola.dk authored
1117
1118 - getAxes()
1119
bad53ab Revamped internals to add support for extra axes, not just dual (spon…
olau@iola.dk authored
1120 Gets an object with the axes. The axes are returned as the
1121 attributes of the object, so for instance getAxes().xaxis is the
1122 x axis.
e8d764d Added "pointOffset" for converting a point in data space to an offset
olau@iola.dk authored
1123
1124 Various things are stuffed inside an axis object, e.g. you could
1125 use getAxes().xaxis.ticks to find out what the ticks are for the
1126 xaxis. Two other useful attributes are p2c and c2p, functions for
1127 transforming from data point space to the canvas plot space and
1128 back. Both returns values that are offset with the plot offset.
bad53ab Revamped internals to add support for extra axes, not just dual (spon…
olau@iola.dk authored
1129 Check the Flot source code for the complete set of attributes (or
1130 output an axis with console.log() and inspect it).
1131
1132 With multiple axes, the extra axes are returned as x2axis, x3axis,
1133 etc., e.g. getAxes().y2axis is the second y axis. You can check
47821c7 Refactor the axis dimension calculations slightly to avoid the whole
olau@iola.dk authored
1134 y2axis.used to see whether the axis is associated with any data
1135 points and y2axis.show to see if it is currently shown.
0d15280 Implemented plugin system, introduced experimental hooks system (thre…
olau@iola.dk authored
1136
a7355c2 Added getPlaceholder and renamed internal target to placeholder
olau@iola.dk authored
1137 - getPlaceholder()
1138
1139 Returns placeholder that the plot was put into. This can be useful
1140 for plugins for adding DOM elements or firing events.
078f25e Fixed description of methods returning internals
olau@iola.dk authored
1141
1142 - getCanvas()
1143
1144 Returns the canvas used for drawing in case you need to hack on it
1145 yourself. You'll probably need to get the plot offset too.
1146
1147 - getPlotOffset()
1148
1149 Gets the offset that the grid has within the canvas as an object
da9023c Document highlight and related
olau@iola.dk authored
1150 with distances from the canvas edges as "left", "right", "top",
1151 "bottom". I.e., if you draw a circle on the canvas with the center
1152 placed at (left, top), its center will be at the top-most, left
1153 corner of the grid.
078f25e Fixed description of methods returning internals
olau@iola.dk authored
1154
0d15280 Implemented plugin system, introduced experimental hooks system (thre…
olau@iola.dk authored
1155 - getOptions()
1156
d2b0d36 Add a note about getOptions() being useful for changing options
olau@iola.dk authored
1157 Gets the options for the plot, normalized, with default values
1158 filled in. You get a reference to actual values used by Flot, so
1159 if you modify the values in here, Flot will use the new values.
1160 If you change something, you probably have to call draw() or
1161 setupGrid() or triggerRedrawOverlay() to see the change.
d3acc16 Removed work-around for slow jQuery mousemove events (closing issue
olau@iola.dk authored
1162
0d15280 Implemented plugin system, introduced experimental hooks system (thre…
olau@iola.dk authored
1163
cc974bd @dnschnur Additional cleanup and markup standardization.
dnschnur authored
1164 ## Hooks ##
0d15280 Implemented plugin system, introduced experimental hooks system (thre…
olau@iola.dk authored
1165
1166 In addition to the public methods, the Plot object also has some hooks
1167 that can be used to modify the plotting process. You can install a
1168 callback function at various points in the process, the function then
1169 gets access to the internal data structures in Flot.
1170
1171 Here's an overview of the phases Flot goes through:
1172
1173 1. Plugin initialization, parsing options
1174
d3acc16 Removed work-around for slow jQuery mousemove events (closing issue
olau@iola.dk authored
1175 2. Constructing the canvases used for drawing
0d15280 Implemented plugin system, introduced experimental hooks system (thre…
olau@iola.dk authored
1176
1177 3. Set data: parsing data specification, calculating colors,
1178 copying raw data points into internal format,
1179 normalizing them, finding max/min for axis auto-scaling
1180
1181 4. Grid setup: calculating axis spacing, ticks, inserting tick
1182 labels, the legend
1183
1184 5. Draw: drawing the grid, drawing each of the series in turn
1185
1186 6. Setting up event handling for interactive features
1187
1188 7. Responding to events, if any
1189
4e02781 Refactor replot behaviour so Flot tries to reuse the existing canvas,
olau@iola.dk authored
1190 8. Shutdown: this mostly happens in case a plot is overwritten
1191
9396ceb Added a hooks option to enable scripts to define hooks before doing a…
olau@iola.dk authored
1192 Each hook is simply a function which is put in the appropriate array.
1193 You can add them through the "hooks" option, and they are also available
1194 after the plot is constructed as the "hooks" attribute on the returned
1195 plot object, e.g.
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
1196
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
1197 ```js
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
1198 // define a simple draw hook
1199 function hellohook(plot, canvascontext) { alert("hello!"); };
0d15280 Implemented plugin system, introduced experimental hooks system (thre…
olau@iola.dk authored
1200
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
1201 // pass it in, in an array since we might want to specify several
1202 var plot = $.plot(placeholder, data, { hooks: { draw: [hellohook] } });
9396ceb Added a hooks option to enable scripts to define hooks before doing a…
olau@iola.dk authored
1203
4fa6e38 Correct GitHub Syntax Highlighting in API markdown
Alexander Blunck authored
1204 // we can now find it again in plot.hooks.draw[0] unless a plugin
1205 // has added other hooks
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
1206 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
1207
9396ceb Added a hooks option to enable scripts to define hooks before doing a…
olau@iola.dk authored
1208 The available hooks are described below. All hook callbacks get the
1209 plot object as first parameter. You can find some examples of defined
1210 hooks in the plugins bundled with Flot.
0d15280 Implemented plugin system, introduced experimental hooks system (thre…
olau@iola.dk authored
1211
1212 - processOptions [phase 1]
1213
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
1214 ```function(plot, options)```
0d15280 Implemented plugin system, introduced experimental hooks system (thre…
olau@iola.dk authored
1215
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
1216 Called after Flot has parsed and merged options. Useful in the
1217 instance where customizations beyond simple merging of default
1218 values is needed. A plugin might use it to detect that it has been
1219 enabled and then turn on or off other options.
d3acc16 Removed work-around for slow jQuery mousemove events (closing issue
olau@iola.dk authored
1220
0d15280 Implemented plugin system, introduced experimental hooks system (thre…
olau@iola.dk authored
1221
1222 - processRawData [phase 3]
1223
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
1224 ```function(plot, series, data, datapoints)```
0d15280 Implemented plugin system, introduced experimental hooks system (thre…
olau@iola.dk authored
1225
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
1226 Called before Flot copies and normalizes the raw data for the given
1227 series. If the function fills in datapoints.points with normalized
1228 points and sets datapoints.pointsize to the size of the points,
1229 Flot will skip the copying/normalization step for this series.
aebbf14 Generalized the data normalization step so it can be parameterized
olau@iola.dk authored
1230
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
1231 In any case, you might be interested in setting datapoints.format,
1232 an array of objects for specifying how a point is normalized and
1233 how it interferes with axis scaling.
1234
1235 The default format array for points is something along the lines of:
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
1236
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
1237 ```js
1238 [
1239 { x: true, number: true, required: true },
1240 { y: true, number: true, required: true }
1241 ]
1242 ```
a4de2ca @dnschnur Additional cleanup and markup standardization.
dnschnur authored
1243
633dd82 @dnschnur Cleaned up and standardized markup.
dnschnur authored
1244 The first object means that for the first coordinate it should be
1245 taken into account when scaling the x axis, that it must be a
1246 number, and that it is required - so if it is null or cannot be
1247 converted to a number, the whole point will be zeroed out with
1248 nulls. Beyond these you can also specify "defaultValue", a value to
1249 use if the coordinate is null. This is for instance handy for bars
1250 where one can omit the third coordinate (the bottom of the bar)
1251 which then defaults to 0.
d3acc16 Removed work-around for slow jQuery mousemove events (closing issue
olau@iola.dk