From 126cb072fc081049f8c1be8a66b79ebaed6a72aa Mon Sep 17 00:00:00 2001 From: David Schnur Date: Sun, 23 Dec 2012 08:54:34 -0500 Subject: [PATCH 1/7] Added a 'zero' option for lines and bars. Area and bar plots normally use a minimum of zero, since their purpose is to show size, and using an auto-scaled minimum distorts the plot's meaning. But this behavior is undesirable in cases where the plot type is used in more of a decorative sense. The zero option provides a way to control this behavior. It defauls to true for bars and filled lines. --- jquery.flot.js | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/jquery.flot.js b/jquery.flot.js index 605fce8..13f8db3 100644 --- a/jquery.flot.js +++ b/jquery.flot.js @@ -106,6 +106,8 @@ Licensed under the MIT license. fill: false, fillColor: null, steps: false + // Omit 'zero', so we can later default its value to + // match that of the 'fill' option. }, bars: { show: false, @@ -114,7 +116,8 @@ Licensed under the MIT license. fill: true, fillColor: null, align: "left", // "left", "right", or "center" - horizontal: false + horizontal: false, + zero: true }, shadowSize: 3, highlightColor: null @@ -498,6 +501,13 @@ Licensed under the MIT license. s.lines.show = true; } + // If nothing was provided for lines.zero, default it to match + // lines.fill, since areas by default should extend to zero. + + if (s.lines.show && s.lines.zero == null) { + s.lines.zero = !!s.lines.fill; + } + // setup axes s.xaxis = getOrCreateAxis(xaxes, axisNumber(s, "x")); s.yaxis = getOrCreateAxis(yaxes, axisNumber(s, "y")); From b6924a96d934e9f70ba746240dd8d7cc863d8f84 Mon Sep 17 00:00:00 2001 From: David Schnur Date: Sun, 23 Dec 2012 09:44:18 -0500 Subject: [PATCH 2/7] Update auto-scaling to support the zero option. Added a format option 'autoscale' that controls whether the given point is considered when determining an automatic scale. The lines & bars 'zero' option controls whether autoscale is set on the dummy point that is inserted to create the series lower-bound. --- jquery.flot.js | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/jquery.flot.js b/jquery.flot.js index 13f8db3..c423256 100644 --- a/jquery.flot.js +++ b/jquery.flot.js @@ -556,8 +556,9 @@ Licensed under the MIT license. format.push({ x: true, number: true, required: true }); format.push({ y: true, number: true, required: true }); - if (s.bars.show || (s.lines.show && s.lines.fill)) { - format.push({ y: true, number: true, required: false, defaultValue: 0 }); + if (s.bars.show || (s.lines.show && (s.lines.fill || s.lines.zero))) { + var autoscale = !!((s.bars.show && s.bars.zero) || (s.lines.show && s.lines.zero)); + format.push({ y: true, number: true, required: false, defaultValue: 0, autoscale: autoscale }); if (s.bars.horizontal) { delete format[format.length - 1].y; format[format.length - 1].x = true; @@ -671,7 +672,7 @@ Licensed under the MIT license. for (m = 0; m < ps; ++m) { val = points[j + m]; f = format[m]; - if (!f || val == fakeInfinity || val == -fakeInfinity) + if (!f || f.autoscale === false || val == fakeInfinity || val == -fakeInfinity) continue; if (f.x) { From 6412dafc6e09b2dd021e30d0c9afc3c1fbc700a0 Mon Sep 17 00:00:00 2001 From: David Schnur Date: Thu, 10 Jan 2013 09:57:00 -0500 Subject: [PATCH 3/7] Restrict zero to bars and filled lines only. This also includes a tweak to zero's default. Previously zero only received a value if lines were visible; now it always receives a value, matching the behavior of other contextual options. --- jquery.flot.js | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/jquery.flot.js b/jquery.flot.js index c423256..249874b 100644 --- a/jquery.flot.js +++ b/jquery.flot.js @@ -501,12 +501,12 @@ Licensed under the MIT license. s.lines.show = true; } - // If nothing was provided for lines.zero, default it to match - // lines.fill, since areas by default should extend to zero. + // If nothing was provided for lines.zero, default it to match + // lines.fill, since areas by default should extend to zero. - if (s.lines.show && s.lines.zero == null) { - s.lines.zero = !!s.lines.fill; - } + if (s.lines.zero == null) { + s.lines.zero = !!s.lines.fill; + } // setup axes s.xaxis = getOrCreateAxis(xaxes, axisNumber(s, "x")); @@ -556,8 +556,8 @@ Licensed under the MIT license. format.push({ x: true, number: true, required: true }); format.push({ y: true, number: true, required: true }); - if (s.bars.show || (s.lines.show && (s.lines.fill || s.lines.zero))) { - var autoscale = !!((s.bars.show && s.bars.zero) || (s.lines.show && s.lines.zero)); + if (s.bars.show || (s.lines.show && s.lines.fill)) { + var autoscale = !!((s.bars.show && s.bars.zero) || (s.lines.show && s.lines.zero)); format.push({ y: true, number: true, required: false, defaultValue: 0, autoscale: autoscale }); if (s.bars.horizontal) { delete format[format.length - 1].y; From 790bbaf55f4ce4c6539831aa6c4febdb341ef19e Mon Sep 17 00:00:00 2001 From: David Schnur Date: Thu, 10 Jan 2013 09:59:45 -0500 Subject: [PATCH 4/7] Mirror the zero option to the categories plugin. Due to limitations in our plugin architecture, the categories plugin duplicates code from Flot's core for adding a dummy point to snap the y axis to zero. We can get rid of this duplication in 0.9; for now we'll just update the duplicate to match the change in core that introduced the new 'zero' option. --- jquery.flot.categories.js | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/jquery.flot.categories.js b/jquery.flot.categories.js index 5bc2396..ec314bf 100644 --- a/jquery.flot.categories.js +++ b/jquery.flot.categories.js @@ -74,7 +74,8 @@ as "categories" on the axis object, e.g. plot.getAxes().xaxis.categories. format.push({ y: true, number: true, required: true }); if (s.bars.show || (s.lines.show && s.lines.fill)) { - format.push({ y: true, number: true, required: false, defaultValue: 0 }); + var autoscale = !!((s.bars.show && s.bars.zero) || (s.lines.show && s.lines.zero)); + format.push({ y: true, number: true, required: false, defaultValue: 0, autoscale: autoscale }); if (s.bars.horizontal) { delete format[format.length - 1].y; format[format.length - 1].x = true; From 1e685b0446f6e6b3281c02230d70e810e7eb6a4c Mon Sep 17 00:00:00 2001 From: David Schnur Date: Thu, 10 Jan 2013 10:00:32 -0500 Subject: [PATCH 5/7] Documented the zero option for bars and lines. --- API.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/API.md b/API.md index 2215c2f..5335129 100644 --- a/API.md +++ b/API.md @@ -669,6 +669,10 @@ series: { fillColor: null or color/gradient } + lines, bars: { + zero: boolean + } + points: { radius: number symbol: "circle" or function @@ -737,6 +741,13 @@ 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. +Area and bar charts normally start from zero, regardless of the data's range. +This is because they convey information through size, and starting from a +different value would distort their meaning. In cases where the fill is purely +for decorative purposes, however, "zero" allows you to override this behavior. +It defaults to true for filled lines and bars; setting it to false tells the +series to use the same automatic scaling as an un-filled line. + 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 From 151e96fb2724780981e6694d83350f353745d461 Mon Sep 17 00:00:00 2001 From: David Schnur Date: Thu, 10 Jan 2013 13:07:53 -0500 Subject: [PATCH 6/7] Expand documentation of the point format options. --- API.md | 40 ++++++++++++++++++++++++++++++---------- 1 file changed, 30 insertions(+), 10 deletions(-) diff --git a/API.md b/API.md index 5335129..bcf5d25 100644 --- a/API.md +++ b/API.md @@ -1247,9 +1247,21 @@ hooks in the plugins bundled with Flot. 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. + how it interferes with axis scaling. It accepts the following options: - The default format array for points is something along the lines of: + ```js + { + x, y: boolean, + number: boolean, + required: boolean, + defaultValue: value, + autoscale: boolean + } + ``` + + "x" and "y" specify whether the value is plotted against the x or y axis, + and is currently used only to calculate axis min-max ranges. The default + format array, for example, looks like this: ```js [ @@ -1258,14 +1270,22 @@ hooks in the plugins bundled with Flot. ] ``` - 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. + This indicates that a point, i.e. [0, 25], consists of two values, with the + first being plotted on the x axis and the second on the y axis. + + If "number" is true, then the value must be numeric, and is set to null if + it cannot be converted to a number. + + "defaultValue" provides a fallback in case the original value 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 zero. + + If "required" is true, then the value must exist (be non-null) for the + point as a whole to be valid. If no value is provided, then the entire + point is cleared out with nulls, turning it into a gap in the series. + + "autoscale" determines whether the value is considered when calculating an + automatic min-max range for the axes that the value is plotted against. - processDatapoints [phase 3] From 2c64f82a4fe8165469c3f9405597ea3bad19d4ab Mon Sep 17 00:00:00 2001 From: David Schnur Date: Thu, 10 Jan 2013 13:10:57 -0500 Subject: [PATCH 7/7] Added the new 'zero' option to the changelog. --- NEWS.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/NEWS.md b/NEWS.md index ed6f89c..91e4064 100644 --- a/NEWS.md +++ b/NEWS.md @@ -101,6 +101,9 @@ The base and overlay canvas are now using the CSS classes "flot-base" and - The selection plugin's getSelection now returns null when the selection has been cleared. (patch by Nick Campbell, pull request #852) + - Added a new option called 'zero' to bars and filled lines series, to control + whether the y-axis minimum is scaled to fit the data or set to zero. + ### Bug fixes ### - Fix problem with null values and pie plugin. (patch by gcruxifix,