Tag Documentation

Tag:Cloud template tag

This function creates a list or "cloud" of all tags in the database, and can be filtered down to specific Tag groups, channels, categories, and more. Furthermore, the tag cloud can be weighted through different methods, such as how many entries are assigned to them, or how many times they've been clicked.

If you wish to use the weighted cloud method: the number of times the highest ranked tag is used establishes the top of the scale with 0 as the bottom. You can specify the number of groups into which your tags will be sorted. Each of your tags will be evaluated as to which group they belong in. They will be given a numerical ranking based on this. CSS styling is then used to convert that number value into a font size.

For example, imagine you have 3 tags on your site: apple, orange and pie. You specify that you want to show a cloud with 3 groups. If apple is used 12 times, orange 7, and pie 1, the top of your scale will be 12. apple will get the highest rank and the largest font size. pie will get the smallest ranking and font size. 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.

{exp:tag:cloud} content {/exp:tag:cloud}

Parameters

The following parameters are available for use:

day_limit=

day_limit="5"

Using this parameter, you can filter your list of tags by those which have been used within the last number of days.

category=

category="12|15"

This parameter allows you to filter your results by tags that are associated to entries which in turn are associated to specified categories. You can specify a category ID or a category url_title. You can hardcode the value, pass it through an embed, or grab it from the URI. Seperate multiples with the pipe character.

exclude=

exclude="burger|hammy|pimpkins"

This parameter allows you to exclude tags from the list by the tag name. For multiples, separate by pipe character. Additionally, to exclude "LIKE" tags, use the % symbol as a wildcard. For example, exclude="%dog" would exclude a tag named sled dog.

fixed_order=

fixed_order="81|17|26|43"

This parameter allows you to filter down your tag results and set them into a fixed order by specifying ID's of tags. Seperate multiples with the pipe character.

groups=

groups="5"

This parameter tells the Tag cloud how many groups to divide your tags into. For example, if you specify 5, it will create 5 groups and place the tags into the appropriate group based on their ranking. This will determine the font size for each tag.

limit=

limit="20"

This parameter allows you to limit the number of tags displayed.

most_popular=

most_popular="30"

This parameter allows you to filter all tags by popularity before the orderby parameter kicks in. This means that you can show all of your most popular tags, then order them how you wish.

orderby=

orderby="total_entries"

This parameter allows you to order your tags by the method you wish. Available methods are:

  • count - total number of instances of each tag across channel entries, within the specified parameters.
  • clicks - number of times the tag can been clicked on.
  • total_entries - total number of instances of each tag across channel entries, regardless of status.
  • tag_name - the name of the tag (default).
  • random - random display order.

paginate=

paginate="both"

Pagination works just like it does in the Channel:Entries tag. When specified, and used in conjunction with the tag_paginate variable pair, pagination will display. Refer to Channel:Entries tag documentation for more information.

rank_by=

rank_by="clicks"

This parameter allows you to weigh your tags by clicks or entries. Default is entries. For example, if you specify clicks, it will weight the tags by the amount of "clicks" each tag has received.

sort=

sort="asc"

This parameter allows you to sort tags by ascending (asc) or descending (desc) order. Default is desc.

start=

start="10"

This parameter controls which integer of font size to start counting. This affects the size variable which sets the font size of each tag in your cloud.

step=

step="2"

This parameter controls the amount to increment the size variable. This allows you to create greater differences in font sizes between tag groups.

tag_id=

tag_id="not 12|82|48"

This parameter allows you to narrow down or filter the tag results in the list by specifing ID's of tags. Seperate multiples with the pipe character.

tag_name=

tag_name="not cheese|pies|corn"

This parameter allows you to narrow down or filter the tag results in the list by specifing names of tags. Seperate multiples with the pipe character.

tag_group_id=

tag_group_id="3"

This parameter allows you to narrow down or filter the tag results in the list by specifying the tag group ID. Seperate multiples with the pipe character.

tag_group_name=

tag_group_name="group1|group2"

This parameter allows you to narrow down or filter the tag results in the list by specifying the tag group short name. Seperate multiples with the pipe character.

websafe_separator=

websafe_separator="-"

This parameter allows you to control the websafe separator character for multi-word tags generated by the websafetag variable. Allowable characters are +, -, and *. The default is +. Be sure to use this parameter consistently throughout your site if you change from the default value of +. For example, if you're linking to your Tag:Entries page with - as your websafe separator, you'll need to add this same parameter with - as the value for your Tag:Entries* page. Otherwise results will NOT show correctly.

Variables

The following variables are available for use:

clicks

{clicks}

