Documented the date support, tweaking the API a bit in the process, deprecated noTicks in favour of a numerical parameter to ticks

git-svn-id: https://flot.googlecode.com/svn/trunk@44 1e0a6537-2640-0410-bfb7-f154510ff394

API.txt

@@ -36,6 +36,13 @@ 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). If you put in something else, e.g. a string, the plot
+function fails with strange errors. This is a common problem because
+you might accidentally retrieve data from the database as strings and
+serialize them directly to JSON without noticing the wrong type.
+
 The format of a single series object is as follows:
 
   {
@@ -74,6 +81,11 @@ 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
 ------------
@@ -93,14 +105,14 @@ Customizing the legend
 ======================
 
   legend: {
-    show: boolean,
+    show: boolean
-    labelFormatter: null or (fn: string -> string),
+    labelFormatter: null or (fn: string -> string)
-    labelBoxBorderColor: color,
+    labelBoxBorderColor: color
-    noColumns: number,
+    noColumns: number
-    position: "ne" or "nw" or "se" or "sw",
+    position: "ne" or "nw" or "se" or "sw"
-    margin: number of pixels,
+    margin: number of pixels
-    backgroundColor: null or color,
+    backgroundColor: null or color
-    backgroundOpacity: number in 0.0 - 1.0,
+    backgroundOpacity: number in 0.0 - 1.0
     container: null or jQuery object
   }
 
@@ -131,19 +143,22 @@ Customizing the axes
 ====================
 
   xaxis, yaxis: {
-    ticks: null or ticks array or (fn: range -> ticks array),
+    mode: null or "time"
-    noTicks: number,
+    min: null or number
-    tickFormatter: fn: number, object -> string,
+    max: null or number
-    tickDecimals: null or number,
-    min: null or number,
-    max: null or number,
     autoscaleMargin: null or number
+    ticks: null or number or ticks array or (fn: range -> ticks array)
+    tickFormatter: (fn: number, object -> string) or string
+    tickDecimals: null or number
   }
 
-The two axes have the same kind of options. The most import are
+The two axes have the same kind of options. The "mode" option
-"min"/"max" that specifies the precise minimum/maximum value on the
+determines how the data is interpreted, the default of null means as
-scale. If you don't specify a value, it will automatically be chosen
+decimal numbers. Use "time" for time series data, see the next section.
-by a scaling algorithm based on the minimum/maximum data values.
+
+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
@@ -153,23 +168,23 @@ 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.
 
-The rest of the options deal with the ticks. If you don't specify any
+The rest of the options deal with the ticks.
-ticks, a tick generator algorithm will make some for you based on the
+
-number of ticks setting, "noTicks". The algorithm always tries to
+If you don't specify any ticks, a tick generator algorithm will make
-generate reasonably round tick values so even if you ask for 3 ticks,
+some for you. You can tweak how many it tries to generate by setting
-you might get 5 if that fits better with the rounding. Never set
+"ticks" to a number. The algorithm always tries to generate reasonably
-"noTicks" to 0, that will just break the auto-detection stuff. If you
+round tick values so even if you ask for 3 ticks, you might get 5 if
-don't want ticks, provide an empty "ticks" array as described below.
+that fits better with the rounding. If you don't want ticks, set
+"ticks" to 0 or an empty array.
 
 You can control how the ticks look like with "tickDecimals", the
 number of decimals to display (default is auto-detected), or by
-providing a function to "tickFormatter".
+providing a function as "tickFormatter". The tick formatter function
+gets two argument, the tick value and an optional "axis" object with
+information, and should return a string. The default formatter looks
+like this:
 
-The tick formatter function gets two argument, the tick value and an
+  function formatter(val, axis) {
-optional "axis" object with information, and should return a string.
-The default formatter looks like this:
-
-  function defaultTickFormatter(val, axis) {
     return val.toFixed(axis.tickDecimals);
   }
 
@@ -189,8 +204,8 @@ custom formatter:
   }
 
 
-If you want to override the tick algorithm, you can manually specify
+If you want to override the tick algorithm, you can specify an array
-"ticks" which should be an array of tick values, either like this:
+to "ticks", either like this:
 
   ticks: [0, 1.2, 2.4]
 
@@ -198,10 +213,6 @@ Or like this (you can mix the two if you like):
 
   ticks: [[0, "zero"], [1.2, "one mark"], [2.4, "two marks"]]
 
-You can disable the ticks by providing an empty array:
-
-  ticks: []
-  
 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
@@ -221,8 +232,84 @@ axis for trigonometric functions:
     return res;
   }
 
