TagCanvas installation
This page describes all the steps that are required to get a TagCanvas cloud working on your page, using either the stand-alone or jQuery plugin version. If you are too impatient to read all of this, you can skip to the examples page for full working source code.
Installation Instructions
1. Download the javascript file of your choice from the main TagCanvas page and copy it to your website. If your site already uses jQuery then I recommend using the plugin version, otherwise the stand-alone version will produce the same results without the need to install jQuery too.
2. Include the Javascript files into your page:
<!--[if lt IE 9]><script type="text/javascript" src="excanvas.js"></script><![endif]-->
<script src="tagcanvas.min.js" type="text/javascript"></script>
or for the jQuery plugin:
<!--[if lt IE 9]><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>
The HTML comment uses a syntax recognised by Internet Explorer called
conditional comments to include the excanvas.js script for
versions of IE lower than version 9.
The main jQuery file must be included before the TagCanvas plugin. The plugin should work with all jQuery versions from 1.3 up (and possibly some earlier versions).
3. Add a canvas to your page, with the required width and height:
<div id="myCanvasContainer">
<canvas width="300" height="300" id="myCanvas">
<p>Anything in here will be replaced on browsers that support the canvas element</p>
</canvas>
</div>
The width and height attributes are always in pixels, the same as with an
<img> element. Don't use CSS to change the size of the
canvas, as this will distort its shape and mess up the mouse position
calculations.
4a. If you don't care about supporting Internet Explorer versions up to 8, put your tag links inside the canvas. They will be shown as-is on browsers that do not support the canvas element:
<div id="myCanvasContainer">
<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>
</div>
You don't have to use ul and li, any link
inside the canvas will be found. The tag links may be outside the canvas
and referenced by the id of a containing element - see
below for details.
4b. If you DO want to support IE versions below 9, the tag links MUST BE OUTSIDE the canvas element or they can not be found by the TagCanvas script:
<div id="myCanvasContainer">
<canvas width="300" height="300" id="myCanvas">
<p>In Internet Explorer versions up to 8, things inside the canvas are inaccessible!</p>
</canvas>
</div>
<div id="tags">
<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>
</div>— and this means you must pass the ID of the container your tags are in to TagCanvas (in this example the 'tags' div) as described below.
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) {
// something went wrong, hide the canvas container
document.getElementById('myCanvasContainer').style.display = 'none';
}
};
</script>
If your tag links are not inside 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, which goes 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 (the
div with the ID of myCanvasContainer) 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 itself is a part of the page, so you can style it with CSS - e.g. to add a border, margins, background, etc. TagCanvas does not draw a background onto the canvas, so the page background colour or image will show through.
The individual tags are drawn on the canvas using drawing functions, so they cannot be styled using CSS. Several options are supplied for specifying how they should be drawn, listed on the options page.