Flot Reference
--------------
Consider a call to the plot function:
var plot = $.plot(placeholder, data, options)
The placeholder is a jQuery object or DOM element or jQuery expression
that the plot will be put into. This placeholder needs to have its
width and height set as explained in the README (go read that now if
you haven't, it's short). The plot will modify some properties of the
placeholder so it's recommended you simply pass in a div that you
don't use for anything else. Make sure you check any fancy styling
you apply to the div, e.g. background images have been reported to be a
problem on IE 7.
The format of the data is documented below, as is the available
options. The plot object returned from the call has some methods you
can call. These are documented separately below.
Note that in general Flot gives no guarantees if you change any of the
objects you pass in to the plot function or get out of it since
they're not necessarily deep-copied.
Data Format
-----------
The data is an array of data series:
[ series1, series2, ... ]
A series can either be raw data or an object with properties. The raw
data format is an array of points:
[ [x1, y1], [x2, y2], ... ]
E.g.
[ [1, 3], [2, 14.01], [3.5, 3.14] ]
Note that to simplify the internal logic in Flot both the x and y
values must be numbers (even if specifying time series, see below for
how to do this). This is a common problem because you might retrieve
data from the database and serialize them directly to JSON without
noticing the wrong type. If you're getting mysterious errors, double
check that you're inputting numbers and not strings.
If a null is specified as a point or if one of the coordinates is null
or couldn't be converted to a number, the point is ignored when
drawing. As a special case, a null value for lines is interpreted as a
line segment end, i.e. the points before and after the null value are
not connected.
Lines and points take two coordinates. For filled lines and bars, you
can specify a third coordinate which is the bottom of the filled
area/bar (defaults to 0).
The format of a single series object is as follows:
{
color: color or number
data: rawdata
label: string
lines: specific lines options
bars: specific bars options
points: specific points options
xaxis: number
yaxis: number
clickable: boolean
hoverable: boolean
shadowSize: number
}
You don't have to specify any of them except the data, the rest are
options that will get default values. Typically you'd only specify
label and data, like this:
{
label: "y = 3",
data: [[0, 3], [10, 3]]
}
The label is used for the legend, if you don't specify one, the series
will not show up in the legend.
If you don't specify color, the series will get a color from the
auto-generated colors. The color is either a CSS color specification
(like "rgb(255, 100, 123)") or an integer that specifies which of
auto-generated colors to select, e.g. 0 will get color no. 0, etc.
The latter is mostly useful if you let the user add and remove series,
in which case you can hard-code the color index to prevent the colors
from jumping around between the series.
The "xaxis" and "yaxis" options specify which axis to use. The axes
are numbered from 1 (default), so { yaxis: 2} means that the series
should be plotted against the second y axis.
"clickable" and "hoverable" can be set to false to disable
interactivity for specific series if interactivity is turned on in
the plot, see below.
The rest of the options are all documented below as they are the same
as the default options passed in via the options parameter in the plot
commmand. When you specify them for a specific data series, they will
override the default options for the plot for that data series.
Here's a complete example of a simple data specification:
[ { label: "Foo", data: [ [10, 1], [17, -14], [30, 5] ] },
{ label: "Bar", data: [ [11, 13], [19, 11], [30, -7] ] } ]
Plot Options
------------
All options are completely optional. They are documented individually
below, to change them you just specify them in an object, e.g.
var options = {
series: {
lines: { show: true },
points: { show: true }
}
};
$.plot(placeholder, data, options);
Customizing the legend
======================
legend: {
show: boolean
labelFormatter: null or (fn: string, series object -> string)
labelBoxBorderColor: color
noColumns: number
position: "ne" or "nw" or "se" or "sw"
margin: number of pixels or [x margin, y margin]
backgroundColor: null or color
backgroundOpacity: number between 0 and 1
container: null or jQuery object/DOM element/jQuery expression
}
The legend is generated as a table with the data series labels and
small label boxes with the color of the series. If you want to format
the labels in some way, e.g. make them to links, you can pass in a
function for "labelFormatter". Here's an example that makes them
clickable:
labelFormatter: function(label, series) {
// series is the series object for the label
return '<a href="#' + label + '">' + label + '</a>';
}
"noColumns" is the number of columns to divide the legend table into.
"position" specifies the overall placement of the legend within the
plot (top-right, top-left, etc.) and margin the distance to the plot
edge (this can be either a number or an array of two numbers like [x,
y]). "backgroundColor" and "backgroundOpacity" specifies the
background. The default is a partly transparent auto-detected
background.
If you want the legend to appear somewhere else in the DOM, you can
specify "container" as a jQuery object/expression to put the legend
table into. The "position" and "margin" etc. options will then be
ignored. Note that Flot will overwrite the contents of the container.
Customizing the axes
====================
xaxis, yaxis: {
show: null or true/false
position: "bottom" or "top" or "left" or "right"
mode: null or "time"
color: null or color spec
tickColor: null or color spec
min: null or number
max: null or number
autoscaleMargin: null or number
transform: null or fn: number -> number
inverseTransform: null or fn: number -> number
ticks: null or number or ticks array or (fn: range -> ticks array)
tickSize: number or array
minTickSize: number or array
tickFormatter: (fn: number, object -> string) or string
tickDecimals: null or number
labelWidth: null or number
labelHeight: null or number
reserveSpace: null or true
tickLength: null or number
alignTicksWithAxis: null or number
}
All axes have the same kind of options. The following describes how to
configure one axis, see below for what to do if you've got more than
one x axis or y axis.
If you don't set the "show" option (i.e. it is null), visibility is
auto-detected, i.e. the axis will show up if there's data associated
with it. You can override this by setting the "show" option to true or
false.
The "position" option specifies where the axis is placed, bottom or
top for x axes, left or right for y axes. The "mode" option determines
how the data is interpreted, the default of null means as decimal
numbers. Use "time" for time series data, see the time series data
section.
The "color" option determines the color of the labels and ticks for
the axis (default is the grid color). For more fine-grained control
you can also set the color of the ticks separately with "tickColor"
(otherwise it's autogenerated as the base color with some
transparency).
The options "min"/"max" are the precise minimum/maximum value on the
scale. If you don't specify either of them, a value will automatically
be chosen based on the minimum/maximum data values. Note that Flot
always examines all the data values you feed to it, even if a
restriction on another axis may make some of them invisible (this
makes interactive use more st