This variable will return the number of times each tag has been "clicked" (viewed in Tag:Entries loop).

count

{count}

This variable will return the total number of instances of each tag across channel entries, within the specified parameters. For example, specifying the status parameter would affect the count on this variable.

position

{ position}

This variable will return the relative position of the tag within the sequence of tags in the list.

size

{size}

This variable will return a numeric value of the relative rank of the tag within the sequence of tags in the list.

step

{step}

This variable relates to the step parameter. It helps you represent the breakpoints between groups of tags by their rank. The usual usage for this is to set the different font sizes of the tags to create the "cloud" effect.

switch

{switch="styleOne|styleTwo"}

This variable will alternately output each of the two values you provide. You would typically use this with with CSS.

tag

{tag}

This variable returns the tag name.

tag_id

{tag_id}

This variable parses the ID of a given tag. This variable would normally be used when creating a link for the tag, and if your tags contain special and/or foreign characters that would cause trouble being placed in the URI.

total_entries

{total_entries}

This variable shows the total number of channel entries that are assigned to each tag. It is not affected by the parameters specified. For example, specifying the status parameter would NOT affect the count on this variable.

total_entries_TAG_GROUP_ID

{total_entries_1}

This variable works like the total_entries variable, but it allows you to display the amount of entries that contain the given tag for the specified Tag group. It is not affected by the template parameters specified. For example, specifying the status parameter would NOT affect the count on this variable. To construct this variable, simply take totalentries and append the unique Tag group ID number to it.

total_entries_TAG_GROUP_SHORT_NAME

{total_entries_article_tags}

This variable works like the total_entries variable, but it allows you to display the amount of entries that contain the given tag for the specified Tag group. It is not affected by the template parameters specified. For example, specifying the status parameter would NOT affect the count on this variable. To construct this variable, simply take totalentries and append the unique Tag group short name to it.

total_results

{total_results}

This variable will return the total amount of tags results being displayed in the cloud. You would typically use this in a conditional statement.

websafe_tag

{websafe_tag}

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

Variable Pairs

The following variable pairs are available for use:

tag_paginate

{tag_paginate}
    <li>
        Page {tag_current_page} of
        {tag_total_pages} pages &nbsp;
        {tag_pagination_links}
    </li>
{/tag_paginate}

OR

{tag_paginate}
<ul class="pagination">
    {tag_pagination_links}
        {first_page}
            <li><a href="{pagination_url}">First</a></li>
        {/first_page}
        {previous_page}
            <li><a href="{pagination_url}">&laquo; Previous</a></li>
        {/previous_page}
        {page}
            <li{if current_page} class="active"{/if}><a href="{pagination_url}">{pagination_page_number}</a></li>
        {/page}
        {next_page}
            <li><a href="{pagination_url}">Next &raquo;</a></li>
        {/next_page}
        {last_page}
            <li><a href="{pagination_url}">Last</a></li>
        {/last_page}
    {/tag_pagination_links}
</ul>
{/tag_paginate}

Pagination is available for this tag and works just like regular EE pagination, but each variable/variable pair is prepended with tag_ (except for any variables and variable pairs inside of the tag_pagination_links variable pair). Used in conjunction with the paginate parameter.

Conditionals

In addition to most of the variables above being available for use as conditionals, the following conditionals is available for use:

tag_no_results

{if tag_no_results}
    Sorry, no results were found.
{/if}

This conditional displays it's contents when there are no results found.

Examples

Displaying tags in Cloud format

Below is a simple typical usage of the Tag Cloud in “cloud” format:

<div id="cloud">
{exp:tag:cloud
    channel="articles"
    rank_by="entries"
    start="15" groups="10" step="3"
    limit="25"
}
    <a href="{path='articles/by_tag'}/{websafe_tag}" style="font-size:{step}px;">
        {tag}
    </a>
{/exp:tag:cloud}
</div>

Displaying tags in List format

You could also display your tags in list form if you wish. You can also keep the font size weighting in place, but is removed from the example below:

<ul>
{exp:tag:cloud
    channel="articles"
    limit="25"
    paginate="bottom"
}
    <li>
        <a href="{path='articles/by_tag'}/{websafe_tag}">{tag}</a>
        ({total_entries})
    </li>
{tag_paginate}
    <li>
        Page {tag_current_page} of {tag_total_pages}.
        {tag_pagination_links}
    </li>
{/tag_paginate}
{/exp:tag:cloud}
</ul>

Support

Having problems setting up and/or using Tag? Support is offered from 10am to 4pm EST weekdays. Send us an email at help@eeharbor.com and we will respond as quickly as we can.