Friends 1.x

Legacy documentation for Friends 1.x.

The Friends:Members function allows you to display a list of all your members. Basically, it allows you to display a member list. The general usage for this is to create a list for your users to look at and add/invite other users as friends as they please.

This function can also serve as an individual profile page for viewing more information about a given member.

{exp:friends:members} content {/exp:friends:members}

Parameters

The following parameters are available for use:

dynamic=

dynamic="off"

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

limit=

limit="10"

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

member_id=

member_id="{segment_3}"

This parameter allows you to view an individual profile of a member by specifying their member ID. You can hardcode a member ID, pass it through an embed, grab it from the URI, or specify CURRENT_USER to display the profile of the currently logged in user. If neither the member_id or username parameter is specified, the Members loop will display a list of all members.

member_group_id=

member_group_id="5|6|9"

This parameter allows you to filter the list of members by one or more member group ID's. Separate multiple groups with the pipe (|) character.

orderby=

orderby="screen_name"

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

paginate=

paginate="both"

This parameter allows you to control where the pagination will display. Options are top, bottom, or both. Used in conjunction with the friends_paginate variable pair.

search_screen_name=

search_screen_name="ja"

This parameter allows you to filter the member list by those members who share the same first few letters of their screen name. For example, if you specify ja in the parameter, your results may be Jason, Janet, Jared, etc. It's not necessary to specify this parameter though. If you have an additional segment in the URI named screen_name, followed by a value, the search will be performed automatically, as long as the dynamic parameter is NOT set to off.

search_username=

search_username="fur"

This parameter allows you to filter the member list by those members who share the same first few letters of their username. For example, if you specify fur in the parameter, your results may be furly, furby, furnace_eater, etc. It's not necessary to specify this parameter though. If you have an additional segment in the URI named username, followed by a value, the search will be performed automatically, as long as the dynamic parameter is NOT set to off.

sort=

sort="desc"

You can sort by asc or desc.

username=

username="{segment_3}"

This parameter allows you to view an individual profile of a member by specifying their username. You can hardcode a username, pass it through an embed, grab it from the URI, or specify CURRENT_USER to display the profile of the currently logged in user. If neither the member_id or username parameter is specified, the Members loop will display a list of all members.

Variables

All standard and custom member fields are available for use, including several extra variables. To parse these member fields, prepend the variables with friends_. So to construct these variables, simply use friends_ + member_field_name.

friends_aol_im

{friends_aol_im}

This variable outputs the friends AOL instant messenger ID if they've provided one.

friends_avatar_filename

{friends_avatar_filename}

This variable outputs the upload directory path, filename, and file extension of the friends avatar if they have one (ex: uploads/avatar_1.jpg).

friends_avatar_height

{friends_avatar_height}

This variable outputs the height of the friends avatar (ex: 60).

friends_avatar_url

{friends_avatar_url}

