Skip to content
stef edited this page Sep 13, 2010 · 27 revisions

jQuery UI Timecloud

A jQuery based visualization widget, displaying animated tagclouds over time.

Copyright © 2008-2009 Stefan Marsiske <my name at>

Dual licensed under the MIT and GPLv3 licenses.


v1.2 – 2009/03/02

  • multiple timeclouds on the same page should be possible
  • support for new versions of dependencies
  • refactoring and bugfixes

v1.1.1 – 2008/12/01

  • possibility to set initial timeframe position from the end
  • graphical slider for speed control
  • small fixes (code&css)

v1.1 – 2008/11/28

  • ie8 support via excanvas
  • UI Overhaul
  • Mousewheel support
  • enhanced delicious example
  • refactored code
  • min/max points marked left of sparklines


All these dependencies are packaged in the include/ directory of the sources.





  • a general example of visualizing subversion development activities is here
  • another example visualizing your delicious tags over time is also in the download.

Easy code

Timecloud displays an animated tagcloud. You can attach your timecloud as easily as this:



Timecloud has quite a few options to set, these can be passed like the ‘timecloud’ parameter in the above example. The following options are available for controlling the behavious and looks of the timecloud:

  • timecloud this contains the sparse timecloud data, mandatory
  • start (0) defines index of first frame to render in the above timecloud list, negative values position from the end
  • winSize (30) sets the initial number of days to capture in a frame
  • steps (1) defines how many days to skip from frame to frame
  • timeout (200us) sets the interval between frames in animation
  • playBack (false) whether to play backwards or forwards
  • play (false) whether to play/pause the animation
  • urlprefix see urlpostfix
  • urlpostfix together with urlprefix and the tag, you can compose an URL which is used as a target link for the tags in the tagcloud.
  • sparklineStyle defines the layout for the sparklines, defaults to:
   { type:'line', lineColor:'Navy', height:'30px', chartRangeMin: '0' }


Timecloud expects the data to be displayed in the ‘timecloud’ option:


Here ‘data’ is a JSON encoded list of lists containing and sorted by days and weighted words (tags). It looks like this:


or a live example:


One nice thing is, that the list needn’t be consecutive, only sorted in ascending order. All missing dates will be treated as not containing any tags. This is handy when doing SQL queries over timelogs for example, you don’t have entries for every day.

An example how to prepare such a data-set is explained later.

For making all this run, we need to include the dependencies in the

section of our document.
      <!--[if IE]><script language="javascript" type="text/javascript" src="../../include/excanvas.js"></script><![endif]-->
      <script type="text/javascript" charset="utf-8" src="include/jquery.js"></script>
      <script type="text/javascript" charset="utf-8" src="include/jquery.sparkline.js" ></script>
      <script type="text/javascript" charset="utf-8" src="include/jquery-ui-p.min.js"></script>
      <script type="text/javascript" charset="utf-8" src="include/jquery.event.wheel.js"></script>
      <script type="text/javascript" charset="utf-8" src="include/tagcloud.js"></script>
      <script type="text/javascript" charset="utf-8" src="timecloud.js"></script>

we have also a stylesheet for our widget:

A live example would be a small PHP script which fetches all your delicious bookmarks, and spits out a list of tags attached to the days they were used:

      <script type="text/javascript">
         $(document).ready(function() {
            var query="delicious.php?op=timecloud";
            $.getJSON(query,function(data) { $("#loading").hide(); $("#timecloud").timecloud({"timecloud":data}); });

The last thing we need, is some element we can attach our timecloud to:

      <div id="timecloud" /> 

for complete examples, see the source there is a live delicious timecloud and a subversion author timecloud example.

How to develop a dataset suitable for a timecloud.

Below I outline a short procedure to create a data set suitable for displaying as a timecloud. The below however should mostly work on UNIX systems only. In our example we try to create a timecloud for our historical data in subversion. We will display the weight of the developers in a certain timeframe for a project. For all files consult the contents of the examples/subversion directory in the sources.

remember the format?


that’s what we’re going to produce now. with a twist, we will make it into a javascript variable, so that you can simply include this file in you html and have the data readily available. Imagine we have a list, like this

   2008-11-21 TAG1
   2008-11-21 TAG2
   2008-11-21 TAG2

in the examples the subversion/utils directory contains an svn2tc.xsl template, which produces such out put if applied on subversion historical logs:

   svn log --xml --verbose | xsltproc svn2tc.xsl - |

(note, that all lines end with pipes, like it would be one long line)
If we would like to display the tags weight over the days, we need this data to be sorted by ascending dates:

   sort -n |

furthermore we would like to have the sum of each tag and each tag only once in our list:

   uniq -c -f 1 |

so we invoke the UNIX uniq command and tell it to count the distinct tags per day. unfortunately it gives us such an output:

         1 2008-11-21 TAG1
         2 2008-11-21 TAG2

which needs to be converted into our list format above, for which i resorted to some awk. To put it short the tool below takes any file similar to the uniq output and converts it to a javascript array variable:

   var timeclouddata=[["2008-11-21", [["TAG1", "1"],["TAG2", "2"]]]];

this you can then pass to


have fun,