User:Roles_Entries template tag

The User:Roles_Entries tag mimics the Channel:Entries tag, but enables you to filter channel entries by entries that use the User Roles fieldtype. Using this tag, entries that do not have a User Roles fieldtype or any permissions there in, will not be shown.

{exp:user:roles_entries} content {/exp:user:roles_entries}

• Parameters
• Variables
• Variable Pairs
• Conditionals
• Examples

Parameters

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

• dynamic
• entry_id
• limit
• orderby
• paginate
• restrict_to_roles
• restrict_to_user_roles
• sort

dynamic=

dynamic="no"

This parameter is available to stop the loop from looking into the URI for an ID of any type.

entry_id

entry_id="6|7|8"

This parameter differs from the normal Channel:Entries entry_id="" paramater in that it will make a pre-defined list of entries for Roles Entries to filter from. If the entry ID's in this parameter do not have roles that match the restrictions lined out on the other parameters on this tag, the entries will not show. This is solely for a further level of filtering entries.

limit=

limit="15"

This parameter controls how many results will be outputted. The limit will default to 100 entries if a value is not specified.

orderby=

orderby="username|screen_name"

This parameter gives you the ability to control the order in which your users are ordered in the list. You can order by any variable that you can parse on as well as random.

paginate=

paginate="both"

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

restrict_to_roles

restrict_to_roles="monkeys|pants_wearers|honey_dippers"

This parameter allows you to manually specify roles to restrict entries to (by default all roles will be shown, if not specified). If using multiple roles, separate with the pipe character. This does not take into account the current user's available roles - only the roles listed in this parameter. If you wish for entries to only show to users that have matching roles assigned to them, see the restrict_to_user_roles parameter.

Role names must match the short name as defined in the User control panel. When specifying role names, this is NOT inclusive. It will only check to see if any of the roles specified in this parameter match any of the roles assigned to entries, no matter how complex they may be, or how many lesser or extra roles they contain from what it specified here.

restrict_to_user_roles

restrict_to_user_roles="yes"

This parameter allows you to specify that the logged in user's available roles will be used to filter entries that have been assigned some or all of the same roles the user has. Default is no. When using in conjunction with the restrict_to_roles parameter, it will check to see if the logged in user fully matches any of the sets of roles for each entry. So for example, if Entry X has the roles Monkeys AND Pants Wearers, OR Honey Dippers, but the user's assigned roles are Monkeys and Bench Warmers, they will not see Entry X because they don't have both Monkeys AND Pants Wearers roles assigned to them. They would need to also have the Pants Wearers role assigned to them.

sort=

sort="asc"

You can sort by asc or desc.

Variables

Most of the variables available in the Channel:Entries loop are available here.

Variable Pairs

The following variable pairs are available for use:

• paginate

paginate

{paginate}
    <li>
        Page {current_page} of
        {total_pages} pages &nbsp;
        {pagination_links}
    </li>
{/paginate}

OR

{paginate}
<ul class="pagination">
    {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}
    {/pagination_links}
</ul>
{/paginate}

Pagination is available for this tag and works just like regular EE pagination. Used in conjunction with the paginate parameter.

Conditionals

The variables above are available as conditionals. Additionally, these exist as well:

• user_no_results

user_no_results

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

This conditional displays its contents when there are no results.

Examples

Below is a basic example of how your User:Roles_Entries template might look.

<ul>
{exp:user:roles_entries
    channel="main"
    restrict_to_roles="monkeys|pants_wearers|honey_dippers"
    restrict_to_user_roles="yes"
}
    <li><a href="{url_title_path='comments'}">{title}</a></li>
    {if user_no_results}
        <li>No results were found.</li>
    {/if}
{/exp:user:roles_entries}
<ul>