Friends 1.x

Legacy documentation for Friends 1.x.

The Friends:Messages function is part of the Private Messaging system and displays a list of all the logged in user's messages for a particular folder. The Friends:Messages loop detects the appropriate folder by looking in the URI for a folder segment, followed by a folder ID. You would typically link to this page from the Friends:Message_Folders loop. So the links would usually look something like this:

http://www.yoursite.com/friends/messages/folder/FOLDER_ID/

{exp:friends:messages} content {/exp:friends:messages}

Parameters

The following parameters are available for use:

message_folder=

message_folder="inbox|folder_name"

This parameter allows you to hardcode a message folder by it's short name.

message_folder_id=

message_folder_id="1"

This parameter allows you to hardcode a message folder by it's ID.

message_id=

message_id="{segment_3}"

By default, the Friends:Messages function will look for a message ID in the URI. If you wish, you can use this parameter to hardcode a member ID, pass it through an embed, or grab it from the URI.

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.

show_read=

show_read="no"

This parameter allows you to control whether or not read messages are displayed. The default is yes.

text_format=

text_format="br"

This parameter adjusts the formatting of the friends_message variable. Options are br, xhtml (default), or none.

Variables

All standard and custom member fields are available for use here, within the variable pairs. Additionally, these exist as well:

friends_FIELD_NAME

{friends_FIELD_NAME}

All standard and custom members fields are available for use, but must be placed within the friends_message_sender and friends_message_recipients variable pairs and be prepended with friends_message_sender_ or friends_message_recipient_. So to display the screen name of the sender, you would use this construct: friends_message_sender_ + screen_name.

friends_count

{friends_count}

This variable outputs the display order number for each result in the list of messages.

friends_message

{friends_message}

This variable outputs the message body for the message.

friends_message_date

{friends_message_date format="%l, %F %j, %Y at %g:%i %a"}

This variable outputs the date for when the message was sent.

friends_message_folder

{friends_message_folder}

This variable outputs the name of the message folder (ex: Inbox, Sent, etc).

friends_message_id

{friends_message_id}

This variable outputs the unique ID of the message.

friends_message_read

{if friends_message_read == "y"}{/if}

This variable determines whether the message has been read by the recipient. It outputs a y or n result. You would normally use this variable as a conditional.

friends_message_subject

{friends_message_subject}

This variable outputs the subject of the message.

friends_message_time_read

{friends_message_time_read format="%l, %F %j, %Y at %g:%i %a"}

This variable outputs the date of when the message was read by the recipient.

friends_switch

{friends_switch="one|two"}

This variable allows you to switch a CSS class back and forth for all outputed results.

friends_total_results

{friends_total_results}

This variable outputs the total amount of results outputted in your list.

Variable Pairs

The following variable pairs are available for use:

friends_message_recipients

{friends_message_recipients}{/friends_message_recipients}

This variable pair allows you to display and format information about the recipient(s) of the message. All standard and custom member fields are available and must be prepended with friends_message_recipient_.

friends_message_sender

{friends_message_sender}{/friends_message_sender}

This variable pair allows you to display and format information about the sender of the message. All standard and custom member fields are available and must be prepended with friends_message_sender_.

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

The following conditionals are available for use:

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 example code below will display a list of all messages sent to the logged in user:

<ul>
{exp:friends:messages
    message_folder="inbox"
}
    <li>
        <a href="{path='friends/message_view'}/{friends_message_id}">
            {friends_message_subject}
        </a>
        from
        {friends_message_sender}
            {friends_message_sender_screen_name}
        {/friends_message_sender}
        on
        {friends_message_date format="%F %j, %Y at %g:%i %a"}
        {if friends_message_read == "y"}
            (read on {friends_message_time_read format="%F %j, %Y"})
        {if:else}
            (unread)
        {/if}
    </li>

    {if friends_no_results}
        <li>You currently have no messages for this folder.</li>
    {/if}
{/exp:friends:messages}
</ul>

The example code below will display a a detailed view of the message sent to the logged in user (once they’ve clicked it from the list):

{exp:friends:messages}

    <h3>Subject: {friends_message_subject}</h3>
    <p>Sent: {friends_message_date format="%F %j, %Y at %g:%i %a"}</p>
    <p>
        From:
        {friends_message_sender}
            <a href="{path='friends/profile'}/{friends_message_sender_member_id}/">
                {friends_message_sender_screen_name}
            </a>
        {/friends_message_sender}
    </p>
    <p>
        Recipients:
        {friends_message_recipients backspace="2"}
            <a href="{path='friends/profile'}/{friends_message_recipient_member_id}/">
                {friends_message_recipient_screen_name}
            </a>, 
        {/friends_message_recipients}
    </p>
    <hr />
    <p>Message:<br />{friends_message}</p>

{/exp:friends:messages}