1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024 |
- 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 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 bars, you can specify a
- third coordinate which is the bottom of the 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: 1 or 2
- yaxis: 1 or 2
- 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, specify 2
- to get the secondary axis (x axis at top or y axis to the right).
- E.g., you can use this to make a dual axis plot by specifying
- { yaxis: 2 } for one data series.
-
- "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, x2axis, y2axis: {
- mode: null or "time"
- min: null or number
- max: null or number
- autoscaleMargin: null or number
-
- labelWidth: null or number
- labelHeight: 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
- }
-
- All axes have the same kind of options. 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 next section.
-
- 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.
-
- The "autoscaleMargin" is a bit esoteric: it's the fraction of margin
- that the scaling algorithm will add to avoid that the outermost points
- ends up on the grid border. Note that this margin is only applied
- when a min or max value is not explicitly set. If a margin is
- specified, the plot will furthermore extend the axis end-point to the
- nearest whole tick. The default value is "null" for the x axis and
- 0.02 for the y axis which seems appropriate for most cases.
-
- "labelWidth" and "labelHeight" specifies a fixed size of the tick
- labels in pixels. They're useful in case you need to align several
- plots.
-
- "transform" and "inverseTransform" are callbacks you can put in to
- change the way the data is drawn. You can design a function to
- compress or expand certain parts of the axis non-linearly, e.g.
- suppress weekends or compress far away points with a logarithm or some
- other means. When Flot draws the plot, each value is first put through
- the transform function. Here's an example, the x axis can be turned
- into a natural logarithm axis with the following code:
-
- xaxis: {
- transform: function (v) { return Math.log(v); },
- inverseTransform: function (v) { return Math.exp(v); }
- }
-
- Note that for finding extrema, Flot assumes that the transform
- function does not reorder values (monotonicity is assumed).
-
- The inverseTransform is simply the inverse of the transform function
- (so v == inverseTransform(transform(v)) for all relevant v). It is
- required for converting from canvas coordinates to data coordinates,
- e.g. for a mouse interaction where a certain pixel is clicked. If you
- don't use any interactive features of Flot, you may not need it.
-
-
- The rest of the options deal with the ticks.
-
- If you don't specify any ticks, a tick generator algorithm will make
- some for you. The algorithm has two passes. It first estimates how
- many ticks would be reasonable and uses this number to compute a nice
- round tick interval size. Then it generates the ticks.
-
- You can specify how many ticks the algorithm aims for by setting
- "ticks" to a number. The algorithm always tries to generate reasonably
- round tick values so even if you ask for three ticks, you might get
- five if that fits better with the rounding. If you don't want any
- ticks at all, set "ticks" to 0 or an empty array.
-
- Another option is to skip the rounding part and directly set the tick
- interval size with "tickSize". If you set it to 2, you'll get ticks at
- 2, 4, 6, etc. Alternatively, you can specify that you just don't want
- ticks at a size less than a specific tick size with "minTickSize".
- Note that for time series, the format is an array like [2, "month"],
- see the next section.
-
- If you want to completely override the tick algorithm, you can specify
- an array for "ticks", either like this:
-
- ticks: [0, 1.2, 2.4]
-
- Or like this where the labels are also customized:
-
- ticks: [[0, "zero"], [1.2, "one mark"], [2.4, "two marks"]]
-
- You can mix the two if you like.
-
- For extra flexibility you can specify a function as the "ticks"
- parameter. The function will be called with an object with the axis
- min and max and should return a ticks array. Here's a simplistic tick
- generator that spits out intervals of pi, suitable for use on the x
- axis for trigonometric functions:
-
- function piTickGenerator(axis) {
- var res = [], i = Math.floor(axis.min / Math.PI);
- do {
- var v = i * Math.PI;
- res.push([v, i + "\u03c0"]);
- ++i;
- } while (v < axis.max);
-
- return res;
- }
-
-
- You can control how the ticks look like with "tickDecimals", the
- number of decimals to display (default is auto-detected).
-
- Alternatively, for ultimate control over how ticks look like you can
- provide a function to "tickFormatter". The function is passed two
- parameters, the tick value and an "axis" object with information, and
- should return a string. The default formatter looks like this:
-
- function formatter(val, axis) {
- return val.toFixed(axis.tickDecimals);
- }
-
- The axis object has "min" and "max" with the range of the axis,
- "tickDecimals" with the number of decimals to round the value to and
- "tickSize" with the size of the interval between ticks as calculated
- by the automatic axis scaling algorithm (or specified by you). Here's
- an example of a custom formatter:
-
- function suffixFormatter(val, axis) {
- if (val > 1000000)
- return (val / 1000000).toFixed(axis.tickDecimals) + " MB";
- else if (val > 1000)
- return (val / 1000).toFixed(axis.tickDecimals) + " kB";
- else
- return val.toFixed(axis.tickDecimals) + " B";
- }
-
- Time series data
- ================
-
- Time series are a bit more difficult than scalar data because
- calendars don't follow a simple base 10 system. For many cases, Flot
- abstracts most of this away, but it can still be a bit difficult to
- get the data into Flot. So we'll first discuss the data format.
-
- The time series support in Flot is based on Javascript timestamps,
- i.e. everywhere a time value is expected or handed over, a Javascript
- timestamp number is used. This is a number, not a Date object. A
- Javascript timestamp is the number of milliseconds since January 1,
- 1970 00:00:00 UTC. This is almost the same as Unix timestamps, except it's
- in milliseconds, so remember to multiply by 1000!
-
- You can see a timestamp like this
-
- alert((new Date()).getTime())
-
- Normally you want the timestamps to be displayed according to a
- certain time zone, usually the time zone in which the data has been
- produced. However, Flot always displays timestamps according to UTC.
- It has to as the only alternative with core Javascript is to interpret
- the timestamps according to the time zone that the visitor is in,
- which means that the ticks will shift unpredictably with the time zone
- and daylight savings of each visitor.
-
- So given that there's no good support for custom time zones in
- Javascript, you'll have to take care of this server-side.
-
- The easiest way to think about it is to pretend that the data
- production time zone is UTC, even if it isn't. So if you have a
- datapoint at 2002-02-20 08:00, you can generate a timestamp for eight
- o'clock UTC even if it really happened eight o'clock UTC+0200.
-
- In PHP you can get an appropriate timestamp with
- 'strtotime("2002-02-20 UTC") * 1000', in Python with
- 'calendar.timegm(datetime_object.timetuple()) * 1000', in .NET with
- something like:
-
- public static int GetJavascriptTimestamp(System.DateTime input)
- {
- System.TimeSpan span = new System.TimeSpan(System.DateTime.Parse("1/1/1970").Ticks);
- System.DateTime time = input.Subtract(span);
- return (long)(time.Ticks / 10000);
- }
-
- Javascript also has some support for parsing date strings, so it is
- possible to generate the timestamps manually client-side.
-
- If you've already got the real UTC timestamp, it's too late to use the
- pretend trick described above. But you can fix up the timestamps by
- adding the time zone offset, e.g. for UTC+0200 you would add 2 hours
- to the UTC timestamp you got. Then it'll look right on the plot. Most
- programming environments have some means of getting the timezone
- offset for a specific date (note that you need to get the offset for
- each individual timestamp to account for daylight savings).
-
- Once you've gotten the timestamps into the data and specified "time"
- as the axis mode, Flot will automatically generate relevant ticks and
- format them. As always, you can tweak the ticks via the "ticks" option
- - just remember that the values should be timestamps (numbers), not
- Date objects.
-
- Tick generation and formatting can also be controlled separately
- through the following axis options:
-
- minTickSize: array
- timeformat: null or format string
- monthNames: null or array of size 12 of strings
- twelveHourClock: boolean
-
- Here "timeformat" is a format string to use. You might use it like
- this:
-
- xaxis: {
- mode: "time"
- timeformat: "%y/%m/%d"
- }
-
- This will result in tick labels like "2000/12/24". The following
- specifiers are supported
-
- %h: hours
- %H: hours (left-padded with a zero)
- %M: minutes (left-padded with a zero)
- %S: seconds (left-padded with a zero)
- %d: day of month (1-31)
- %m: month (1-12)
- %y: year (four digits)
- %b: month name (customizable)
- %p: am/pm, additionally switches %h/%H to 12 hour instead of 24
- %P: AM/PM (uppercase version of %p)
-
- You can customize the month names with the "monthNames" option. For
- instance, for Danish you might specify:
-
- monthNames: ["jan", "feb", "mar", "apr", "maj", "jun", "jul", "aug", "sep", "okt", "nov", "dec"]
-
- If you set "twelveHourClock" to true, the autogenerated timestamps
- will use 12 hour AM/PM timestamps instead of 24 hour.
-
- The format string and month names are used by a very simple built-in
- format function that takes a date object, a format string (and
- optionally an array of month names) and returns the formatted string.
- If needed, you can access it as $.plot.formatDate(date, formatstring,
- monthNames) or even replace it with another more advanced function
- from a date library if you're feeling adventurous.
-
- If everything else fails, you can control the formatting by specifying
- a custom tick formatter function as usual. Here's a simple example
- which will format December 24 as 24/12:
-
- tickFormatter: function (val, axis) {
- var d = new Date(val);
- return d.getUTCDate() + "/" + (d.getUTCMonth() + 1);
- }
-
- Note that for the time mode "tickSize" and "minTickSize" are a bit
- special in that they are arrays on the form "[value, unit]" where unit
- is one of "second", "minute", "hour", "day", "month" and "year". So
- you can specify
-
- minTickSize: [1, "month"]
-
- to get a tick interval size of at least 1 month and correspondingly,
- if axis.tickSize is [2, "day"] in the tick formatter, the ticks have
- been produced with two days in-between.
-
-
-
- Customizing the data series
- ===========================
-
- series: {
- lines, points, bars: {
- show: boolean
- lineWidth: number
- fill: boolean or number
- fillColor: null or color/gradient
- }
-
- points: {
- radius: number
- }
-
- bars: {
- barWidth: number
- align: "left" or "center"
- horizontal: boolean
- }
-
- lines: {
- steps: boolean
- }
-
- shadowSize: number
- }
-
- colors: [ color1, color2, ... ]
-
- The options inside "series: {}" are copied to each of the series. So
- you can specify that all series should have bars by putting it in the
- global options, or override it for individual series by specifying
- bars in a particular the series object in the array of data.
-
- The most important options are "lines", "points" and "bars" that
- specify whether and how lines, points and bars should be shown for
- each data series. In case you don't specify anything at all, Flot will
- default to showing lines (you can turn this off with
- lines: { show: false}). You can specify the various types
- independently of each other, and Flot will happily draw each of them
- in turn (this is probably only useful for lines and points), e.g.
-
- var options = {
- series: {
- lines: { show: true, fill: true, fillColor: "rgba(255, 255, 255, 0.8)" },
- points: { show: true, fill: false }
- }
- };
-
- "lineWidth" is the thickness of the line or outline in pixels. You can
- set it to 0 to prevent a line or outline from being drawn; this will
- also hide the shadow.
-
- "fill" is whether the shape should be filled. For lines, this produces
- area graphs. You can use "fillColor" to specify the color of the fill.
- If "fillColor" evaluates to false (default for everything except
- points which are filled with white), the fill color is auto-set to the
- color of the data series. You can adjust the opacity of the fill by
- setting fill to a number between 0 (fully transparent) and 1 (fully
- opaque).
-
- For bars, fillColor can be a gradient, see the gradient documentation
- below. "barWidth" is the width of the bars in units of the x axis (or
- the y axis if "horizontal" is true), contrary to most other measures
- that are specified in pixels. For instance, for time series the unit
- is milliseconds so 24 * 60 * 60 * 1000 produces bars with the width of
- a day. "align" specifies whether a bar should be left-aligned
- (default) or centered on top of the value it represents. When
- "horizontal" is on, the bars are drawn horizontally, i.e. from the y
- axis instead of the x axis; note that the bar end points are still
- defined in the same way so you'll probably want to swap the
- coordinates if you've been plotting vertical bars first.
-
- For lines, "steps" specifies whether two adjacent data points are
- connected with a straight (possibly diagonal) line or with first a
- horizontal and then a vertical line. Note that this transforms the
- data by adding extra points.
-
- "shadowSize" is the default size of shadows in pixels. Set it to 0 to
- remove shadows.
-
- The "colors" array specifies a default color theme to get colors for
- the data series from. You can specify as many colors as you like, like
- this:
-
- colors: ["#d18b2c", "#dba255", "#919733"]
-
- If there are more data series than colors, Flot will try to generate
- extra colors by lightening and darkening colors in the theme.
-
-
- Customizing the grid
- ====================
-
- grid: {
- show: boolean
- aboveData: boolean
- color: color
- backgroundColor: color/gradient or null
- tickColor: color
- labelMargin: number
- markings: array of markings or (fn: axes -> array of markings)
- borderWidth: number
- borderColor: color or null
- clickable: boolean
- hoverable: boolean
- autoHighlight: boolean
- mouseActiveRadius: number
- }
-
- The grid is the thing with the axes and a number of ticks. "color" is
- the color of the grid itself whereas "backgroundColor" specifies the
- background color inside the grid area. The default value of null means
- that the background is transparent. You can also set a gradient, see
- the gradient documentation below.
-
- You can turn off the whole grid including tick labels by setting
- "show" to false. "aboveData" determines whether the grid is drawn on
- above the data or below (below is default).
-
- "tickColor" is the color of the ticks and "labelMargin" is the spacing
- between tick labels and the grid. Note that you can style the tick
- labels with CSS, e.g. to change the color. They have class "tickLabel".
- "borderWidth" is the width of the border around the plot. Set it to 0
- to disable the border. You can also set "borderColor" if you want the
- border to have a different color than the grid lines.
-
- "markings" is used to draw simple lines and rectangular areas in the
- background of the plot. You can either specify an array of ranges on
- the form { xaxis: { from, to }, yaxis: { from, to } } (secondary axis
- coordinates with x2axis/y2axis) or with a function that returns such
- an array given the axes for the plot in an object as the first
- parameter.
-
- You can set the color of markings by specifying "color" in the ranges
- object. Here's an example array:
-
- markings: [ { xaxis: { from: 0, to: 2 }, yaxis: { from: 10, to: 10 }, color: "#bb0000" }, ... ]
-
- If you leave out one of the values, that value is assumed to go to the
- border of the plot. So for example if you only specify { xaxis: {
- from: 0, to: 2 } } it means an area that extends from the top to the
- bottom of the plot in the x range 0-2.
-
- A line is drawn if from and to are the same, e.g.
-
- markings: [ { yaxis: { from: 1, to: 1 } }, ... ]
-
- would draw a line parallel to the x axis at y = 1. You can control the
- line width with "lineWidth" in the range object.
-
- An example function might look like this:
-
- markings: function (axes) {
- var markings = [];
- for (var x = Math.floor(axes.xaxis.min); x < axes.xaxis.max; x += 2)
- markings.push({ xaxis: { from: x, to: x + 1 } });
- return markings;
- }
-
-
- If you set "clickable" to true, the plot will listen for click events
- on the plot area and fire a "plotclick" event on the placeholder with
- a position and a nearby data item object as parameters. The coordinates
- are available both in the unit of the axes (not in pixels) and in
- global screen coordinates.
-
- Likewise, if you set "hoverable" to true, the plot will listen for
- mouse move events on the plot area and fire a "plothover" event with
- the same parameters as the "plotclick" event. If "autoHighlight" is
- true (the default), nearby data items are highlighted automatically.
- If needed, you can disable highlighting and control it yourself with
- the highlight/unhighlight plot methods described elsewhere.
-
- You can use "plotclick" and "plothover" events like this:
-
- $.plot($("#placeholder"), [ d ], { grid: { clickable: true } });
-
- $("#placeholder").bind("plotclick", function (event, pos, item) {
- alert("You clicked at " + pos.x + ", " + pos.y);
- // secondary axis coordinates if present are in pos.x2, pos.y2,
- // if you need global screen coordinates, they are pos.pageX, pos.pageY
-
- if (item) {
- highlight(item.series, item.datapoint);
- alert("You clicked a point!");
- }
- });
-
- The item object in this example is either null or a nearby object on the form:
-
- item: {
- datapoint: the point, e.g. [0, 2]
- dataIndex: the index of the point in the data array
- series: the series object
- seriesIndex: the index of the series
- pageX, pageY: the global screen coordinates of the point
- }
-
- For instance, if you have specified the data like this
-
- $.plot($("#placeholder"), [ { label: "Foo", data: [[0, 10], [7, 3]] } ], ...);
-
- and the mouse is near the point (7, 3), "datapoint" is [7, 3],
- "dataIndex" will be 1, "series" is a normalized series object with
- among other things the "Foo" label in series.label and the color in
- series.color, and "seriesIndex" is 0. Note that plugins and options
- that transform the data can shift the indexes from what you specified
- in the original data array.
-
- If you use the above events to update some other information and want
- to clear out that info in case the mouse goes away, you'll probably
- also need to listen to "mouseout" events on the placeholder div.
-
- "mouseActiveRadius" specifies how far the mouse can be from an item
- and still activate it. If there are two or more points within this
- radius, Flot chooses the closest item. For bars, the top-most bar
- (from the latest specified data series) is chosen.
-
- If you want to disable interactivity for a specific data series, you
- can set "hoverable" and "clickable" to false in the options for that
- series, like this { data: [...], label: "Foo", clickable: false }.
-
-
- Specifying gradients
- ====================
-
- A gradient is specified like this:
-
- { colors: [ color1, color2, ... ] }
-
- For instance, you might specify a background on the grid going from
- black to gray like this:
-
- grid: {
- backgroundColor: { colors: ["#000", "#999"] }
- }
-
- For the series you can specify the gradient as an object that
- specifies the scaling of the brightness and the opacity of the series
- color, e.g.
-
- { colors: [{ opacity: 0.8 }, { brightness: 0.6, opacity: 0.8 } ] }
-
- where the first color simply has its alpha scaled, whereas the second
- is also darkened. For instance, for bars the following makes the bars
- gradually disappear, without outline:
-
- bars: {
- show: true,
- lineWidth: 0,
- fill: true,
- fillColor: { colors: [ { opacity: 0.8 }, { opacity: 0.1 } ] }
- }
-
- Flot currently only supports vertical gradients drawn from top to
- bottom because that's what works with IE.
-
-
- Plot Methods
- ------------
-
- The Plot object returned from the plot function has some methods you
- can call:
-
- - highlight(series, datapoint)
-
- Highlight a specific datapoint in the data series. You can either
- specify the actual objects, e.g. if you got them from a
- "plotclick" event, or you can specify the indices, e.g.
- highlight(1, 3) to highlight the fourth point in the second series
- (remember, zero-based indexing).
-
-
- - unhighlight(series, datapoint) or unhighlight()
-
- Remove the highlighting of the point, same parameters as
- highlight.
-
- If you call unhighlight with no parameters, e.g. as
- plot.unhighlight(), all current highlights are removed.
-
-
- - setData(data)
-
- You can use this to reset the data used. Note that axis scaling,
- ticks, legend etc. will not be recomputed (use setupGrid() to do
- that). You'll probably want to call draw() afterwards.
-
- You can use this function to speed up redrawing a small plot if
- you know that the axes won't change. Put in the new data with
- setData(newdata), call draw(), and you're good to go. Note that
- for large datasets, almost all the time is consumed in draw()
- plotting the data so in this case don't bother.
-
-
- - setupGrid()
-
- Recalculate and set axis scaling, ticks, legend etc.
-
- Note that because of the drawing model of the canvas, this
- function will immediately redraw (actually reinsert in the DOM)
- the labels and the legend, but not the actual tick lines because
- they're drawn on the canvas. You need to call draw() to get the
- canvas redrawn.
-
- - draw()
-
- Redraws the plot canvas.
-
- - triggerRedrawOverlay()
-
- Schedules an update of an overlay canvas used for drawing
- interactive things like a selection and point highlights. This
- is mostly useful for writing plugins. The redraw doesn't happen
- immediately, instead a timer is set to catch multiple successive
- redraws (e.g. from a mousemove).
-
- - width()/height()
-
- Gets the width and height of the plotting area inside the grid.
- This is smaller than the canvas or placeholder dimensions as some
- extra space is needed (e.g. for labels).
-
- - offset()
-
- Returns the offset of the plotting area inside the grid relative
- to the document, useful for instance for calculating mouse
- positions (event.pageX/Y minus this offset is the pixel position
- inside the plot).
-
- - pointOffset({ x: xpos, y: ypos })
-
- Returns the calculated offset of the data point at (x, y) in data
- space within the placeholder div. If you are working with dual axes, you
- can specify the x and y axis references, e.g.
-
- o = pointOffset({ x: xpos, y: ypos, xaxis: 2, yaxis: 2 })
- // o.left and o.top now contains the offset within the div
-
-
- There are also some members that let you peek inside the internal
- workings of Flot which is useful in some cases. Note that if you change
- something in the objects returned, you're changing the objects used by
- Flot to keep track of its state, so be careful.
-
- - getData()
-
- Returns an array of the data series currently used in normalized
- form with missing settings filled in according to the global
- options. So for instance to find out what color Flot has assigned
- to the data series, you could do this:
-
- var series = plot.getData();
- for (var i = 0; i < series.length; ++i)
- alert(series[i].color);
-
- A notable other interesting field besides color is datapoints
- which has a field "points" with the normalized data points in a
- flat array (the field "pointsize" is the increment in the flat
- array to get to the next point so for a dataset consisting only of
- (x,y) pairs it would be 2).
-
- - getAxes()
-
- Gets an object with the axes settings as { xaxis, yaxis, x2axis,
- y2axis }.
-
- Various things are stuffed inside an axis object, e.g. you could
- use getAxes().xaxis.ticks to find out what the ticks are for the
- xaxis. Two other useful attributes are p2c and c2p, functions for
- transforming from data point space to the canvas plot space and
- back. Both returns values that are offset with the plot offset.
-
- - getPlaceholder()
-
- Returns placeholder that the plot was put into. This can be useful
- for plugins for adding DOM elements or firing events.
-
- - getCanvas()
-
- Returns the canvas used for drawing in case you need to hack on it
- yourself. You'll probably need to get the plot offset too.
-
- - getPlotOffset()
-
- Gets the offset that the grid has within the canvas as an object
- with distances from the canvas edges as "left", "right", "top",
- "bottom". I.e., if you draw a circle on the canvas with the center
- placed at (left, top), its center will be at the top-most, left
- corner of the grid.
-
- - getOptions()
-
- Gets the options for the plot, in a normalized format with default
- values filled in.
-
-
- Hooks
- =====
-
- In addition to the public methods, the Plot object also has some hooks
- that can be used to modify the plotting process. You can install a
- callback function at various points in the process, the function then
- gets access to the internal data structures in Flot.
-
- Here's an overview of the phases Flot goes through:
-
- 1. Plugin initialization, parsing options
-
- 2. Constructing the canvases used for drawing
-
- 3. Set data: parsing data specification, calculating colors,
- copying raw data points into internal format,
- normalizing them, finding max/min for axis auto-scaling
-
- 4. Grid setup: calculating axis spacing, ticks, inserting tick
- labels, the legend
-
- 5. Draw: drawing the grid, drawing each of the series in turn
-
- 6. Setting up event handling for interactive features
-
- 7. Responding to events, if any
-
- Each hook is simply a function which is put in the appropriate array.
- You can add them through the "hooks" option, and they are also available
- after the plot is constructed as the "hooks" attribute on the returned
- plot object, e.g.
-
- // define a simple draw hook
- function hellohook(plot, canvascontext) { alert("hello!"); };
-
- // pass it in, in an array since we might want to specify several
- var plot = $.plot(placeholder, data, { hooks: { draw: [hellohook] } });
-
- // we can now find it again in plot.hooks.draw[0] unless a plugin
- // has added other hooks
-
- The available hooks are described below. All hook callbacks get the
- plot object as first parameter. You can find some examples of defined
- hooks in the plugins bundled with Flot.
-
- - processOptions [phase 1]
-
- function(plot, options)
-
- Called after Flot has parsed and merged options. Useful in the
- instance where customizations beyond simple merging of default
- values is needed. A plugin might use it to detect that it has been
- enabled and then turn on or off other options.
-
-
- - processRawData [phase 3]
-
- function(plot, series, data, datapoints)
-
- Called before Flot copies and normalizes the raw data for the given
- series. If the function fills in datapoints.points with normalized
- points and sets datapoints.pointsize to the size of the points,
- Flot will skip the copying/normalization step for this series.
-
- In any case, you might be interested in setting datapoints.format,
- an array of objects for specifying how a point is normalized and
- how it interferes with axis scaling.
-
- The default format array for points is something along the lines of:
-
- [
- { x: true, number: true, required: true },
- { y: true, number: true, required: true }
- ]
-
- The first object means that for the first coordinate it should be
- taken into account when scaling the x axis, that it must be a
- number, and that it is required - so if it is null or cannot be
- converted to a number, the whole point will be zeroed out with
- nulls. Beyond these you can also specify "defaultValue", a value to
- use if the coordinate is null. This is for instance handy for bars
- where one can omit the third coordinate (the bottom of the bar)
- which then defaults to 0.
-
-
- - processDatapoints [phase 3]
-
- function(plot, series, datapoints)
-
- Called after normalization of the given series but before finding
- min/max of the data points. This hook is useful for implementing data
- transformations. "datapoints" contains the normalized data points in
- a flat array as datapoints.points with the size of a single point
- given in datapoints.pointsize. Here's a simple transform that
- multiplies all y coordinates by 2:
-
- function multiply(plot, series, datapoints) {
- var points = datapoints.points, ps = datapoints.pointsize;
- for (var i = 0; i < points.length; i += ps)
- points[i + 1] *= 2;
- }
-
- Note that you must leave datapoints in a good condition as Flot
- doesn't check it or do any normalization on it afterwards.
-
-
- - draw [phase 5]
-
- function(plot, canvascontext)
-
- Hook for drawing on the canvas. Called after the grid is drawn
- (unless it's disabled) and the series have been plotted (in case
- any points, lines or bars have been turned on). For examples of how
- to draw things, look at the source code.
-
-
- - bindEvents [phase 6]
-
- function(plot, eventHolder)
-
- Called after Flot has setup its event handlers. Should set any
- necessary event handlers on eventHolder, a jQuery object with the
- canvas, e.g.
-
- function (plot, eventHolder) {
- eventHolder.mousedown(function (e) {
- alert("You pressed the mouse at " + e.pageX + " " + e.pageY);
- });
- }
-
- Interesting events include click, mousemove, mouseup/down. You can
- use all jQuery events. Usually, the event handlers will update the
- state by drawing something (add a drawOverlay hook and call
- triggerRedrawOverlay) or firing an externally visible event for
- user code. See the crosshair plugin for an example.
-
- Currently, eventHolder actually contains both the static canvas
- used for the plot itself and the overlay canvas used for
- interactive features because some versions of IE get the stacking
- order wrong. The hook only gets one event, though (either for the
- overlay or for the static canvas).
-
-
- - drawOverlay [phase 7]
-
- function (plot, canvascontext)
-
- The drawOverlay hook is used for interactive things that need a
- canvas to draw on. The model currently used by Flot works the way
- that an extra overlay canvas is positioned on top of the static
- canvas. This overlay is cleared and then completely redrawn
- whenever something interesting happens. This hook is called when
- the overlay canvas is to be redrawn.
-
- "canvascontext" is the 2D context of the overlay canvas. You can
- use this to draw things. You'll most likely need some of the
- metrics computed by Flot, e.g. plot.width()/plot.height(). See the
- crosshair plugin for an example.
-
-
-
- Plugins
- -------
-
- Plugins extend the functionality of Flot. To use a plugin, simply
- include its Javascript file after Flot in the HTML page.
-
- If you're worried about download size/latency, you can concatenate all
- the plugins you use, and Flot itself for that matter, into one big file
- (make sure you get the order right), then optionally run it through a
- Javascript minifier such as YUI Compressor.
-
- Here's a brief explanation of how the plugin plumbings work:
-
- Each plugin registers itself in the global array $.plot.plugins. When
- you make a new plot object with $.plot, Flot goes through this array
- calling the "init" function of each plugin and merging default options
- from its "option" attribute. The init function gets a reference to the
- plot object created and uses this to register hooks and add new public
- methods if needed.
-
- See the PLUGINS.txt file for details on how to write a plugin. As the
- above description hints, it's actually pretty easy.
|