Tag 2.1 Cloud

So it's all well and good that you have collected all of these tags for your entries. You should display them somehow. Create a tag cloud. You can have tags clouds for either weblog entries or gallery entries.

The Cloud tag will produce a list of tags limited to the number you specify. The tags in this list will be the most used tags on your site. You can create a visual map of the relative ranking of the top tags by using variables provided to control font size.

The number of times the top tag is used establishes the top of the scale with 0 as the bottom. You specify the number of groups into which your tags will be sorted. Each of your top tags will be evaluated as to which group they belong in. They will be given a numerical ranking based on this.

For example, imagine you have 3 tags on your site; apple, orange and microsoft. You specify that you want to show a cloud with 3 groups. If apple is used 12 times, orange 7 and microsoft 1, the top of your scale will be 12. Apple will get the highest rank and the largest font. Microsoft will get the smallest ranking and font. Orange will get the middle font because it falls into the middle grouping. The range for falling into the lowest group would be 0-4. For the middle, 5-8. And for the top, 9-12.

Several parameters are used to control the behavior of the Cloud tag.

{exp:tag:cloud weblog="my_blog" groups="5" start="10" step="2" limit="40"} content {/exp:tag:cloud}

Parameters

author=

author="joe"

The 'author' parameter can filter tags by the user who entered them.

backspace=

backspace="3"

'backspace' will allow you to remove some number of characters from the end of your cloud.

category=

category="some_category"

You can limit tags in your cloud by those that belong to weblog entries of a specific category. This works both in gallery and weblog entry mode. You can supply a category number or a category name.

day_limit=

day_limit="5"

Filter your list of tags by those which have been used within the last number of days specified in the 'day_limit' parameter.

exclude=

exclude="burger|hammy|pimpkins"

You can exclude tags from the cloud by their name. For multiples, separate by pipe.

gallery=

gallery="my_gallery"

The cloud function allows you to display tags used either in weblog entries or gallery entries. When you specify a gallery in the 'gallery' parameter, the cloud function switches into gallery mode.

groups=

groups="5"

The 'groups' parameter tells the Tag module how many groups to divide your tags into.

limit=

limit="40"

The 'limit' parameter tells the Tag module how many tags to show in the tag cloud.

orderby=

orderby="total_entries"

The 'orderby' parameter allows you to order tags by count, total_entries, gallery_entries, weblog_entries, and tag_name. Only one value can be provided.

sort=

sort="asc"

The 'sort' parameter allows you to sort tags by 'asc' or 'desc'. The default is 'desc'.

start=

start="10"

The 'start' parameter tells the Tag module at what integer to start counting. This affects the 'size' variable which allows you to set the font size of each tag in your tag cloud.

start_on=

start_on="2007-04-13 3:00 PM"

The 'start_on' parameter filters the list of tags by those that were used after the date specified. Use the standard EE date formatting.

status=

status="open|closed"

You can specify the Status for both weblog and gallery entries. For multiples, use pipe.

step=

step="2"

The 'step' parameter tells the Tag module by what amount to increment the 'size' variable available below. This allows you to create greater differences in font sizes between tag groups.

stop_before=

stop_before="2007-06-1 5:00 PM"

The 'stop_before' parameter filters the list of tags by those that were used before the date specified. Use the standard EE date formatting.

weblog=

weblog="my_blog"

The 'weblog' parameter tells the Tag module from which weblog(s) to pull your tags. As tags have a weblog assignment based on the entries to which they have been added, they can be pulled by weblog. The 'weblog' parameter allows multiple tags separated by pipe. You can negate weblogs as well by adding 'not' to the beginning of a string of weblogs, like this: weblog="not images|scooter|ducks".

websafe_separator=

websafe_separator="+"

The 'websafe_separator' parameter allows you to control the websafe separator character for multi-word tags generated by the {websafe_tag}. Allowable characters are '+', '-', and '_'. The default is '+'.

Variables

The following variables are available in the cloud tag.

tag

{tag}

The 'tag' variable will be replaced by the tag name.

tag_name

{tag_name}

The 'tag_name' variable will be replaced by the tag name.

count

{count}

The 'count' variable will be replaced by the total number of instances of the tag acros weblog entries.

gallery_entries

{gallery_entries}

The 'gallery_entries' variable shows the total number of gallery entries for a tag.

position

{ position}

The 'position' variable will be replaced by the relative position of the tag within the sequence of tags in the cloud.

size

{size}

The 'size' variable is a representation of the relative rank of a given tag.

step

{step}

The 'step' variable relates to the step parameter. It helps you represent the breakpoints between groups of tags in their frequency of use. Usually people use it to set the font size of each tag in order to create that all important 'cloud' effect.

switch

{switch="styleOne|styleTwo"}

The 'switch' variable will be replaced alternately by each of the two values you provide, just as in other EE functions.

total_entries

{total_entries}

The 'total_entries' variable shows the total combined entries that a given tag has between gallery and weblog entries.

websafe_tag

{websafe_tag}

The 'websafe_tag' variable will be replaced by a tag name where spaces have been replaced by plus signs. You can also specify the websafe seperator character by using the websafe_separator parameter. This makes the tags more safe to place in a URL and for compatibility with web apps like Technorati and the like.

weblog_entries

{weblog_entries}

The 'weblog_entries' variable shows the total number of weblog entries for a tag.

Conditionals

All of the variables above are available for conditionals.

Examples

{exp:tag:cloud gallery="gallery" category="1" groups="10" step="3" limit="40"}
<a href="{path='tags/tag'}{websafe_tag}" title="{tag_name}" style="font-size:{step}px;">{tag}</a> 
{/exp:tag:cloud} {exp:tag:cloud weblog="my_blog" category="favorite_category" groups="10" step="3" limit="40"}
<a href="{path='tags/tag'}{websafe_tag}" title="{tag_name}" style="font-size:{step}px;">{tag}</a> 
{/exp:tag:cloud}

The path = ‘tags/tag’ part should be set to an existing template, or you should create a template called ‘tags’.
Be sure to keep the ‘tag’ part in the path.

Your ‘tags’ template should follow the guidelines of the Tag 2.1 Entries documentation.