Tag Documentation

Tag:Tags template tag

This template tag allows you to display the tags that have been assigned to a specific channel entry. In other words, when you're viewing a channel entry, this will show something like:

Tags: peanut, acorns, pants.

Please be sure NOT to name your custom tag field anything like tag or any of the other variables below, as it will conflict with the names.

Because Tag is a fieldtype, you can also display raw Tag data through traditional custom field parsing. All of the same parameters and variables are available, if you wish to use that approach.

{exp:tag:tags} content {/exp:tag:tags}

OR

{TAG_FIELD_NAME} content {/TAG_FIELD_NAME}

Parameters

The following parameters are available for use:

backspace=

backspace="2"

This parameter will remove the last specified amount of characters from your results. A typical usage for this would be to remove the last comma, should you choose to separate your tags by commas.

case=

case="lower"

This parameter allows you to control the case output of the tag name. Options are:

  • upper - ex: TAG NAME
  • lower - ex: tag name
  • title (default) - ex: Tag Name
  • sentence - ex: Tag name
  • none - outputs no case modification to the tag, but strips the websafe character from multi-word tags

dynamic=

dynamic="no"

By default, this tag will search the URI for an entry ID or URL title. This parameter allows you to disable this dynamic checking.

entry_id=

entry_id="{entry_id}"

This parameter is available should you need to hardcode a specific entry ID, or if you need to pass the entry ID through an embedded template. It is also necessary if you're using the Tag:Tags loop on a multi-entry page. Best practice is to always specify it. This parameter should NOT be used if you're using the custom field variable pair approach ({TAG_FIELD_NAME}{/TAG_FIELD_NAME}).

limit=

limit="10"

You can limit the number of tags returned by using this parameter.

orderby=

orderby="clicks"

This parameter allows you to set a specific order to your tags. Available methods are:

  • tag_name (default) - alphabetically order tags
  • clicks - total number of clicks each tag has received (loaded into Tag:Entries)
  • total_entries - total number of channel entries the tag has been assigned to
  • entry_date - date the tag was first created
  • edit_date - date that the tag was last used in an entry

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.

sort=

sort="asc"

This parameter allows you to control the output order. Available methods are ascending (asc) or descending (desc) order.

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. Separate 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. Separate multiples with the pipe character.

websafe_separator=

websafe_separator="-"

This parameter allows you to control the websafe separator character for multi-word tags in the URI. 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 from your Tag cloud 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 a Tag:Entries loop).

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.

tag_count

{tag_count}

Just like the {count} variable for Channel:Entries, this variable returns the relative position of the tag within the list of results. For example, if five tags are being displayed, then this variable will parse as 4 for the fourth tag displayed.

tag_total_results

{tag_total_results}

Just like the {total_results} variable for Channel:Entries, this variable will return the total amount of tag results being displayed. You would typically use this in a conditional statement.

websafe_tag

{websafe_tag}

This variable will be replaced by the 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 separator 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

Any of the variables above may be used as conditionals. Additionally, these exist as well:

tag_no_results

{if tag_no_results}
    Sorry, no tags are assigned to this entry.
{/if}

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

Examples

The below is a basic example of how you show the tags that belong to a channel entry (typically used within Channel:Entries or Tag:Entries template tags):

{exp:channel:entries}
    <h3>{title}</h3>
    <p>{body}</p>
    <p>Tags:
    {exp:tag:tags
        entry_id="{entry_id}"
        orderby="tag_name" sort="asc"
        limit="10"
        backspace="2"
    }
        <a href="{path='news/articles'}/{websafe_tag}">
            {tag} ({total_entries})
        </a>,
    {/exp:tag:tags}
    </p>
{/exp:channel:entries}

And here is a more advanced example that shows you how to use conditionals to prevent the Tags: wording and formatting from parsing if there's no results:

{exp:channel:entries}
    <h3>{title}</h3>
    <p>{body}</p>
    {exp:tag:tags
        entry_id="{entry_id}"
        orderby="tag_name" sort="asc"
        limit="10"
        backspace="2"
    }
        {if tag_count == "1"}
            <p>Tags:
        {/if}
                <a href="{path='news/articles'}/{websafe_tag}">
                    {tag} ({total_entries})
                </a>
        {if tag_count == tag_total_results}
            </p>
        {if:else}
            ,
        {/if}
    {/exp:tag:tags}
{/exp:channel:entries}

The below is an example of using the custom field variable pair approach:

{exp:channel:entries}
    <h3>{title}</h3>
    <p>{body}</p>
    <p>Tags:
    {TAG_FIELD_NAME
        orderby="tag_name" sort="asc"
        limit="10"
        backspace="2"
    }
        <a href="{path='news/articles'}/{websafe_tag}">
            {tag} ({total_entries})
        </a>,
    {/TAG_FIELD_NAME}
    </p>
{/exp:channel:entries}

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.