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