diff --git a/API.txt b/API.txt.md similarity index 83% rename from API.txt rename to API.txt.md index 61d2f34..0a76501 100644 --- a/API.txt +++ b/API.txt.md @@ -1,9 +1,9 @@ Flot Reference --------------- +============== Consider a call to the plot function: - var plot = $.plot(placeholder, data, options) + 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 @@ -28,16 +28,16 @@ Data Format The data is an array of data series: - [ series1, series2, ... ] + [ 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], ... ] + [ [x1, y1], [x2, y2], ... ] E.g. - [ [1, 3], [2, 14.01], [3.5, 3.14] ] + [ [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 @@ -58,28 +58,28 @@ area/bar (defaults to 0). The format of a single series object is as follows: - { - color: color or number - data: rawdata - label: string - lines: specific lines options - bars: specific bars options - points: specific points options - xaxis: number - yaxis: number - clickable: boolean - hoverable: boolean - shadowSize: number - } + { + color: color or number + data: rawdata + label: string + lines: specific lines options + bars: specific bars options + points: specific points options + xaxis: number + yaxis: number + clickable: boolean + hoverable: boolean + shadowSize: number + } You don't have to specify any of them except the data, the rest are options that will get default values. Typically you'd only specify label and data, like this: - { - label: "y = 3", - data: [[0, 3], [10, 3]] - } + { + 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. @@ -108,8 +108,8 @@ 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] ] } ] + [ { label: "Foo", data: [ [10, 1], [17, -14], [30, 5] ] }, + { label: "Bar", data: [ [11, 13], [19, 11], [30, -7] ] } ] Plot Options @@ -118,30 +118,30 @@ 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 } - } - }; + var options = { + series: { + lines: { show: true }, + points: { show: true } + } + }; - $.plot(placeholder, data, options); + $.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 - } + 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 @@ -149,10 +149,10 @@ 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 '' + label + ''; - } + labelFormatter: function(label, series) { + // series is the series object for the label + return '' + label + ''; + } "noColumns" is the number of columns to divide the legend table into. "position" specifies the overall placement of the legend within the @@ -171,36 +171,36 @@ ignored. Note that Flot will overwrite the contents of the container. Customizing the axes ==================== - xaxis, yaxis: { - show: null or true/false - position: "bottom" or "top" or "left" or "right" - mode: null or "time" - - color: null or color spec - tickColor: null or color spec - font: null or font spec object - - min: null or number - max: null or number - autoscaleMargin: null or number - - transform: null or fn: number -> number - inverseTransform: null or fn: number -> number - - ticks: null or number or ticks array or (fn: axis -> ticks array) - tickSize: number or array - minTickSize: number or array - tickFormatter: (fn: number, object -> string) or string - tickDecimals: null or number - - labelWidth: null or number - labelHeight: null or number - reserveSpace: null or true - - tickLength: null or number - - alignTicksWithAxis: null or number - } + xaxis, yaxis: { + show: null or true/false + position: "bottom" or "top" or "left" or "right" + mode: null or "time" + + color: null or color spec + tickColor: null or color spec + font: null or font spec object + + min: null or number + max: null or number + autoscaleMargin: null or number + + transform: null or fn: number -> number + inverseTransform: null or fn: number -> number + + ticks: null or number or ticks array or (fn: axis -> ticks array) + tickSize: number or array + minTickSize: number or array + tickFormatter: (fn: number, object -> string) or string + tickDecimals: null or number + + labelWidth: null or number + labelHeight: null or number + reserveSpace: null or true + + tickLength: null or number + + alignTicksWithAxis: null or number + } All axes have the same kind of options. The following describes how to configure one axis, see below for what to do if you've got more than @@ -229,13 +229,13 @@ read from the font style on the placeholder element (80% the size of that to be precise). If you set it directly with "font: { ... }", the format is like this: - { - size: 11, - style: "italic", - weight: "bold", - family: "sans-serif", - variant: "small-caps" - } + { + size: 11, + style: "italic", + weight: "bold", + family: "sans-serif", + variant: "small-caps" + } 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 @@ -260,18 +260,18 @@ 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); } - } + xaxis: { + transform: function (v) { return Math.log(v); }, + inverseTransform: function (v) { return Math.exp(v); } + } Similarly, for reversing the y axis so the values appear in inverse order: - yaxis: { - transform: function (v) { return -v; }, - inverseTransform: function (v) { return -v; } - } + yaxis: { + transform: function (v) { return -v; }, + inverseTransform: function (v) { return -v; } + } Note that for finding extrema, Flot assumes that the transform function does not reorder values (it should be monotone). @@ -306,11 +306,11 @@ 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] + 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"]] + ticks: [[0, "zero"], [1.2, "one mark"], [2.4, "two marks"]] You can mix the two if you like. @@ -320,16 +320,16 @@ 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; - } + 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). @@ -339,9 +339,9 @@ 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); - } + 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 @@ -349,14 +349,14 @@ The axis object has "min" and "max" with the range of the axis, 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"; - } + 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"; + } "labelWidth" and "labelHeight" specifies a fixed size of the tick labels in pixels. They're useful in case you need to align several @@ -390,16 +390,16 @@ that a series should be plotted against the second y axis. To actually configure that axis, you can't use the xaxis/yaxis options directly - instead there are two arrays in the options: - xaxes: [] - yaxes: [] + xaxes: [] + yaxes: [] Here's an example of configuring a single x axis and two y axes (we can leave options of the first y axis empty as the defaults are fine): - { - xaxes: [ { position: "top" } ], - yaxes: [ { }, { position: "right", min: 20 } ] - } + { + xaxes: [ { position: "top" } ], + yaxes: [ { }, { position: "right", min: 20 } ] + } The arrays get their default values from the xaxis/yaxis settings, so say you want to have all y axes start at zero, you can simply specify @@ -428,7 +428,7 @@ in milliseconds, so remember to multiply by 1000! You can see a timestamp like this - alert((new Date()).getTime()) + 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 @@ -451,12 +451,12 @@ In PHP you can get an appropriate timestamp 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); - } + 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. @@ -478,32 +478,32 @@ 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 + 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" - } + 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), use %0d for zero-padding - %m: month (1-12), use %0m for zero-padding - %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) + %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), use %0d for zero-padding + %m: month (1-12), use %0m for zero-padding + %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) Inserting a zero like %0m or %0d means that the specifier will be left-padded with a zero if it's only single-digit. So %y-%0m-%0d @@ -512,7 +512,7 @@ results in unambigious ISO timestamps like 2007-05-10 (for May 10th). 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"] + 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. @@ -528,17 +528,17 @@ 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); - } + 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"] + 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 @@ -549,33 +549,33 @@ 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 - symbol: "circle" or function - } - - bars: { - barWidth: number - align: "left" or "center" - horizontal: boolean - } - - lines: { - steps: boolean + series: { + lines, points, bars: { + show: boolean + lineWidth: number + fill: boolean or number + fillColor: null or color/gradient + } + + points: { + radius: number + symbol: "circle" or function + } + + bars: { + barWidth: number + align: "left" or "center" + horizontal: boolean + } + + lines: { + steps: boolean + } + + shadowSize: number } - - shadowSize: number - } - - colors: [ color1, color2, ... ] + + 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 @@ -590,12 +590,12 @@ 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 } - } - }; + 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 @@ -630,13 +630,13 @@ For points, you can specify the radius and the symbol. The only built-in symbol type is circles, for other types you can use a plugin or define them yourself by specifying a callback: - function cross(ctx, x, y, radius, shadow) { + function cross(ctx, x, y, radius, shadow) { var size = radius * Math.sqrt(Math.PI) / 2; ctx.moveTo(x - size, y - size); ctx.lineTo(x + size, y + size); ctx.moveTo(x - size, y + size); ctx.lineTo(x + size, y - size); - } + } The parameters are the drawing context, x and y coordinates of the center of the point, a radius which corresponds to what the circle @@ -653,7 +653,7 @@ 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"] + 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. @@ -662,26 +662,26 @@ 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 - labelMargin: number - axisMargin: number - markings: array of markings or (fn: axes -> array of markings) - borderWidth: number - borderColor: color or null - minBorderMargin: number or null - clickable: boolean - hoverable: boolean - autoHighlight: boolean - mouseActiveRadius: number - } - - interaction: { - redrawOverlayInterval: number or -1 - } + grid: { + show: boolean + aboveData: boolean + color: color + backgroundColor: color/gradient or null + labelMargin: number + axisMargin: number + markings: array of markings or (fn: axes -> array of markings) + borderWidth: number + borderColor: color or null + minBorderMargin: number or null + clickable: boolean + hoverable: boolean + autoHighlight: boolean + mouseActiveRadius: number + } + + interaction: { + redrawOverlayInterval: number or -1 + } The grid is the thing with the axes and a number of ticks. Many of the things in the grid are configured under the individual axes, but not @@ -716,7 +716,7 @@ 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" }, ... ] + 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: { @@ -725,19 +725,19 @@ 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 } }, ... ] + 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 that makes vertical stripes 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; - } + 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 @@ -758,25 +758,25 @@ 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); - // axis coordinates for other axes, if present, are in pos.x2, pos.x3, ... - // if you need global screen coordinates, they are pos.pageX, pos.pageY - - if (item) { - highlight(item.series, item.datapoint); - alert("You clicked a point!"); - } + alert("You clicked at " + pos.x + ", " + pos.y); + // axis coordinates for other axes, if present, are in pos.x2, pos.x3, ... + // 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: { + 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 @@ -813,14 +813,14 @@ Specifying gradients A gradient is specified like this: - { colors: [ color1, color2, ... ] } + { 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"] } - } + 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 @@ -832,12 +832,12 @@ 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: { + 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. @@ -922,8 +922,8 @@ can call: space within the placeholder div. If you are working with multiple axes, you can specify the x and y axis references, e.g. - o = pointOffset({ x: xpos, y: ypos, xaxis: 2, yaxis: 3 }) - // o.left and o.top now contains the offset within the div + o = pointOffset({ x: xpos, y: ypos, xaxis: 2, yaxis: 3 }) + // o.left and o.top now contains the offset within the div - resize() @@ -1040,14 +1040,14 @@ 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!"); }; + // 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] } }); + // 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 + // 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 @@ -1078,10 +1078,10 @@ hooks in the plugins bundled with Flot. The default format array for points is something along the lines of: - [ - { x: true, number: true, required: true }, - { y: true, number: true, required: true } - ] + [ + { 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 @@ -1104,11 +1104,11 @@ hooks in the plugins bundled with Flot. given in datapoints.pointsize. Here's a simple transform that multiplies all y coordinates by 2: - function multiply(plot, series, datapoints) { + 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; - } + 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. @@ -1141,11 +1141,11 @@ hooks in the plugins bundled with Flot. necessary event handlers on eventHolder, a jQuery object with the canvas, e.g. - function (plot, eventHolder) { + function (plot, eventHolder) { eventHolder.mousedown(function (e) { - alert("You pressed the mouse at " + e.pageX + " " + e.pageY); + 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 @@ -1168,7 +1168,7 @@ hooks in the plugins bundled with Flot. - drawOverlay [phase 7] - function (plot, canvascontext) + 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 @@ -1185,7 +1185,7 @@ hooks in the plugins bundled with Flot. - shutdown [phase 8] - function (plot, eventHolder) + function(plot, eventHolder) Run when plot.shutdown() is called, which usually only happens in case a plot is overwritten by a new plot. If you're writing a diff --git a/README.txt.md b/README.txt.md index 0248719..6ef1129 100644 --- a/README.txt.md +++ b/README.txt.md @@ -67,7 +67,7 @@ ready, run the plot function: Here, data is an array of data series and options is an object with settings if you want to customize the plot. Take a look at the examples for some ideas of what to put in or look at the reference -in the file "API.txt". Here's a quick example that'll draw a line from +in the file "API.txt.md". Here's a quick example that'll draw a line from (0, 0) to (1, 1): $.plot($("#placeholder"), [ [[0, 0], [1, 1]] ], { yaxis: { max: 1 } });