-Note that the scaling and tick algorithms don't work with time series
+
-yet.
+Time series data
+================
+
+The time series support in Flot is based on Javascript timestamps,
+i.e. everywhere a time value is expected or passed over, a Javascript
+timestamp number is used. This is not the same as a Date object. A
+Javascript timestamp is the number of milliseconds since January 1,
+1970 00:00:00. This is almost the same as Unix timestamps, except it's
+in milliseconds, so remember to multiply by 1000!
+
+You can see a timestamp by outputting
+
+  (new Date()).getTime()
+
+In PHP you can get an appropriate timestamp with
+'strtotime("2002-02-20") * 1000', in Python with
+'time.mktime(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 (int)(time.Ticks / 10000);
+  }
+
+Once you've got 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. Again the values should be timestamps, not Date objects!
+
+Formatting is controlled separately through the following axis
+options:
+
+  xaxis, yaxis: {
+    timeformat: null or format string
+    monthNames: null or array of size 12 of strings
+  }
+
+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)
+
+You can customize the month names with the "monthNames" option. For
+instance, for Danish you might specify:
+
+  monthName: ["jan", "feb", "mar", "apr", "maj", "jun", "jul", "aug", "sep", "okt", "nov", "dec"]
+
+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.getDate() + "/" + (d.getMonth() + 1);
+  }
+
+For the time mode the axis object contains an additional
+"tickSizeUnit" which is one of "second", "minute", "hour", "day",
+"month" and "year". So if axis.tickSize is 2 and axis.tickSizeUnit is
+"day", the ticks have been produced with two days in-between.
 
 
 Customizing the data series

TODO

@@ -2,10 +2,9 @@ These are mostly ideas, that they're written down here is no guarantee
 that they'll ever be done. If you want something done, feel free to
 say why or come up with a patch. :-)
 
-handling time data
+pending
-  - dataformat
+  - split out autoscaleMargin into a snapToTicks
-  - axis adjustment
+  - autodetect a sensible ticks setting
-  - tick generation
 
 grid configuration
   - how ticks look like

examples/setting-options.html

