User Documentation

Documentation


Product Details Changelog FAQs

User:Users template tag

The User:Users tag allows you to display a list of all your members. It's basically a Member List. For further flexibility, you can filter down your results by almost any method.

{exp:user:users} content {/exp:user:users}

Parameters

Most usual parameters are available here. Additionally, these exist as well:

alpha=

alpha="a"

This parameter allows you to filter down your results to users whose screen names begin with the specified letter(s).

dynamic=

dynamic="no"

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

dynamic_parameters=

dynamic_parameters="yes"

This parameter allows for dynamic sorting of your users list. Used in conjunction with the user_orderby and user_sort form fields.

group_id=

group_id="6|7|12"

This parameter allows you to filter your user list results by member group(s). Additionally, you can use not to exclude member groups you'd like to not show (not 4|7). Separate multiple values with the pipe character.

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.

member_id=

member_id="not 12|65|109"

This parameter allows you to filter out or display only specific members by specifying their member ID(s). You can hardcode a member ID, pass it through an embed, or grab it from the URI. Specify not to exclude specific members from displaying in the results. separate multiple member ID's with the pipe character.

orderby=

orderby="username|screen_name"

This parameter gives you the ability to control the order in which your users are ordered in the list. This parameter can accept multiple values separated by pipe. When multiples are provided, the sort parameter should match up with pipes. You can order by any variable that you can parse on as well as random.

offset=

offset="2"

This parameter will skip the first specified amount of users in the list. For example, if you specify 2, it will not show the first 2 users in the list.

paginate=

paginate="both"

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

role_id=

role_id="6|7|12"

This parameter allows you to filter your user list results by member roles(s). Additionally, you can use not to exclude member groups you'd like to not show (not 4|7). Separate multiple values with the pipe character.

search:member_field=

search:location="cal%"

This parameter works similar to the EE search:field= parameter and allows you to search your member fields for specific values to filter down your member results. Additionally, you can search on Screen Name and Usernames as well. % can be used as a wildcard, && can be used for inclusive (contains both/all values) searching, and the pipe character (|) can be used to specify multiple values. Examples:

  • search:your_field_name="IS_EMPTY" - members that have that field empty.
  • search:your_field_name="IS_NOT_EMPTY" - members that have a value for that field.
  • search:your_field_name="value" - members that contain the specified value for that field.
  • search:your_field_name="value|value2" - members that contain EITHER of the specified values for that field.
  • search:your_field_name="value&&value2" - members that contain BOTH of the specified values for that field.
  • search:your_field_name="%value%" - members that contain the specified value within words for that field (ex: %pp% would match apple, happy, etc).
  • search:your_field_name="%value" - members that contain the specified value within words for that field (ex: %nut% would match peanut, chestnut, etc).
  • search:your_field_name="value%" - members that contain the specified value within words for that field (ex: %pan% would match pants, pans, etc).
  • search:your_field_name="not value" - members that DO NOT contain the specified value for that field.
  • search:your_field_name="not value|value2" - members that DO NOT contain EITHER of the specified values for that field.
  • search:your_field_name="not value&&value2" - members that DO NOT contain BOTH of the specified values for that field.
  • search:your_field_name="not %value%" - members that DO NOT contain the specified value within words for that field (ex: %pp% would exclude apple, happy, etc).
  • search:your_field_name="not value|%value2%" - members that DO NOT contain a direct word match on the first value, or DO NOT contain the second value within any words in that field.
  • search:your_field_name="not value&&%value2%" - members that DO NOT contain a direct word match on the first value, AND DO NOT contain the second value within any words in that field.

sort=

sort="asc|desc"

You can sort by asc or desc. When multiples are provided in the orderby, this parameter should match up with pipes.

Variables

All User and Member variables are available here. Additionally, these exist as well:

abbr_

{abbr_your_member_field}

By prepending abbr_ to any custom member field, it returns a one letter abbreviation of the field value. For example, if you had a field named vehicle, you'd specify abbr_vehicle, and a value of Ford would parse as F.

count

{count}

This variable outputs the display order number for each user in the list results.

switch

{switch="style1|style2"}

This variable allows you to switch a CSS class back and fourth for all outputted results.

total_combined_posts

{total_combined_posts}

This variable shows the total combined posts for a given user.

total_results

{total_results}

This variable outputs the total number of results for that page. You would typically use this in a conditional statement.

absolute_count

{absolute_count}

This variable will return the absolute position number of each result within the list of results, including paginated results.

absolute_results

{absolute_results}

This variable will return the absolute total amount of results being displayed in the results, including paginated results. You would typically use this in a conditional statement.

Variable Pairs

The following variable pairs are available for use:

user_paginate

{user_paginate}
    <li>
        Page {user_current_page} of
        {user_total_pages} pages &nbsp;
        {user_pagination_links}
    </li>
{/user_paginate}

OR

{user_paginate}
<ul class="pagination">
    {user_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}
    {/user_pagination_links}
</ul>
{/user_paginate}

Pagination is available for this tag and works just like regular EE pagination, but each variable/variable pair is prepended with user_ (except for any variables and variable pairs inside of the user_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 conditional is available for use:

user_no_results

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

This conditional displays its contents when there are no results found.

Form Fields

The following form fields are available for use:

user_orderby

<select name="user_orderby">
    <option value="username">Username</option>
    <option value="screen_name">Screen Name</option>
    <option value="join_date">Join Date</option>
</select>

You can send orderby parameters through form submission using the POST method. The name of the field sent through POST needs to be user_orderby. This is the same as orderby and corresponds with user_sort. This only works when the dynamic_parameters parameter is set to yes. Also note that the order and sort values are saved to cookies so that the preference is remembered during pagination.

user_sort

<select name="user_sort">
    <option value="asc">Ascending</option>
    <option value="desc">Descending</option>
</select>

You can send sort parameters through form submission using the POST method. The name of the field sent through POST needs to be user_sort. This is the same as sort and corresponds with user_orderby. This only works when the dynamic_parameters parameter is set to yes. Also note that the order and sort values are saved to cookies so that the preference is remembered during pagination.

Examples

The following code will generate a very simple list of all site members with a link to their profiles (assuming your profile template is located at "users/profile"), along with pagination:

<ul>
{exp:user:users
    orderby="screen_name" sort="asc"
    limit="25"
    paginate="both"
}
    <li>
        <a href="{path='users/profile'}/{user_member_id}">{screen_name}</a>
    </li>
    {if user_no_results}
        <li>
            Sorry, no results were found.
        </li>
    {/if}
    {user_paginate}
        <li>
            Page {user_current_page} of {user_total_pages} pages
            {user_pagination_links}
        </li>
    {/user_paginate}
{/exp:user:users}
</ul>

The below example will generate a member list sorted by Total Entries by default. Above the list, is a form to Dynamically order/sort the list.

<form method="post" action="{path="user/users"}">
    <select name="user_orderby">
        <option value="username">Username</option>
        <option value="screen_name">Screen Name</option>
        <option value="join_date">Join Date</option>
    </select>
    <select name="user_sort">
        <option value="asc">Ascending</option>
        <option value="desc">Descending</option>
    </select>
    <input type="submit" value="Sort" />
</form>

{exp:user:users
    orderby="total_entries" sort="desc"
    dynamic_parameters="yes"
}
    <h3>{screen_name}</h3>
    <p>Favorite Food: {favorite_food}</p>
    <p>Total Entries: {total_entries}</p>
    <p>Join Date: {join_date format="%F %j, %Y"}</p>
{/exp:user:users}

Support

Having problems setting up and/or using User? 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.