PHP/JavaScript webapp to analyse spending habits
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

API.txt 37KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024
  1. Flot Reference
  2. --------------
  3. Consider a call to the plot function:
  4. var plot = $.plot(placeholder, data, options)
  5. The placeholder is a jQuery object or DOM element or jQuery expression
  6. that the plot will be put into. This placeholder needs to have its
  7. width and height set as explained in the README (go read that now if
  8. you haven't, it's short). The plot will modify some properties of the
  9. placeholder so it's recommended you simply pass in a div that you
  10. don't use for anything else. Make sure you check any fancy styling
  11. you apply to the div, e.g. background images have been reported to be a
  12. problem on IE 7.
  13. The format of the data is documented below, as is the available
  14. options. The "plot" object returned has some methods you can call.
  15. These are documented separately below.
  16. Note that in general Flot gives no guarantees if you change any of the
  17. objects you pass in to the plot function or get out of it since
  18. they're not necessarily deep-copied.
  19. Data Format
  20. -----------
  21. The data is an array of data series:
  22. [ series1, series2, ... ]
  23. A series can either be raw data or an object with properties. The raw
  24. data format is an array of points:
  25. [ [x1, y1], [x2, y2], ... ]
  26. E.g.
  27. [ [1, 3], [2, 14.01], [3.5, 3.14] ]
  28. Note that to simplify the internal logic in Flot both the x and y
  29. values must be numbers (even if specifying time series, see below for
  30. how to do this). This is a common problem because you might retrieve
  31. data from the database and serialize them directly to JSON without
  32. noticing the wrong type. If you're getting mysterious errors, double
  33. check that you're inputting numbers and not strings.
  34. If a null is specified as a point or if one of the coordinates is null
  35. or couldn't be converted to a number, the point is ignored when
  36. drawing. As a special case, a null value for lines is interpreted as a
  37. line segment end, i.e. the points before and after the null value are
  38. not connected.
  39. Lines and points take two coordinates. For bars, you can specify a
  40. third coordinate which is the bottom of the bar (defaults to 0).
  41. The format of a single series object is as follows:
  42. {
  43. color: color or number
  44. data: rawdata
  45. label: string
  46. lines: specific lines options
  47. bars: specific bars options
  48. points: specific points options
  49. xaxis: 1 or 2
  50. yaxis: 1 or 2
  51. clickable: boolean
  52. hoverable: boolean
  53. shadowSize: number
  54. }
  55. You don't have to specify any of them except the data, the rest are
  56. options that will get default values. Typically you'd only specify
  57. label and data, like this:
  58. {
  59. label: "y = 3",
  60. data: [[0, 3], [10, 3]]
  61. }
  62. The label is used for the legend, if you don't specify one, the series
  63. will not show up in the legend.
  64. If you don't specify color, the series will get a color from the
  65. auto-generated colors. The color is either a CSS color specification
  66. (like "rgb(255, 100, 123)") or an integer that specifies which of
  67. auto-generated colors to select, e.g. 0 will get color no. 0, etc.
  68. The latter is mostly useful if you let the user add and remove series,
  69. in which case you can hard-code the color index to prevent the colors
  70. from jumping around between the series.
  71. The "xaxis" and "yaxis" options specify which axis to use, specify 2
  72. to get the secondary axis (x axis at top or y axis to the right).
  73. E.g., you can use this to make a dual axis plot by specifying
  74. { yaxis: 2 } for one data series.
  75. "clickable" and "hoverable" can be set to false to disable
  76. interactivity for specific series if interactivity is turned on in
  77. the plot, see below.
  78. The rest of the options are all documented below as they are the same
  79. as the default options passed in via the options parameter in the plot
  80. commmand. When you specify them for a specific data series, they will
  81. override the default options for the plot for that data series.
  82. Here's a complete example of a simple data specification:
  83. [ { label: "Foo", data: [ [10, 1], [17, -14], [30, 5] ] },
  84. { label: "Bar", data: [ [11, 13], [19, 11], [30, -7] ] } ]
  85. Plot Options
  86. ------------
  87. All options are completely optional. They are documented individually
  88. below, to change them you just specify them in an object, e.g.
  89. var options = {
  90. series: {
  91. lines: { show: true },
  92. points: { show: true }
  93. }
  94. };
  95. $.plot(placeholder, data, options);
  96. Customizing the legend
  97. ======================
  98. legend: {
  99. show: boolean
  100. labelFormatter: null or (fn: string, series object -> string)
  101. labelBoxBorderColor: color
  102. noColumns: number
  103. position: "ne" or "nw" or "se" or "sw"
  104. margin: number of pixels or [x margin, y margin]
  105. backgroundColor: null or color
  106. backgroundOpacity: number between 0 and 1
  107. container: null or jQuery object/DOM element/jQuery expression
  108. }
  109. The legend is generated as a table with the data series labels and
  110. small label boxes with the color of the series. If you want to format
  111. the labels in some way, e.g. make them to links, you can pass in a
  112. function for "labelFormatter". Here's an example that makes them
  113. clickable:
  114. labelFormatter: function(label, series) {
  115. // series is the series object for the label
  116. return '<a href="#' + label + '">' + label + '</a>';
  117. }
  118. "noColumns" is the number of columns to divide the legend table into.
  119. "position" specifies the overall placement of the legend within the
  120. plot (top-right, top-left, etc.) and margin the distance to the plot
  121. edge (this can be either a number or an array of two numbers like [x,
  122. y]). "backgroundColor" and "backgroundOpacity" specifies the
  123. background. The default is a partly transparent auto-detected
  124. background.
  125. If you want the legend to appear somewhere else in the DOM, you can
  126. specify "container" as a jQuery object/expression to put the legend
  127. table into. The "position" and "margin" etc. options will then be
  128. ignored. Note that Flot will overwrite the contents of the container.
  129. Customizing the axes
  130. ====================
  131. xaxis, yaxis, x2axis, y2axis: {
  132. mode: null or "time"
  133. min: null or number
  134. max: null or number
  135. autoscaleMargin: null or number
  136. labelWidth: null or number
  137. labelHeight: null or number
  138. transform: null or fn: number -> number
  139. inverseTransform: null or fn: number -> number
  140. ticks: null or number or ticks array or (fn: range -> ticks array)
  141. tickSize: number or array
  142. minTickSize: number or array
  143. tickFormatter: (fn: number, object -> string) or string
  144. tickDecimals: null or number
  145. }
  146. All axes have the same kind of options. The "mode" option
  147. determines how the data is interpreted, the default of null means as
  148. decimal numbers. Use "time" for time series data, see the next section.
  149. The options "min"/"max" are the precise minimum/maximum value on the
  150. scale. If you don't specify either of them, a value will automatically
  151. be chosen based on the minimum/maximum data values.
  152. The "autoscaleMargin" is a bit esoteric: it's the fraction of margin
  153. that the scaling algorithm will add to avoid that the outermost points
  154. ends up on the grid border. Note that this margin is only applied
  155. when a min or max value is not explicitly set. If a margin is
  156. specified, the plot will furthermore extend the axis end-point to the
  157. nearest whole tick. The default value is "null" for the x axis and
  158. 0.02 for the y axis which seems appropriate for most cases.
  159. "labelWidth" and "labelHeight" specifies a fixed size of the tick
  160. labels in pixels. They're useful in case you need to align several
  161. plots.
  162. "transform" and "inverseTransform" are callbacks you can put in to
  163. change the way the data is drawn. You can design a function to
  164. compress or expand certain parts of the axis non-linearly, e.g.
  165. suppress weekends or compress far away points with a logarithm or some
  166. other means. When Flot draws the plot, each value is first put through
  167. the transform function. Here's an example, the x axis can be turned
  168. into a natural logarithm axis with the following code:
  169. xaxis: {
  170. transform: function (v) { return Math.log(v); },
  171. inverseTransform: function (v) { return Math.exp(v); }
  172. }
  173. Note that for finding extrema, Flot assumes that the transform
  174. function does not reorder values (monotonicity is assumed).
  175. The inverseTransform is simply the inverse of the transform function
  176. (so v == inverseTransform(transform(v)) for all relevant v). It is
  177. required for converting from canvas coordinates to data coordinates,
  178. e.g. for a mouse interaction where a certain pixel is clicked. If you
  179. don't use any interactive features of Flot, you may not need it.
  180. The rest of the options deal with the ticks.
  181. If you don't specify any ticks, a tick generator algorithm will make
  182. some for you. The algorithm has two passes. It first estimates how
  183. many ticks would be reasonable and uses this number to compute a nice
  184. round tick interval size. Then it generates the ticks.
  185. You can specify how many ticks the algorithm aims for by setting
  186. "ticks" to a number. The algorithm always tries to generate reasonably
  187. round tick values so even if you ask for three ticks, you might get
  188. five if that fits better with the rounding. If you don't want any
  189. ticks at all, set "ticks" to 0 or an empty array.
  190. Another option is to skip the rounding part and directly set the tick
  191. interval size with "tickSize". If you set it to 2, you'll get ticks at
  192. 2, 4, 6, etc. Alternatively, you can specify that you just don't want
  193. ticks at a size less than a specific tick size with "minTickSize".
  194. Note that for time series, the format is an array like [2, "month"],
  195. see the next section.
  196. If you want to completely override the tick algorithm, you can specify
  197. an array for "ticks", either like this:
  198. ticks: [0, 1.2, 2.4]
  199. Or like this where the labels are also customized:
  200. ticks: [[0, "zero"], [1.2, "one mark"], [2.4, "two marks"]]
  201. You can mix the two if you like.
  202. For extra flexibility you can specify a function as the "ticks"
  203. parameter. The function will be called with an object with the axis
  204. min and max and should return a ticks array. Here's a simplistic tick
  205. generator that spits out intervals of pi, suitable for use on the x
  206. axis for trigonometric functions:
  207. function piTickGenerator(axis) {
  208. var res = [], i = Math.floor(axis.min / Math.PI);
  209. do {
  210. var v = i * Math.PI;
  211. res.push([v, i + "\u03c0"]);
  212. ++i;
  213. } while (v < axis.max);
  214. return res;
  215. }
  216. You can control how the ticks look like with "tickDecimals", the
  217. number of decimals to display (default is auto-detected).
  218. Alternatively, for ultimate control over how ticks look like you can
  219. provide a function to "tickFormatter". The function is passed two
  220. parameters, the tick value and an "axis" object with information, and
  221. should return a string. The default formatter looks like this:
  222. function formatter(val, axis) {
  223. return val.toFixed(axis.tickDecimals);
  224. }
  225. The axis object has "min" and "max" with the range of the axis,
  226. "tickDecimals" with the number of decimals to round the value to and
  227. "tickSize" with the size of the interval between ticks as calculated
  228. by the automatic axis scaling algorithm (or specified by you). Here's
  229. an example of a custom formatter:
  230. function suffixFormatter(val, axis) {
  231. if (val > 1000000)
  232. return (val / 1000000).toFixed(axis.tickDecimals) + " MB";
  233. else if (val > 1000)
  234. return (val / 1000).toFixed(axis.tickDecimals) + " kB";
  235. else
  236. return val.toFixed(axis.tickDecimals) + " B";
  237. }
  238. Time series data
  239. ================
  240. Time series are a bit more difficult than scalar data because
  241. calendars don't follow a simple base 10 system. For many cases, Flot
  242. abstracts most of this away, but it can still be a bit difficult to
  243. get the data into Flot. So we'll first discuss the data format.
  244. The time series support in Flot is based on Javascript timestamps,
  245. i.e. everywhere a time value is expected or handed over, a Javascript
  246. timestamp number is used. This is a number, not a Date object. A
  247. Javascript timestamp is the number of milliseconds since January 1,
  248. 1970 00:00:00 UTC. This is almost the same as Unix timestamps, except it's
  249. in milliseconds, so remember to multiply by 1000!
  250. You can see a timestamp like this
  251. alert((new Date()).getTime())
  252. Normally you want the timestamps to be displayed according to a
  253. certain time zone, usually the time zone in which the data has been
  254. produced. However, Flot always displays timestamps according to UTC.
  255. It has to as the only alternative with core Javascript is to interpret
  256. the timestamps according to the time zone that the visitor is in,
  257. which means that the ticks will shift unpredictably with the time zone
  258. and daylight savings of each visitor.
  259. So given that there's no good support for custom time zones in
  260. Javascript, you'll have to take care of this server-side.
  261. The easiest way to think about it is to pretend that the data
  262. production time zone is UTC, even if it isn't. So if you have a
  263. datapoint at 2002-02-20 08:00, you can generate a timestamp for eight
  264. o'clock UTC even if it really happened eight o'clock UTC+0200.
  265. In PHP you can get an appropriate timestamp with
  266. 'strtotime("2002-02-20 UTC") * 1000', in Python with
  267. 'calendar.timegm(datetime_object.timetuple()) * 1000', in .NET with
  268. something like:
  269. public static int GetJavascriptTimestamp(System.DateTime input)
  270. {
  271. System.TimeSpan span = new System.TimeSpan(System.DateTime.Parse("1/1/1970").Ticks);
  272. System.DateTime time = input.Subtract(span);
  273. return (long)(time.Ticks / 10000);
  274. }
  275. Javascript also has some support for parsing date strings, so it is
  276. possible to generate the timestamps manually client-side.
  277. If you've already got the real UTC timestamp, it's too late to use the
  278. pretend trick described above. But you can fix up the timestamps by
  279. adding the time zone offset, e.g. for UTC+0200 you would add 2 hours
  280. to the UTC timestamp you got. Then it'll look right on the plot. Most
  281. programming environments have some means of getting the timezone
  282. offset for a specific date (note that you need to get the offset for
  283. each individual timestamp to account for daylight savings).
  284. Once you've gotten the timestamps into the data and specified "time"
  285. as the axis mode, Flot will automatically generate relevant ticks and
  286. format them. As always, you can tweak the ticks via the "ticks" option
  287. - just remember that the values should be timestamps (numbers), not
  288. Date objects.
  289. Tick generation and formatting can also be controlled separately
  290. through the following axis options:
  291. minTickSize: array
  292. timeformat: null or format string
  293. monthNames: null or array of size 12 of strings
  294. twelveHourClock: boolean
  295. Here "timeformat" is a format string to use. You might use it like
  296. this:
  297. xaxis: {
  298. mode: "time"
  299. timeformat: "%y/%m/%d"
  300. }
  301. This will result in tick labels like "2000/12/24". The following
  302. specifiers are supported
  303. %h: hours
  304. %H: hours (left-padded with a zero)
  305. %M: minutes (left-padded with a zero)
  306. %S: seconds (left-padded with a zero)
  307. %d: day of month (1-31)
  308. %m: month (1-12)
  309. %y: year (four digits)
  310. %b: month name (customizable)
  311. %p: am/pm, additionally switches %h/%H to 12 hour instead of 24
  312. %P: AM/PM (uppercase version of %p)
  313. You can customize the month names with the "monthNames" option. For
  314. instance, for Danish you might specify:
  315. monthNames: ["jan", "feb", "mar", "apr", "maj", "jun", "jul", "aug", "sep", "okt", "nov", "dec"]
  316. If you set "twelveHourClock" to true, the autogenerated timestamps
  317. will use 12 hour AM/PM timestamps instead of 24 hour.
  318. The format string and month names are used by a very simple built-in
  319. format function that takes a date object, a format string (and
  320. optionally an array of month names) and returns the formatted string.
  321. If needed, you can access it as $.plot.formatDate(date, formatstring,
  322. monthNames) or even replace it with another more advanced function
  323. from a date library if you're feeling adventurous.
  324. If everything else fails, you can control the formatting by specifying
  325. a custom tick formatter function as usual. Here's a simple example
  326. which will format December 24 as 24/12:
  327. tickFormatter: function (val, axis) {
  328. var d = new Date(val);
  329. return d.getUTCDate() + "/" + (d.getUTCMonth() + 1);
  330. }
  331. Note that for the time mode "tickSize" and "minTickSize" are a bit
  332. special in that they are arrays on the form "[value, unit]" where unit
  333. is one of "second", "minute", "hour", "day", "month" and "year". So
  334. you can specify
  335. minTickSize: [1, "month"]
  336. to get a tick interval size of at least 1 month and correspondingly,
  337. if axis.tickSize is [2, "day"] in the tick formatter, the ticks have
  338. been produced with two days in-between.
  339. Customizing the data series
  340. ===========================
  341. series: {
  342. lines, points, bars: {
  343. show: boolean
  344. lineWidth: number
  345. fill: boolean or number
  346. fillColor: null or color/gradient
  347. }
  348. points: {
  349. radius: number
  350. }
  351. bars: {
  352. barWidth: number
  353. align: "left" or "center"
  354. horizontal: boolean
  355. }
  356. lines: {
  357. steps: boolean
  358. }
  359. shadowSize: number
  360. }
  361. colors: [ color1, color2, ... ]
  362. The options inside "series: {}" are copied to each of the series. So
  363. you can specify that all series should have bars by putting it in the
  364. global options, or override it for individual series by specifying
  365. bars in a particular the series object in the array of data.
  366. The most important options are "lines", "points" and "bars" that
  367. specify whether and how lines, points and bars should be shown for
  368. each data series. In case you don't specify anything at all, Flot will
  369. default to showing lines (you can turn this off with
  370. lines: { show: false}). You can specify the various types
  371. independently of each other, and Flot will happily draw each of them
  372. in turn (this is probably only useful for lines and points), e.g.
  373. var options = {
  374. series: {
  375. lines: { show: true, fill: true, fillColor: "rgba(255, 255, 255, 0.8)" },
  376. points: { show: true, fill: false }
  377. }
  378. };
  379. "lineWidth" is the thickness of the line or outline in pixels. You can
  380. set it to 0 to prevent a line or outline from being drawn; this will
  381. also hide the shadow.
  382. "fill" is whether the shape should be filled. For lines, this produces
  383. area graphs. You can use "fillColor" to specify the color of the fill.
  384. If "fillColor" evaluates to false (default for everything except
  385. points which are filled with white), the fill color is auto-set to the
  386. color of the data series. You can adjust the opacity of the fill by
  387. setting fill to a number between 0 (fully transparent) and 1 (fully
  388. opaque).
  389. For bars, fillColor can be a gradient, see the gradient documentation
  390. below. "barWidth" is the width of the bars in units of the x axis (or
  391. the y axis if "horizontal" is true), contrary to most other measures
  392. that are specified in pixels. For instance, for time series the unit
  393. is milliseconds so 24 * 60 * 60 * 1000 produces bars with the width of
  394. a day. "align" specifies whether a bar should be left-aligned
  395. (default) or centered on top of the value it represents. When
  396. "horizontal" is on, the bars are drawn horizontally, i.e. from the y
  397. axis instead of the x axis; note that the bar end points are still
  398. defined in the same way so you'll probably want to swap the
  399. coordinates if you've been plotting vertical bars first.
  400. For lines, "steps" specifies whether two adjacent data points are
  401. connected with a straight (possibly diagonal) line or with first a
  402. horizontal and then a vertical line. Note that this transforms the
  403. data by adding extra points.
  404. "shadowSize" is the default size of shadows in pixels. Set it to 0 to
  405. remove shadows.
  406. The "colors" array specifies a default color theme to get colors for
  407. the data series from. You can specify as many colors as you like, like
  408. this:
  409. colors: ["#d18b2c", "#dba255", "#919733"]
  410. If there are more data series than colors, Flot will try to generate
  411. extra colors by lightening and darkening colors in the theme.
  412. Customizing the grid
  413. ====================
  414. grid: {
  415. show: boolean
  416. aboveData: boolean
  417. color: color
  418. backgroundColor: color/gradient or null
  419. tickColor: color
  420. labelMargin: number
  421. markings: array of markings or (fn: axes -> array of markings)
  422. borderWidth: number
  423. borderColor: color or null
  424. clickable: boolean
  425. hoverable: boolean
  426. autoHighlight: boolean
  427. mouseActiveRadius: number
  428. }
  429. The grid is the thing with the axes and a number of ticks. "color" is
  430. the color of the grid itself whereas "backgroundColor" specifies the
  431. background color inside the grid area. The default value of null means
  432. that the background is transparent. You can also set a gradient, see
  433. the gradient documentation below.
  434. You can turn off the whole grid including tick labels by setting
  435. "show" to false. "aboveData" determines whether the grid is drawn on
  436. above the data or below (below is default).
  437. "tickColor" is the color of the ticks and "labelMargin" is the spacing
  438. between tick labels and the grid. Note that you can style the tick
  439. labels with CSS, e.g. to change the color. They have class "tickLabel".
  440. "borderWidth" is the width of the border around the plot. Set it to 0
  441. to disable the border. You can also set "borderColor" if you want the
  442. border to have a different color than the grid lines.
  443. "markings" is used to draw simple lines and rectangular areas in the
  444. background of the plot. You can either specify an array of ranges on
  445. the form { xaxis: { from, to }, yaxis: { from, to } } (secondary axis
  446. coordinates with x2axis/y2axis) or with a function that returns such
  447. an array given the axes for the plot in an object as the first
  448. parameter.
  449. You can set the color of markings by specifying "color" in the ranges
  450. object. Here's an example array:
  451. markings: [ { xaxis: { from: 0, to: 2 }, yaxis: { from: 10, to: 10 }, color: "#bb0000" }, ... ]
  452. If you leave out one of the values, that value is assumed to go to the
  453. border of the plot. So for example if you only specify { xaxis: {
  454. from: 0, to: 2 } } it means an area that extends from the top to the
  455. bottom of the plot in the x range 0-2.
  456. A line is drawn if from and to are the same, e.g.
  457. markings: [ { yaxis: { from: 1, to: 1 } }, ... ]
  458. would draw a line parallel to the x axis at y = 1. You can control the
  459. line width with "lineWidth" in the range object.
  460. An example function might look like this:
  461. markings: function (axes) {
  462. var markings = [];
  463. for (var x = Math.floor(axes.xaxis.min); x < axes.xaxis.max; x += 2)
  464. markings.push({ xaxis: { from: x, to: x + 1 } });
  465. return markings;
  466. }
  467. If you set "clickable" to true, the plot will listen for click events
  468. on the plot area and fire a "plotclick" event on the placeholder with
  469. a position and a nearby data item object as parameters. The coordinates
  470. are available both in the unit of the axes (not in pixels) and in
  471. global screen coordinates.
  472. Likewise, if you set "hoverable" to true, the plot will listen for
  473. mouse move events on the plot area and fire a "plothover" event with
  474. the same parameters as the "plotclick" event. If "autoHighlight" is
  475. true (the default), nearby data items are highlighted automatically.
  476. If needed, you can disable highlighting and control it yourself with
  477. the highlight/unhighlight plot methods described elsewhere.
  478. You can use "plotclick" and "plothover" events like this:
  479. $.plot($("#placeholder"), [ d ], { grid: { clickable: true } });
  480. $("#placeholder").bind("plotclick", function (event, pos, item) {
  481. alert("You clicked at " + pos.x + ", " + pos.y);
  482. // secondary axis coordinates if present are in pos.x2, pos.y2,
  483. // if you need global screen coordinates, they are pos.pageX, pos.pageY
  484. if (item) {
  485. highlight(item.series, item.datapoint);
  486. alert("You clicked a point!");
  487. }
  488. });
  489. The item object in this example is either null or a nearby object on the form:
  490. item: {
  491. datapoint: the point, e.g. [0, 2]
  492. dataIndex: the index of the point in the data array
  493. series: the series object
  494. seriesIndex: the index of the series
  495. pageX, pageY: the global screen coordinates of the point
  496. }
  497. For instance, if you have specified the data like this
  498. $.plot($("#placeholder"), [ { label: "Foo", data: [[0, 10], [7, 3]] } ], ...);
  499. and the mouse is near the point (7, 3), "datapoint" is [7, 3],
  500. "dataIndex" will be 1, "series" is a normalized series object with
  501. among other things the "Foo" label in series.label and the color in
  502. series.color, and "seriesIndex" is 0. Note that plugins and options
  503. that transform the data can shift the indexes from what you specified
  504. in the original data array.
  505. If you use the above events to update some other information and want
  506. to clear out that info in case the mouse goes away, you'll probably
  507. also need to listen to "mouseout" events on the placeholder div.
  508. "mouseActiveRadius" specifies how far the mouse can be from an item
  509. and still activate it. If there are two or more points within this
  510. radius, Flot chooses the closest item. For bars, the top-most bar
  511. (from the latest specified data series) is chosen.
  512. If you want to disable interactivity for a specific data series, you
  513. can set "hoverable" and "clickable" to false in the options for that
  514. series, like this { data: [...], label: "Foo", clickable: false }.
  515. Specifying gradients
  516. ====================
  517. A gradient is specified like this:
  518. { colors: [ color1, color2, ... ] }
  519. For instance, you might specify a background on the grid going from
  520. black to gray like this:
  521. grid: {
  522. backgroundColor: { colors: ["#000", "#999"] }
  523. }
  524. For the series you can specify the gradient as an object that
  525. specifies the scaling of the brightness and the opacity of the series
  526. color, e.g.
  527. { colors: [{ opacity: 0.8 }, { brightness: 0.6, opacity: 0.8 } ] }
  528. where the first color simply has its alpha scaled, whereas the second
  529. is also darkened. For instance, for bars the following makes the bars
  530. gradually disappear, without outline:
  531. bars: {
  532. show: true,
  533. lineWidth: 0,
  534. fill: true,
  535. fillColor: { colors: [ { opacity: 0.8 }, { opacity: 0.1 } ] }
  536. }
  537. Flot currently only supports vertical gradients drawn from top to
  538. bottom because that's what works with IE.
  539. Plot Methods
  540. ------------
  541. The Plot object returned from the plot function has some methods you
  542. can call:
  543. - highlight(series, datapoint)
  544. Highlight a specific datapoint in the data series. You can either
  545. specify the actual objects, e.g. if you got them from a
  546. "plotclick" event, or you can specify the indices, e.g.
  547. highlight(1, 3) to highlight the fourth point in the second series
  548. (remember, zero-based indexing).
  549. - unhighlight(series, datapoint) or unhighlight()
  550. Remove the highlighting of the point, same parameters as
  551. highlight.
  552. If you call unhighlight with no parameters, e.g. as
  553. plot.unhighlight(), all current highlights are removed.
  554. - setData(data)
  555. You can use this to reset the data used. Note that axis scaling,
  556. ticks, legend etc. will not be recomputed (use setupGrid() to do
  557. that). You'll probably want to call draw() afterwards.
  558. You can use this function to speed up redrawing a small plot if
  559. you know that the axes won't change. Put in the new data with
  560. setData(newdata), call draw(), and you're good to go. Note that
  561. for large datasets, almost all the time is consumed in draw()
  562. plotting the data so in this case don't bother.
  563. - setupGrid()
  564. Recalculate and set axis scaling, ticks, legend etc.
  565. Note that because of the drawing model of the canvas, this
  566. function will immediately redraw (actually reinsert in the DOM)
  567. the labels and the legend, but not the actual tick lines because
  568. they're drawn on the canvas. You need to call draw() to get the
  569. canvas redrawn.
  570. - draw()
  571. Redraws the plot canvas.
  572. - triggerRedrawOverlay()
  573. Schedules an update of an overlay canvas used for drawing
  574. interactive things like a selection and point highlights. This
  575. is mostly useful for writing plugins. The redraw doesn't happen
  576. immediately, instead a timer is set to catch multiple successive
  577. redraws (e.g. from a mousemove).
  578. - width()/height()
  579. Gets the width and height of the plotting area inside the grid.
  580. This is smaller than the canvas or placeholder dimensions as some
  581. extra space is needed (e.g. for labels).
  582. - offset()
  583. Returns the offset of the plotting area inside the grid relative
  584. to the document, useful for instance for calculating mouse
  585. positions (event.pageX/Y minus this offset is the pixel position
  586. inside the plot).
  587. - pointOffset({ x: xpos, y: ypos })
  588. Returns the calculated offset of the data point at (x, y) in data
  589. space within the placeholder div. If you are working with dual axes, you
  590. can specify the x and y axis references, e.g.
  591. o = pointOffset({ x: xpos, y: ypos, xaxis: 2, yaxis: 2 })
  592. // o.left and o.top now contains the offset within the div
  593. There are also some members that let you peek inside the internal
  594. workings of Flot which is useful in some cases. Note that if you change
  595. something in the objects returned, you're changing the objects used by
  596. Flot to keep track of its state, so be careful.
  597. - getData()
  598. Returns an array of the data series currently used in normalized
  599. form with missing settings filled in according to the global
  600. options. So for instance to find out what color Flot has assigned
  601. to the data series, you could do this:
  602. var series = plot.getData();
  603. for (var i = 0; i < series.length; ++i)
  604. alert(series[i].color);
  605. A notable other interesting field besides color is datapoints
  606. which has a field "points" with the normalized data points in a
  607. flat array (the field "pointsize" is the increment in the flat
  608. array to get to the next point so for a dataset consisting only of
  609. (x,y) pairs it would be 2).
  610. - getAxes()
  611. Gets an object with the axes settings as { xaxis, yaxis, x2axis,
  612. y2axis }.
  613. Various things are stuffed inside an axis object, e.g. you could
  614. use getAxes().xaxis.ticks to find out what the ticks are for the
  615. xaxis. Two other useful attributes are p2c and c2p, functions for
  616. transforming from data point space to the canvas plot space and
  617. back. Both returns values that are offset with the plot offset.
  618. - getPlaceholder()
  619. Returns placeholder that the plot was put into. This can be useful
  620. for plugins for adding DOM elements or firing events.
  621. - getCanvas()
  622. Returns the canvas used for drawing in case you need to hack on it
  623. yourself. You'll probably need to get the plot offset too.
  624. - getPlotOffset()
  625. Gets the offset that the grid has within the canvas as an object
  626. with distances from the canvas edges as "left", "right", "top",
  627. "bottom". I.e., if you draw a circle on the canvas with the center
  628. placed at (left, top), its center will be at the top-most, left
  629. corner of the grid.
  630. - getOptions()
  631. Gets the options for the plot, in a normalized format with default
  632. values filled in.
  633. Hooks
  634. =====
  635. In addition to the public methods, the Plot object also has some hooks
  636. that can be used to modify the plotting process. You can install a
  637. callback function at various points in the process, the function then
  638. gets access to the internal data structures in Flot.
  639. Here's an overview of the phases Flot goes through:
  640. 1. Plugin initialization, parsing options
  641. 2. Constructing the canvases used for drawing
  642. 3. Set data: parsing data specification, calculating colors,
  643. copying raw data points into internal format,
  644. normalizing them, finding max/min for axis auto-scaling
  645. 4. Grid setup: calculating axis spacing, ticks, inserting tick
  646. labels, the legend
  647. 5. Draw: drawing the grid, drawing each of the series in turn
  648. 6. Setting up event handling for interactive features
  649. 7. Responding to events, if any
  650. Each hook is simply a function which is put in the appropriate array.
  651. You can add them through the "hooks" option, and they are also available
  652. after the plot is constructed as the "hooks" attribute on the returned
  653. plot object, e.g.
  654. // define a simple draw hook
  655. function hellohook(plot, canvascontext) { alert("hello!"); };
  656. // pass it in, in an array since we might want to specify several
  657. var plot = $.plot(placeholder, data, { hooks: { draw: [hellohook] } });
  658. // we can now find it again in plot.hooks.draw[0] unless a plugin
  659. // has added other hooks
  660. The available hooks are described below. All hook callbacks get the
  661. plot object as first parameter. You can find some examples of defined
  662. hooks in the plugins bundled with Flot.
  663. - processOptions [phase 1]
  664. function(plot, options)
  665. Called after Flot has parsed and merged options. Useful in the
  666. instance where customizations beyond simple merging of default
  667. values is needed. A plugin might use it to detect that it has been
  668. enabled and then turn on or off other options.
  669. - processRawData [phase 3]
  670. function(plot, series, data, datapoints)
  671. Called before Flot copies and normalizes the raw data for the given
  672. series. If the function fills in datapoints.points with normalized
  673. points and sets datapoints.pointsize to the size of the points,
  674. Flot will skip the copying/normalization step for this series.
  675. In any case, you might be interested in setting datapoints.format,
  676. an array of objects for specifying how a point is normalized and
  677. how it interferes with axis scaling.
  678. The default format array for points is something along the lines of:
  679. [
  680. { x: true, number: true, required: true },
  681. { y: true, number: true, required: true }
  682. ]
  683. The first object means that for the first coordinate it should be
  684. taken into account when scaling the x axis, that it must be a
  685. number, and that it is required - so if it is null or cannot be
  686. converted to a number, the whole point will be zeroed out with
  687. nulls. Beyond these you can also specify "defaultValue", a value to
  688. use if the coordinate is null. This is for instance handy for bars
  689. where one can omit the third coordinate (the bottom of the bar)
  690. which then defaults to 0.
  691. - processDatapoints [phase 3]
  692. function(plot, series, datapoints)
  693. Called after normalization of the given series but before finding
  694. min/max of the data points. This hook is useful for implementing data
  695. transformations. "datapoints" contains the normalized data points in
  696. a flat array as datapoints.points with the size of a single point
  697. given in datapoints.pointsize. Here's a simple transform that
  698. multiplies all y coordinates by 2:
  699. function multiply(plot, series, datapoints) {
  700. var points = datapoints.points, ps = datapoints.pointsize;
  701. for (var i = 0; i < points.length; i += ps)
  702. points[i + 1] *= 2;
  703. }
  704. Note that you must leave datapoints in a good condition as Flot
  705. doesn't check it or do any normalization on it afterwards.
  706. - draw [phase 5]
  707. function(plot, canvascontext)
  708. Hook for drawing on the canvas. Called after the grid is drawn
  709. (unless it's disabled) and the series have been plotted (in case
  710. any points, lines or bars have been turned on). For examples of how
  711. to draw things, look at the source code.
  712. - bindEvents [phase 6]
  713. function(plot, eventHolder)
  714. Called after Flot has setup its event handlers. Should set any
  715. necessary event handlers on eventHolder, a jQuery object with the
  716. canvas, e.g.
  717. function (plot, eventHolder) {
  718. eventHolder.mousedown(function (e) {
  719. alert("You pressed the mouse at " + e.pageX + " " + e.pageY);
  720. });
  721. }
  722. Interesting events include click, mousemove, mouseup/down. You can
  723. use all jQuery events. Usually, the event handlers will update the
  724. state by drawing something (add a drawOverlay hook and call
  725. triggerRedrawOverlay) or firing an externally visible event for
  726. user code. See the crosshair plugin for an example.
  727. Currently, eventHolder actually contains both the static canvas
  728. used for the plot itself and the overlay canvas used for
  729. interactive features because some versions of IE get the stacking
  730. order wrong. The hook only gets one event, though (either for the
  731. overlay or for the static canvas).
  732. - drawOverlay [phase 7]
  733. function (plot, canvascontext)
  734. The drawOverlay hook is used for interactive things that need a
  735. canvas to draw on. The model currently used by Flot works the way
  736. that an extra overlay canvas is positioned on top of the static
  737. canvas. This overlay is cleared and then completely redrawn
  738. whenever something interesting happens. This hook is called when
  739. the overlay canvas is to be redrawn.
  740. "canvascontext" is the 2D context of the overlay canvas. You can
  741. use this to draw things. You'll most likely need some of the
  742. metrics computed by Flot, e.g. plot.width()/plot.height(). See the
  743. crosshair plugin for an example.
  744. Plugins
  745. -------
  746. Plugins extend the functionality of Flot. To use a plugin, simply
  747. include its Javascript file after Flot in the HTML page.
  748. If you're worried about download size/latency, you can concatenate all
  749. the plugins you use, and Flot itself for that matter, into one big file
  750. (make sure you get the order right), then optionally run it through a
  751. Javascript minifier such as YUI Compressor.
  752. Here's a brief explanation of how the plugin plumbings work:
  753. Each plugin registers itself in the global array $.plot.plugins. When
  754. you make a new plot object with $.plot, Flot goes through this array
  755. calling the "init" function of each plugin and merging default options
  756. from its "option" attribute. The init function gets a reference to the
  757. plot object created and uses this to register hooks and add new public
  758. methods if needed.
  759. See the PLUGINS.txt file for details on how to write a plugin. As the
  760. above description hints, it's actually pretty easy.