TagCanvas function reference

« Return to TagCanvas page

Skip to:

• Start
• Pause
• Resume
• Reload
• Update
• TagToFront
• RotateTag
• SetSpeed
• Delete

TagCanvas 2 has several functions, and the way they are called differs slightly between the stand-alone and jQuery versions. The buttons beneath the example cloud below each call one of the functions.

I've set the minSpeed option for this example cloud to make it easier to see the “Pause” and “Resume” buttons working.

A Javascript function updates some of the tags every 5 seconds so that you can see the effect of the “Reload” and “Update” buttons. “Reload” will reload the list, shuffling the tags again because the shuffleTags option is active. “Update” will reload the tags and change any tags that have been replaced.

The “TagToFront” and “RotateTag” buttons call their functions with a randomly-chosen tag to move. “RotateTag” is moving the chosen tag to lat: -60, lng: -60, which is near the bottom on the left. “SetSpeed” uses a random direction and speed. I haven't included a “Delete” button because it should be fairly obvious what that does.

Starting the cloud

The start functions start or restart the cloud animation. The canvas ID must be provided for the stand-alone version, though the tag list ID and options arguments are optional.

When the tag list ID is not provided, TagCanvas will use any links it finds inside the canvas element for the tags - though this will not work in IE versions before IE9.

// stand-alone version
TagCanvas.Start(canvasId, tagListId, options);

The jQuery version gets the canvas from the selector. The options and tag list arguments are both optional, and the tag list selection works in the same was as with the stand-alone version.

// jQuery plugin version
$(selector).tagcanvas(options, tagListId);

Calling the start functions again for the same canvas will restart the cloud. The tag list can be updated this way, and many of the options may be changed.

Pausing the cloud animation

The pause functions will stop the cloud animating. The script will continue receiving Javascript timer callbacks, but the animation code will be skipped. Calling the pause function again when a cloud is already paused will have no effect.

The stand-alone version is paused by calling the TagCanvas.Pause() function, passing in the ID of the canvas to be paused.

// stand-alone version
TagCanvas.Pause(canvasId);

The jQuery plugin version gets the canvas from the selector again, and uses the same tagcanvas() function, this time with the string "pause" passed in as an argument.

// jQuery plugin version
$(selector).tagcanvas("pause");

The jQuery selector may match multiple canvases - so you can pause some or all clouds on the page at once.

Resuming animation when paused

The resume functions continue the cloud animation with the same speed and direction as when it was paused. If the cloud is not paused, the resume function will have no effect.

The stand-alone version works by passing the canvas ID to the TagCanvas.Resume() function.

// stand-alone version
TagCanvas.Resume(canvasId);

The jQuery plugin version works similarly to the pause function, though the string "resume" must be passed to the tagcanvas() function instead of "pause".

// jQuery plugin version
$(selector).tagcanvas("resume");

This may also be used to resume multiple paused clouds by choosing a selector that includes the relevant canvases.

Reloading the list of tags

The reload function re-reads the list of tags from the same source, replacing the current list. It works in a similar way to calling Start again, but without all of the initialization code being run.

// stand-alone version
TagCanvas.Reload(canvasId);

The jQuery plugin version:

// jQuery plugin version
$(selector).tagcanvas("reload");

Updating the list of tags

The update function also reloads the list of tags, but keeps unchanged tags in (or close to) their current positions. This works by comparing the text content (or image source) of the tag and the href attribute. Tag weights and titles are updated without changing the tag positions.

// stand-alone version
TagCanvas.Update(canvasId);

The jQuery plugin version:

// jQuery plugin version
$(selector).tagcanvas("update");

In version 2.0, Update and the shuffleTags option didn't work well together - this has been fixed in version 2.1.

Bringing a tag to the front of the cloud

The TagToFront function moves a tag to the front of the cloud, bypassing the mouse or drag-based animation. You must specify which tag to bring to the front, using a list of options.

// stand-alone version
TagCanvas.TagToFront(canvasId, {id: "tag1"});

The jQuery plugin version:

// jQuery plugin version
$(selector).tagcanvas("tagtofront", {id: "tag1"});

There are a few options available to pass to the function. You must specify one of id, index or text for TagCanvas to find the tag to be moved.

The callback function is passed the relevant TagCanvas and Tag objects as arguments, and is called after the cloud has finished its movement.

Moving a tag to another position

TagToFront always moves the chosen tag to the front of the cloud - if you want the tag somewhere else, you must use the RotateTag function.

// stand-alone version
TagCanvas.RotateTag(canvasId, {id: "tag1", lat: 30, lng: -45});

The jQuery plugin version:

// jQuery plugin version
$(selector).tagcanvas("rotatetag", {id: "tag1", lat: 30, lng: -45});

The RotateTag function has a similar list of options, but you must also specify the lat and lng options for the position that you want the tag to be rotated to.

The lat option is the latitude of the destination - the up/down or north/south angle. The angle is in degrees, with 0° in the middle (or equator), 90° at the top (or north pole) and -90° at the bottom (the south pole).

The lng option is the longitude of the destination - the left/right or east/west angle.* This angle is also in degrees, with 0° at the front, 90° to the right/east, -90° to the left/west and both 180° and -180° at the back.

RotateTag and TagToFront both make use of the animTiming option to control the animation movement over time. The default option of “Smooth” uses a sine function to accelerate and decelerate at the start and end of the movement. The alternative “Linear” option rotates the cloud at a constant rate from start to finish.

Setting the cloud speed and direction

The initial option sets the speed and direction of the cloud movement when TagCanvas starts, but if you want to set it again after that you must use the SetSpeed function.

// stand-alone version
TagCanvas.SetSpeed(canvasId, [0.5, -0.25]);

The jQuery plugin version:

// jQuery plugin version
$(selector).tagcanvas("setspeed", [0.5, -0.25]);

The array argument is in the same format as the initial option, a multiple of the maxSpeed option in the X and Y directions. The cloud will maintain the new speed until it is changed by another function call or cursor input.

Removing the cloud

I added this function to help out people wanting to dynamically add and remove instances of TagCanvas on a page. It is easy enough to remove the canvas element from the DOM, but this leaves an instance of the TagCanvas class active, thus preventing you from reusing the same ID when you try to start it again.

// stand-alone version
TagCanvas.Delete(canvasId);

The jQuery plugin version:

// jQuery plugin version
$(selector).tagcanvas("delete");

The Delete function destroys the TagCanvas instance, leaving the canvas element intact on the page. What this means is that the contents of the canvas will be frozen at the time that the Delete function was called, no longer animating or accepting input. It is up to you to remove the canvas from the DOM using removeChild() or one of the jQuery functions for removing elements.

---

* Does anyone else find it odd that we usually put “left” before “right” and “east” before “west” when left is west and right is east? No, I guess not.

« Back to top of page Example pages »

Copyright © 2020, Goat 1000