@@ -48,7 +48,7 @@ $(function () {
             ticks: [0, [Math.PI/2, "\u03c0/2"], [Math.PI, "\u03c0"], [Math.PI * 3/2, "3\u03c0/2"], [Math.PI * 2, "2\u03c0"]]
         },
         yaxis: {
-            noTicks: 10,
+            ticks: 10,
             min: -2,
             max: 2
         },

examples/visitors.html

@@ -43,7 +43,7 @@ $(function () {
     }
     
     var options = {
-        xaxis: { datatype: "time" },
+        xaxis: { mode: "time" },
         selection: { mode: "x" },
         grid: { coloredAreas: weekendAreas }
     };
@@ -53,7 +53,7 @@ $(function () {
     var overview = $.plot($("#overview"), [d], {
         lines: { show: true, lineWidth: 1 },
         shadowSize: 0,
-        xaxis: { ticks: [], datatype: "time" },
+        xaxis: { ticks: [], mode: "time" },
         yaxis: { ticks: [], min: 0, max: 4000 },
         selection: { mode: "x" }
     });

examples/zooming.html

@@ -21,7 +21,7 @@
       <p id="overviewLegend" style="margin-left:10px"></p>
     </div>
 
-    <p style="clear:left"> The selection support makes even
+    <p style="clear:left"> The selection support makes 
       pretty advanced zooming schemes possible. With a few lines of code,
       the small overview plot to the right has been connected to the large
       plot. Try selecting a rectangle on either of them.</p>
@@ -43,7 +43,7 @@ $(function () {
         legend: { show: false },
         lines: { show: true },
         points: { show: true },
-        yaxis: { noTicks: 10 },
+        yaxis: { ticks: 10 },
         selection: { mode: "xy" }
     };
 
@@ -56,8 +56,8 @@ $(function () {
         legend: { show: true, container: $("#overviewLegend") },
         lines: { show: true, lineWidth: 1 },
         shadowSize: 0,
-        xaxis: { noTicks: 4 },
+        xaxis: { ticks: 4 },
-        yaxis: { noTicks: 3, min: -2, max: 2 },
+        yaxis: { ticks: 3, min: -2, max: 2 },
         grid: { color: "#999" },
         selection: { mode: "xy" }
     });

jquery.flot.js

@@ -7,7 +7,7 @@
 (function($) {
     function Plot(target_, data_, options_) {
         // data is on the form:
-        //   [ series1 series2 ... ]
+        //   [ series1, series2 ... ]
         // where series is either just the data as [ [x1, y1], [x2, y2], ... ]
         // or { data: [ [x1, y1], [x2, y2], ... ], label: "some label" }
         
@@ -27,19 +27,21 @@
                 backgroundOpacity: 0.85 // set to 0 to avoid background
             },
             xaxis: {
-                ticks: null, // either [1, 3] or [[1, "a"], 3] or fn: axis info -> ticks
+                mode: null, // null or "time"
-                noTicks: 5, // approximate number of ticks for auto-ticks
-                tickFormatter: null, // fn: number -> string or format string if datatype is date
-                tickDecimals: null, // no. of decimals, null means auto
-                datatype: "number", // one of "number", "time"
                 min: null, // min. value to show, null means set automatically
                 max: null, // max. value to show, null means set automatically
-                autoscaleMargin: null // margin in % to add if auto-setting min/max
+                autoscaleMargin: null, // margin in % to add if auto-setting min/max
+                ticks: null, // either [1, 3] or [[1, "a"], 3] or (fn: axis info -> ticks) or app. number of ticks for auto-ticks
+                tickFormatter: null, // fn: number -> string
+                
+                // mode specific options
+                tickDecimals: null, // no. of decimals, null means auto
+
+                monthNames: null, // list of names of months
+                timeformat: null, // format string to use
             },
             yaxis: {
-                noTicks: 5,
                 ticks: null,
-                datatype: "number",
                 autoscaleMargin: 0.02
             },
             points: {
@@ -75,12 +77,7 @@
                 mode: null, // one of null, "x", "y" or "xy"
                 color: "#e8cfac"
             },
-            shadowSize: 4,
+            shadowSize: 4
-            datatype: {
-                time: {
-                    monthNames: ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]
-                }
-            }
         };
         var canvas = null, overlay = null;
         var ctx = null, octx = null;
@@ -98,16 +95,6 @@
         var hozScale = 0;
         var vertScale = 0;
 
-        // map of app. size of time units in milliseconds
-        var timeUnitSize = {
-            "second": 1000,
-            "minute": 60 * 1000,
-            "hour": 60 * 60 * 1000,
-            "day": 24 * 60 * 60 * 1000,
-            "month": 30 * 24 * 60 * 60 * 1000,
-            "year": 365.2425 * 24 * 60 * 60 * 1000
-        };
-
         // initialize
         series = parseData(data_);
         parseOptions(options_);
@@ -117,11 +104,11 @@
         bindEvents();
         findDataRanges();
         setRange(xaxis, options.xaxis);
-        setTickSize(xaxis, options.xaxis);
+        prepareTickGeneration(xaxis, options.xaxis);
         setTicks(xaxis, options.xaxis);
         extendXRangeIfNeededByBar();
         setRange(yaxis, options.yaxis);
-        setTickSize(yaxis, options.yaxis);
+        prepareTickGeneration(yaxis, options.yaxis);
         setTicks(yaxis, options.yaxis);
         setSpacing();
         draw();
@@ -152,6 +139,12 @@
         
         function parseOptions(o) {
             $.extend(true, options, o);
+
+            // backwards compatibility, to be removed in future
+            if (options.xaxis.noTicks && options.xaxis.ticks == null)
+                options.xaxis.ticks = options.xaxis.noTicks;
+            if (options.yaxis.noTicks && options.yaxis.ticks == null)
+                options.yaxis.ticks = options.yaxis.noTicks;
         }
 
         function constructCanvas() {
@@ -263,12 +256,66 @@
             axis.max = max;
         }
 
-        function setTickSize(axis, axisOptions) {
+        function prepareTickGeneration(axis, axisOptions) {
-            var delta = (axis.max - axis.min) / axisOptions.noTicks;
+            var noTicks = 5;
+            if (typeof axisOptions.ticks == "number" && axisOptions.ticks > 0)
+                noTicks = axisOptions.ticks;
+            
+            var delta = (axis.max - axis.min) / noTicks;
             var size, generator, unit = "", formatter, i;
 
-            if (axisOptions.datatype == "time") {
+            if (axisOptions.mode == "time") {
                 // pretty handling of time
+                
+                function formatDate(d, fmt, monthNames) {
+                    var leftPad = function(n) {
+                        n = "" + n;
+                        return n.length == 1 ? "0" + n : n;
+                    };
+                    
+                    var r = [];
+                    var escape = false;
+                    if (monthNames == null)
+                        monthNames = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+                    for (var i = 0; i < fmt.length; ++i) {
+                        var c = fmt.charAt(i);
+                        
+                        if (escape) {
+                            switch (c) {
+                            case 'h': c = "" + d.getHours(); break;
+                            case 'H': c = leftPad(d.getHours()); break;
+                            case 'M': c = leftPad(d.getMinutes()); break;
+                            case 'S': c = leftPad(d.getSeconds()); break;
+                            case 'd': c = "" + d.getDate(); break;
+                            case 'm': c = "" + (d.getMonth() + 1); break;
+                            case 'y': c = "" + d.getFullYear(); break;
+                            case 'b': c = "" + monthNames[d.getMonth()]; break;
+                            default: c;
+                            }
+                            r.push(c);
+                            escape = false;
+                        }
+                        else {
+                            if (c == "%")
+                                escape = true;
+                            else
+                                r.push(c);
+                        }
+                    }
+                    return r.join("");
+                }
+                
+                    
+                // map of app. size of time units in milliseconds
+                var timeUnitSize = {
+                    "second": 1000,
+                    "minute": 60 * 1000,
+                    "hour": 60 * 60 * 1000,
+                    "day": 24 * 60 * 60 * 1000,
+                    "month": 30 * 24 * 60 * 60 * 1000,
+                    "year": 365.2425 * 24 * 60 * 60 * 1000
+                };
+
 
                 // the allowed tick sizes, after 1 year we use
                 // an integer algorithm
@@ -339,9 +386,8 @@
                             //console.log(d, "month", axis.tickSize)
                             if (axis.tickSize < 1) {
                                 // a bit complicated - we'll divide the month
-                                // up but we need to take care
+                                // up but we need to take care of fractions
-                                // of fractions so we don't end up in the
+                                // so we don't end up in the middle of a day
-                                // middle of a day
                                 d.setDate(1);
                                 var start = d.getTime();
                                 d.setMonth(d.getMonth() + 1);
@@ -400,37 +446,37 @@
                     size *= magn;
                 }
 
-                if (typeof axisOptions.tickFormatter == "string")
+                formatter = function (v, axis) {
-                    formatter = function (v, axis) {
+                    var d = new Date(v);
-                        return formatDate(new Date(v), axisOptions.tickFormatter);
+                    
-                    };
+                    // first check global format
-                else
+                    if (axisOptions.timeformat != null)
-                    formatter = function (v, axis) {
+                        return formatDate(d, axisOptions.timeformat, axisOptions.monthNames);
-                        var d = new Date(v);
+                    
-                        var t = axis.tickSize * timeUnitSize[axis.tickSizeUnit];
+                    var t = axis.tickSize * timeUnitSize[axis.tickSizeUnit];
-                        var span = axis.max - axis.min;
+                    var span = axis.max - axis.min;
-                        
+                    
-                        if (t < timeUnitSize.minute)
+                    if (t < timeUnitSize.minute)
-                            fmt = "%h:%M:%S";
+                        fmt = "%h:%M:%S";
-                        else if (t < timeUnitSize.day) {
+                    else if (t < timeUnitSize.day) {
-                            if (span < 2 * timeUnitSize.day)
+                        if (span < 2 * timeUnitSize.day)
-                                fmt = "%h:%M";
+                            fmt = "%h:%M";
-                            else
+                        else
                             fmt = "%b %d %h:%M";
-                        }
+                    }
-                        else if (t < timeUnitSize.month)
+                    else if (t < timeUnitSize.month)
-                            fmt = "%b %d";
+                        fmt = "%b %d";
-                        else if (t < timeUnitSize.year) {
+                    else if (t < timeUnitSize.year) {
-                            if (span < timeUnitSize.year)
+                        if (span < timeUnitSize.year)
-                                fmt = "%b";
+                            fmt = "%b";
-                            else
-                                fmt = "%b %y";
-                        }
                         else
-                            fmt = "%y";
+                            fmt = "%b %y";
-                        
+                    }
-                        return formatDate(d, fmt);
+                    else
-                    };
+                        fmt = "%y";
+                    
+                    return formatDate(d, fmt, axisOptions.monthNames);
+                };
             }
             else {
                 // pretty rounding of base-10 numbers
@@ -480,7 +526,6 @@
             axis.tickSize = size;
             axis.tickGenerator = generator;
             axis.tickSizeUnit = unit;
-            axis.datatype = axisOptions.datatype;
             if ($.isFunction(axisOptions.tickFormatter))
                 axis.tickFormatter = function (v, axis) { return "" + axisOptions.tickFormatter(v, axis); };
             else
@@ -500,10 +545,15 @@
         }
 
         function setTicks(axis, axisOptions) {
-            var i, v;
             axis.ticks = [];
-
+            
-            if (axisOptions.ticks) {
+            if (axisOptions.ticks == null)
+                axis.ticks = axis.tickGenerator(axis);
+            else if (typeof axisOptions.ticks == "number") {
+                if (axisOptions.ticks > 0)
+                    axis.ticks = axis.tickGenerator(axis);
+            }
+            else if (axisOptions.ticks) {
                 var ticks = axisOptions.ticks;
 
                 if ($.isFunction(ticks))
@@ -511,10 +561,11 @@
                     ticks = ticks({ min: axis.min, max: axis.max });
                 
                 // clean up the user-supplied ticks, copy them over
+                var i, v;
                 for (i = 0; i < ticks.length; ++i) {
                     var label = null;
                     var t = ticks[i];
-                    if (typeof(t) == "object") {
+                    if (typeof t == "object") {
                         v = t[0];
                         if (t.length > 1)
                             label = t[1];
@@ -526,10 +577,8 @@
                     axis.ticks[i] = { v: v, label: label };
                 }
             }
-            else
-                axis.ticks = axis.tickGenerator(axis);
 
-            if (axisOptions.autoscaleMargin != null) {
+            if (axisOptions.autoscaleMargin != null && axis.ticks.length > 0) {
                 if (axisOptions.min == null)
                     axis.min = axis.ticks[0].v;
                 if (axisOptions.max == null && axis.ticks.length > 1)
@@ -714,7 +763,7 @@
                 var sc = series[i].color;
                 if (sc != null) {
                     --neededColors;
-                    if (typeof(sc) == "number")
+                    if (typeof sc == "number")
                         assignedColors.push(sc);
                     else
                         usedColors.push(parseColor(series[i].color));
@@ -764,7 +813,7 @@
                     s.color = colors[colori].toString();
                     ++colori;
                 }
-                else if (typeof(s.color) == "number")
+                else if (typeof s.color == "number")
                     s.color = colors[s.color].toString();
 
                 // copy the rest
@@ -1435,42 +1484,6 @@
             return Math.abs(selection.second.x - selection.first.x) >= minSize &&
                 Math.abs(selection.second.y - selection.first.y) >= minSize;
         }
-
-        function formatDate(d, s) {
-            var leftPad = function(n) {
-                n = "" + n;
-                return n.length == 1 ? "0" + n : n;
-            };
-
-            var r = [];
-            var escape = false;
-            for (var i = 0; i < s.length; ++i) {
-                var c = s.charAt(i);
-
-                if (escape) {
-                    switch (c) {
-                    case 'h': c = "" + d.getHours(); break;
-                    case 'H': c = leftPad(d.getHours()); break;
-                    case 'M': c = leftPad(d.getMinutes()); break;
-                    case 'S': c = leftPad(d.getSeconds()); break;
-                    case 'd': c = "" + d.getDate(); break;
-                    case 'm': c = "" + (d.getMonth() + 1); break;
-                    case 'y': c = "" + d.getFullYear(); break;
-                    case 'b': c = "" + options.datatype.time.monthNames[d.getMonth()]; break;
-                    default: c;
-                    }
-                    r.push(c);
-                    escape = false;
-                }
-                else {
-                    if (c == "%")
-                        escape = true;
-                    else
-                        r.push(c);
-                }
-            }
-            return r.join("");
-        }
     }
     
     $.plot = function(target, data, options) {