TagCanvas - HTML5 Canvas Tag Cloud

TagCanvas is a Javascript class which will draw and animate a HTML5 canvas based tag cloud. I'm releasing it as open source under the LGPL v3 license. Below is an example.

Since the canvas is part of the HTML page, you can position things above or below it.

Background image

Note: the canvas element is not supported by Internet Explorer at the moment. However, the tag cloud above should be working in IE thanks to the ExplorerCanvas Javascript include file that translates canvas functions into IE's VML. It is a bit slow, but it does work. Mostly.

At the time of writing you must use the latest trunk version of ExplorerCanvas, as the current version in the project downloads area does not have the required text output support.

TagCanvas 1.3 is the first version to support image links - the first image found inside a link will be used instead of any text. Click the "Use image links" button below the example tag cloud to see it in action. Unfortunately image placement does not work properly with ExplorerCanvas, so IE is not supported.

Instructions

1. Download the javascript file from here: tagcanvas.js version 1.3 / [Minified],
or the jQuery plugin version here: jquery.tagcanvas.js version 1.3 / [Minified]

The minified versions of the files have been compressed using the Yahoo! YUI Compressor.

2. Include the file into your page:

<!--[if IE]><script type="text/javascript" src="excanvas.js"></script><![endif]-->
<script src="tagcanvas.js" type="text/javascript"></script>

or for the jQuery plugin:

 <!--[if IE]><script type="text/javascript" src="excanvas.js"></script><![endif]-->
 <script src="jquery-1.4.2.min.js" type="text/javascript"></script>
 <script src="jquery.tagcanvas.min.js" type="text/javascript"></script>

3. Add a canvas to your page, with the required width and height:

 <canvas width="300" height="300" id="myCanvas">
  <p>Anything in here will be replaced on browsers that support the canvas element</p>
 </canvas>

4. Put your tag links inside the canvas. They will be shown as-is on browsers that do not support the canvas element:

 <canvas width="300" height="300" id="myCanvas">
  <p>Anything in here will be replaced on browsers that support the canvas element</p>
  <ul>
   <li><a href="http://www.google.com" target="_blank">Google</a></li>
   <li><a href="/fish">Fish</a></li>
   <li><a href="/chips">Chips</a></li>
   <li><a href="/salt">Salt</a></li>
   <li><a href="/vinegar">Vinegar</a></li>
  </ul>
 </canvas>

You don't have to use ul and li, any link inside the canvas will be found.

As of version 1.3, the tag links may be outside the canvas and referenced by the id of a containing element - see below for details.

Note: if you are using excanvas for IE support, the tag links must be outside the canvas or they will not be found.

5. Initialise the TagCanvas class with the id of the canvas element when the page is loaded:

 <script type="text/javascript">
  window.onload = function() {
    try {
      TagCanvas.Start('myCanvas');
    } catch(e) {
      // in Internet Explorer there is no canvas!
      document.getElementById('myCanvasContainer').style.display = 'none';
    }
  };
 </script>

If you want to put the tag links outside the canvas, pass the id of the element containing the tags as an extra argument to the Start function:

      ...
      TagCanvas.Start('myCanvas','tagList');
      ...

To start TagCanvas using the jQuery plugin:

 <script type="text/javascript">
 $(document).ready(function() {
   if( ! $('#myCanvas').tagcanvas({
     textColour : '#ffffff',
     outlineThickness : 1,
     maxSpeed : 0.03,
     depth : 0.75
   })) {
     // TagCanvas failed to load
     $('#myCanvasContainer').hide();
   }
   // your other jQuery stuff here...
 });
 </script>

The tagcanvas() jQuery function also takes an optional argument for the id of the tag list container after the configuration options:

   ...
   $('#myCanvas').tagcanvas({
     depth : 0.75
   },'tagList');
   ...

The function returns true if the tag cloud is started successfully, false otherwise. This is so that you can handle the problem and replace the canvas with something else, or whatever you want to do.

Note that in the example above, the canvas container element is hidden when TagCanvas fails - the canvas itself may not respond to jQuery functions when running in a browser without canvas support.

6. That's it. The canvas is a part of the page, so you can style it with CSS - e.g. to add a border, margins, background, etc. The class will not draw a background onto the canvas, so the page background colour or image will show through.

Some options

There are a few options for modifying the way the cloud looks. Default values are shown in second column below:

Option	Default	Description
`maxSpeed`	`0.05`	Maximum speed of rotation
`decel`	`0.95`	Deceleration rate when mouse leaves canvas
`minBrightness`	`0.1`	Brightness of tags at farthest point (0.0-1.0)
`textColour`	`"#ff99ff"`	Colour of the tag text
`textHeight`	`15`	Height of the tag text font (in pixels)
`textFont`	`"Helvetica, Arial, sans-serif"`	Font family for the tag text
`outlineColour`	`"#ffff99"`	Colour of the box around the active tag
`outlineThickness`	`2`	Thickness of outline in pixels
`outlineOffset`	`5`	Distance of outline from text, in pixels
`pulsateTo`	`1.0`	Pulsate outline to this opacity (0.0-1.0)
`pulsateTime`	`3`	Pulse rate, in seconds per beat
`depth`	`0.5`	Controls the perspective (0.0-1.0)
`initial`	`null`	Initial rotation, with horizontal and vertical as an array, e.g. `[0.8,-0.3]`. Values are multiplied by maxSpeed.
`freezeActive`	`false`	Set to `true` to pause movement when a tag is highlighted.
`reverse`	`false`	Set to `true` to reverse direction of movement relative to mouse position.
`hideTags`	`false`	Set to `true` to automatically hide the tag list element if TagCanvas is started successfully.

To use these options for the stand-alone version, set the corresponding class variables before calling Start:

 <script type="text/javascript">
 window.onload = function() {
  TagCanvas.textColour = '#ffffff';
  TagCanvas.outlineColour = '#ff9999';
  TagCanvas.Start('myCanvas');
 };
 </script>

for the jQuery plugin, pass the relevant parameters into the tagcanvas function:

 <script type="text/javascript">
 $(document).ready(function() {
   $('#myCanvas').tagcanvas({
     textColour : '#ffffff',
     outlineColour : '#ff9999'
   });
 });
 </script>

What's new?

Version 1.3: adds some support for using explorer canvas, using image link tags and selection of the tag list by id. Since the source of the links can now be specified, this is also the first version to support being restarted.
Version 1.2: adds several new options: reverse, freezeActive, initial, pulsateTo and pulsateTime. The jQuery plugin version is also slightly smaller than the previous version.
Version 1.1.1: improves compatibility with older jQuery versions, and also copes better with FireFox 3.0.x. The older FireFox version supports the canvas element, but not in the same way as the newer version. For now the stand-alone version will emulate IE behaviour in FireFox 3.0.x by moving the contents of the canvas into a div and deleting the canvas. The jQuery version will return false and let you deal with the fallout.
Version 1.1: adds support for adjusting the perspective depth effect, the outline thickness and distance, and also uses a new algorithm to space the tags around the cloud better. This is also the first version available as a jQuery plugin as well as the stand-alone version.

Help!

As usual, this code doesn't come with any guarantees. But if you get stuck, find any bugs or have suggestions for improvements, please contact me at the usual address, graham(at)goat1000.com.