This variable outputs the complete path to the avatar, including the avatar directory path and filename (ex: http://www.yoursite.com/images/avatars/uploads/avatar_1.jpg).

friends_avatar_width

{friends_avatar_width}

This variable outputs the width of the friends avatar (ex: 80).

friends_bday_d

{friends_bday_d}

This variable outputs the friends Birthday day.

friends_bday_m

{friends_bday_m}

This variable outputs the friends Birthday month.

friends_bday_y

{friends_bday_y}

This variable outputs the friends Birthday year.

friends_birthday

{friends_birthday format="%F %j, %Y"}

This variable outputs a timestamp value of the birth date and allows you to display any date formatting of your choice.

friends_bio

{friends_bio}

This variable outputs the friends bio.

friends_count

{friends_count}

This variable outputs the display order number for each result in the list of users. Available within Friends:Members loop.

friends_daylight_savings

{friends_daylight_savings}

This variable outputs a y or n value of whether or not the friend is observing daylight savings time.

Note: ExpressionEngine 2.6 and later do not have Daylight Savings time settings and this param is no longer supported after ExpressionEngine 2.5.5.

friends_email

{friends_email}

This variable outputs the friends email address.

friends_entry_date

{friends_entry_date format="%F %j, %Y"}

This variable displays the date of when the friend request or confirm occurred. This variable will only parse correctly for users that have some type of relationship to the currently logged in user, so it's best to place this into a conditional.

friends_icq

{friends_icq}

This variable outputs the friends ICQ instant messenger ID if they've provided one.

friends_interests

{friends_interests}

This variable outputs the data a friend has for the Interests field.

friends_ip_address

{friends_ip_address}

This variable outputs the IP address the friend last accessed the website with.

friends_join_date

{friends_join_date format="%F %j, %Y"}

This variable outputs the friends join date.

friends_last_activity

{friends_last_activity format="%F %j, %Y"}

This variable outputs the last time the friend was active.

friends_last_bulletin_date

{friends_last_bulletin_date format="%F %j, %Y"}

This variable outputs the last time the friend posted a bulletin.

friends_last_comment_date

{friends_last_comment_date format="%F %j, %Y"}

This variable outputs the last time the friend posted a comment.

friends_last_email_date

{friends_last_email_date format="%F %j, %Y"}

This variable outputs the last time the friend sent an email via the EE email function.

friends_last_entry_date

{friends_last_entry_date format="%F %j, %Y"}

This variable outputs the last time the friend posted a channel entry.

friends_last_forum_post_date

{friends_last_forum_post_date format="%F %j, %Y"}

This variable outputs the last time the friend posted in the forums.

friends_last_rating_date

{friends_last_rating_date format="%F %j, %Y"}

This variable outputs the last time the friend submitted a rating (with Rating module).

friends_last_view_bulletins

{friends_last_view_bulletins format="%F %j, %Y"}

This variable outputs the last time the friend viewed a bulletin.

friends_last_visit

{friends_last_visit format="%F %j, %Y"}

This variable outputs the last time the friend visited the website.

friends_location

{friends_location}

This variable outputs the data a friend has for the Location field.

friends_member_id

{friends_member_id}

This variable outputs the friends member ID.

friends_member_group_id

{friends_member_group_id}

This variable outputs the group ID the friend belongs to.

friends_member_group_title

{friends_member_group_title}

This variable outputs the group name the friend belongs to.

friends_msn_im

{friends_msn_im}

This variable outputs the friends MSN instant messenger ID if they've provided one.

friends_occupation

{friends_occupation}

This variable outputs the data a friend has for the Occupation field.

friends_photo_filename

{friends_photo_filename}

This variable outputs the upload directory path, filename, and file extension of the friends member photo if they have one (ex: uploads/photo_1.jpg).

friends_photo_height

{friends_photo_height}

This variable outputs the height of the friends member photo (ex: 60).

friends_photo_url

{friends_photo_url}

This variable outputs the complete path to the member photo, including the member photo directory path and filename (ex: http://www.yoursite.com/images/member_photos/uploads/photo_1.jpg).

friends_photo_width

{friends_photo_width}

This variable outputs the width of the friends member photo (ex: 80).

friends_private_messages

{friends_private_messages}

This variable outputs the amount of privates messages the friend has.

friends_profile_views

{friends_profile_views}

This variable shows the number of times that the friends profile has been viewed. Use of the User module User:Stats function triggers the counting of a profile view. When you view your own profile it doesn't count.

friends_reciprocal

{friends_reciprocal}

This variable determines whether or not a given friend in your list also has you as a friend in their list. It will return either y or n. You would normally use this as a conditional.

friends_screen_name

{friends_screen_name}

This variable outputs the friends screen name.

friends_signature

{friends_signature}

This variable outputs the text value of the friends signature.

friends_sig_img_filename

{friends_sig_img_filename}

This variable outputs the upload directory path, filename, and file extension of the friends signature image if they have one (ex: uploads/signature_1.jpg).

friends_sig_img_height

{friends_sig_img_height}

This variable outputs the height of the friends signature image (ex: 60).

friends_sig_img_url

{friends_sig_img_url}

This variable outputs the complete path to the signature image, including the signature images directory path and filename (ex: http://www.yoursite.com/images/signature_attachments/uploads/signature_1.jpg).

friends_sig_img_width

{friends_sig_img_width}

This variable outputs the width of the friends signature image (ex: 80).

friends_switch

{friends_switch="one|two"}

This variable allows you to switch a CSS class back and fourth for all outputed results. Available within Friends:Members loop.

friends_time_format

{friends_time_format}

This variable shows the friends time formating (ex: us, ca, uk).

friends_timezone

{friends_timezone}

This variable shows the friends timezone settings.

friends_total_blocked_friends

{friends_total_blocked_friends}

This variable displays the total amount of members a given user has blocked.

friends_total_combined_posts

{friends_total_combined_posts}

This variable displays the friends total amount of combined posts (ex: forums, channel entries, comments, etc).

friends_total_comments

{friends_total_comments}

This variable displays the friends total amount of comments.

friends_total_entries

{friends_total_entries}

This variable displays the friends total amount of channel entries.

friends_total_forum_posts

{friends_total_forum_posts}

This variable displays the friends total amount of forums posts.

friends_total_forum_topics

{friends_total_forum_topics}

This variable displays the friends total amount of forums topics.

friends_total_friends

{friends_total_friends}

This variable displays the total amount of friends a member has. It does not take reciprocality into factor here. So if a member has 5 confirmed friends, and 3 unconfirmed friend requests, it will evaluate as 8. Use the friends_total_reciprocal_friends variable to filter out unconfirmed friend requests from the count.

friends_total_hugs

{friends_total_hugs}

This variable displays the total amount of times a member has been hugged, using the Friends:Hug function.

friends_total_ratings

{friends_total_ratings}

This variable displays the total amount of ratings submitted by the friend (with Rating add-on).

friends_total_reciprocal_friends

{friends_total_reciprocal_friends}

This variable displays the total amount of reciprocal friends a member has. Any unconfirmed friend requests are not factored in here. So if a member has 5 confirmed friends, and 3 unconfirmed friend requests, it will evaluate as 5. Use the friends_total_friends variable to include unconfirmed friend requests in the count.

friends_total_results

{friends_total_results}

This variable outputs the total amount of results outputted in your list. Available within Friends:Members loop.

friends_url

{friends_url}

This variable outputs the data a friend has for the URL field.

friends_username

{friends_username}

This variable outputs the friends username.

friends_yahoo_im

{friends_yahoo_im}

This variable outputs the friends Yahoo instant messenger ID if they've provided one.

friends_custom_member_field

{friends_custom_member_field}

All of custom member fields are available for use. To parse your custom member fields, prepend the variables with friends_. So to construct these variables, simply use friends_ + custom_member_field_short_name (Ex: friends_ + favorite_book = friends_favorite_book).

Variable Pairs

The following variable pairs are available for use:

friends_paginate

{friends_paginate}
    Page {friends_current_page} of {friends_total_pages} pages
    {friends_pagination_links}
{/friends_paginate}

Pagination is available for this tag and works just like regular pagination, but each variable is prepended with friends_. Used in conjunction with the paginate parameter.

Conditionals

You can run conditionals on any of the single variables available above. Additionally, these are available:

if friend

{if friend == "y"}
    This member is my friend.
{/if}

This conditional determines whether or not a given member in your list has been added to your friends list. It will return either y or n. You would normally use this as a conditional.

if friends_no_results

{if friends_no_results}
    Sorry, no results were found.
{/if} `

This conditional evaluates to true and displays it's contents when there are no results found for this tag.

Examples

The code below will output a simple list of all members of the current site:

<h3>Viewing all Members of this Site</h3>

<ul>
{exp:friends:members
    orderby="screen_name"
    sort="asc"
}
    <li>
        <a href="{path='friends/profile'}/{friends_member_id}/">
            {friends_screen_name}
        </a>
        {if friend == "y"}
            {if friends_reciprocal == "y"}
                (already friends)
            {if:else}
                (invited)
            {/if}
        {if:else}
            <a href="{path=friends/add}{friends_member_id}/">
                Add to Friends
            </a>
        {/if}
    </li>
{/exp:friends:members}
</ul>

Below is a sample of what an individual profile or preview page might look like, assuming the members member ID is in the 3rd segment of the URI:

{exp:friends:members
    member_id="{segment_3}"
}

    <h3>{friends_screen_name}’s Profile</h3>
    <p>Email: {friends_email}</p>
    <p>Total Entries: {friends_total_entries}</p>
    <p>Join Date: {friends_join_date  format="%m %d, %Y"}</p>
    <p>
        {if friend == "y"}
            {if friends_reciprocal == "y"}
                (already friends)
            {if:else}
                (invited)
            {/if}
        {if:else}
            <a href="{path='friends/add'}/{friends_member_id}/">
                Add to Friends
            </a>
        {/if}
    </p>

{/exp:friends:members}