Tag Documentation

Tag:Related_Entries template tag

Tag is more than just a content tagging add-on. It is an intuitive relationship tool. Once you've assigned tags to your entries, you can then display in your templates the relationships that emerge within this data. This template tag allows you to display a list of other channel entries that share one or more of the same tags as the main entry contains.

For example, if the main entry you're viewing contains the tags: peanut, acorns, and pants, any other entries that contain one or more of those tags will show. Additionally, these related entries can be ranked by most tag matches. If an entry contains 2 of those tags, it will be ranked higher than entries that contain just 1 match to those tags.

{exp:tag:related_entries} content {/exp:tag:related_entries}

Diagram: Relationships with Tag

Parameters

Most of the parameters available in the Channel:Entries tag are available here. Additionally, these exist as well:

entry_id=

entry_id="{entry_id}"

Tag:Related_Entries will normally read the entry ID dynamically when viewing a single entry page. However, if you wish to use this on a multiple entry page, and/or use embeds, this parameter is available for use.

exclude=

exclude="tacos|nachos|peanuts"

This parameter allows you to exclude entries based on specified tags from showing up. For multiples, separate by pipe character. Additionally, to exclude "LIKE" tags, use the % symbol as a wildcard. For example, exclude="%dog" would exclude the sled dog tag.

limit=

limit="5"

This parameter allows you to set a maximum amount of results to display for this tag.

orderby=

orderby="relevance"

This parameter lets you specify the order in which you'd like your entries to display. Most Channel:Entries options are available here. Additionally, you can use relevance. When specifying relevance, it will order your entries by amount of tags that match. For example, if an entry has 3 matching tags, and two other entries have only 1 matching tag, the entry with 3 matching tags will rank higher than the others. Also, specifying relevance enables the tag_relevance and tag_relevance_percent variables.

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_limit=

rank_limit="5"

This parameter ranks the tags that belong to the primary entry of the page. It chooses the top ranked of those tags, limiting that selection by the number you provide in the parameter. Then pulls related entries that have those top ranked tags in common with the primary entry of the page.

Tags can be ranked by how often they are used, by how often they are clicked or both. See the rank_method parameter.

rank_method=

rank_method="clicks|total_entries"

A tag can be ranked by how often it is clicked on the site, by how many entries use it, or both. You can show related entries by tag rank and you can establish the ranking method using this parameter. Allowed values are clicks and total_entries. You can indicate both by joining the two with the pipe character.

tag_group_id=

tag_group_id="3"

This parameter allows you to narrow down or filter the results 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 results by specifying the tag group short name. Seperate multiples with the pipe character.

url_title=

url_title="{segment_3}"

Tag:Related_Entries will normally read the entry ID or URL title dynamically when viewing a single entry page. However, if you wish to use this on a multiple entry page, and/or use embeds, this parameter is available for use.

Variables

Most of the variables available in the Channel:Entries loop are available here. Additionally, these exist as well:

Note: When using in a single entry page, be sure to place your Tag:Related_Entries loop outside of the Channel:Entries loop, as the variables are shared and will collide. If it's absolutely necessary to place the Tag:Related_Entries loop inside of the Channel:Entries loop, be sure to use an embed and pass the entry ID over.

tag_relevance

{tag_relevance}

This variable displays the amount of tag matches the related entry and the main entry have. This variable only works with the orderby="relevance" parameter specified.

tag_relevance_percent

{tag_relevance_percent}

This variable displays the percentage of the amount of tag matches the related entry and the main entry have. This variable only works with the orderby="relevance" parameter specified.

Variable Pairs

Most of the variable pairs available in the Channel:Entries loop are available here. Additionally, 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 conditionals available in the Channel:Entries tag, the following conditionals are 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

Below is a basic example of using the Tag:Related_Entries loop outside of the Channel:Entries loop on a single entry view template, using relevance:

{exp:tag:related_entries
    channel="articles"
    orderby="relevance" sort="desc"
    limit="5"
    paginate="bottom"
}

    <h3><a href="{url_title_path="articles/entry"}">{title}</a></h3>
    <p>Relevance: {tag_relevance} matches ({tag_relevance_percent}%)</p>
    <p>{summary}</p>

    {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}

{/exp:tag:related_entries}

Below is an example of using the Related Entries loop inside of the Channel:Entries loop through an embed in a single entry view or multiple entry page template. Something to note is that the variables of Channel:Entries and Tag:Related_Entries are shared, so placing the Tag:Related_Entries loop directly into the Channel:Entries loop would cause variable collisions. The only way around this is to use an embed:

Main Template:

{exp:channel:entries}
    <h2><a href="{url_title_path="articles/entry"}">{title}</a></h2>
    <p>{body}</p>
    {embed="path_to/embed_template" entry_id="{entry_id}"}
{/exp:channel:entries}

Embedded Template:

<ul>
    {exp:tag:related_entries
        channel="articles"
        entry_id="{embed:entry_id}"
        orderby="title" sort="asc"
        limit="5"
    }
        <li><a href="{url_title_path="articles/entry"}">{title}</a></li>
    {/exp:tag:related_entries}
</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.