Flot Plugins – Easy Time Series Navigation

Over the last two summer breaks I have been working on projects that make use of the flot javascript plotting library.

Part of these projects required a bunch of extra functionality to be added to the standard flot release. I modulated some of the functionality in to flot plugins. By the end of my time playing around with flot I had a bunch of different plugins and have just made all of those public on github to stop them collecting dust!

Plugins developed (in order of interest):

• Heatmap graph type
• Event Graphic System
• Easy time series navigation
• Data Cacher
• Axis labels using Raphael.js
• Automated x-axis gap insertion
• Additional autoscale type
• Selectable series
• Customised time period labels

Over a series of blog posts I am going to describe what each plugin is and how it works and hopefully it comes in use for people at some stage.

Easy Time Series Navigation

Github Code
Live Example

The first plugin I am going to explain is the easy time series navigation plugin. The code can be found on github here.

It is developed for use with time series navigation graphs. By that, I mean graphs that can be dragged forward and back in time by clicking and dragging the mouse. This dragging capability is added using the navigation plugin that is included with the standard flot package.

The plugin makes it to trivial to snap to a current range in time. A time range can be either: hour, day, week, month or year. Moving forward and back in time for the given time range is also possible. This is useful if say, we wanted to view the next or previous week from the current graph position.

Here is a screenshot of a flot graph showing latency over time between Maxnet and Auckland University. A single week is shown because I clicked the ‘now’ button. Clicking ‘Week>>’ or ‘<<week’ would move forward and back in time respectively.

The plugin just adds the functionality for flot to alter the xaxis position based on the given range and axis number. The actual UI controls are up to you to implement 🙂

There are four public functions added to the flot API to bind your buttons to. I am just going to copy and paste the documentation from the script itself here to explain those.

The plugin does a bunch of funky time handling stuff that you won’t want to do yourself. The open source javascript date library, datejs, comes with some handy methods that make the code very clean.

Lets take snapping to a given year as an example. If it is not January then we need to move the time to the previous years January.  The Datejs ‘last’ method makes this trivial.

Then we need to move to the first day of January. There is conveniently a ‘moveToFirstDayOfMonth’ method. Finally, the end of the range needs to be one year after January 1st.

case "year":
  if (!startDate.is().january()) startDate.last().january();

  startDate.moveToFirstDayOfMonth().clearTime();
  end = 365 * MS_1DAY;
  break;

There are similar case blocks for the other range types. Then, the xaxis minimum value is set to the start date timestamp and the maximum is set to that value plus the end.

Note that it is possible to specify a time zone offset in the xaxis options.

// don't allow navigating beyond the current time
if (startDate.compareTo(new Date()) > 0) return { min: axis.min, max: axis.max  };

axis.min = startDate.getTime() + plot.getAxes().xaxis.options.tzOffset;
axis.max = axis.min + end;

plot.setupGrid();
plot.draw();

return { min: axis.min, max: axis.max };

Edit: I have added a basic example to show how the API could be included in your code. See the github examples folder.