Friends 1.x

Legacy documentation for Friends 1.x.

The Friends:Message_Form function is part of the Private Messaging system and allows your users to send messages to each other.

{exp:friends:message_form} content {/exp:friends:message_form}

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 a member ID or message ID.

friend_id=

friend_id="{segment_3}"

Instead of using the friends form field, you can pass another users member ID in the URI and capture it into this parameter, which would allow your users to send messages to another user from clicking a link, etc. You can hardcode a member ID, pass it through an embed, or grab it from the URI.

limit=

limit="150"

This parameter controls the maximum number of friends or member that will show up in the friends or members variable pairs. Default is 100.

message_id=

message_id="{segment_3}"

This parameter is available to accept the ID of a message, which is typically used for replying to messages. (See reply_mode). You would typically grab the message ID from the URI.

notification_template=

notification_template="friends_notifications/new_message"

This parameter controls which EE template to use to notify the recipient(s) of the message they received.

reciprocal=

reciprocal="y"

This parameter allows you to control whether to show reciprocal or "independent" friends results within the friends variable pair. A reciprocal friendship is when both members have added each other to their friends lists. An independant friendship is when a friendship is not confirmed by the other user. The default shows both reciprocal and independant friends.

reply_email=

reply_email="no-reply@yoursite.com"

This parameter allows you to set a no-reply email address to appear in the email notifications sent to the recipient of private messages. The default behaviour uses the senders email address associated with their member account.

reply_mode=

reply_mode="y"

This parameter allows you to turn the Message_Form loop into a Reply form so your users can respond to messages. You would typically create a new template for your Reply form, and several variables become available for use. See Examples for more information.

forward_mode=

forward_mode="y"

This parameter allows you to turn the Message_Form loop into a Forward form so your users can forward messages to other users. You would typically create a new template for your Forward form, and several variables become available for use. See Examples for more information.

return=

return="friends/messages"

This parameter allows you to return the user to a specified template upon successful submittal of form.

Variables

The following variables are available for use:

friends_FIELD_NAME

{friends_FIELD_NAME}

All standard and custom member fields are available for use within the Notification Templates, and be prepended with friends_sender_ or friends_recipient_. So to display the screen name of the sender, you would use this construct: friends_sender_ + screen_name.

friends_message

{friends_message}

This variable outputs the message body for the message, and is available for Reply Mode.

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, and is available for Reply Mode.

friends_message_folder

{friends_message_folder}

This variable outputs the name of the message folder (Inbox, Sent, etc), and is available for Reply Mode.

friends_message_id

{friends_message_id}

This variable outputs the unique ID of the message, and is available for Reply Mode.

friends_message_subject

{friends_message_subject}

This variable outputs the subject of the message, and is available for Reply Mode.

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 current user, and is available for Reply Mode.

Variable Pairs

The following variable pairs are available for use:

Note: You cannot use more than 1 variable pair together in the same form. They must each be used seperately.

friends

{friends}{/friends}

This variable pair allows you to output and control the listing of the current user's friends, so they can select them from a list to be recipients of a message. This would normally be wrapped around the friend form field as a dropdown or multi-select menu.

members

{members}{/members}

This variable pair allows you to output and control the listing of all members of the site, so they can be selected from a list to be recipients of a message. This would normally be wrapped around the friend form field as a dropdown or multi-select menu.

Form Fields

The following form fields are available for use:

friend[]

<select name="friend[]" multiple="multiple">
{friends}
    <option value="{friends_member_id}">{friends_screen_name}</option>
{/friends}
</select>

This form field is where the user would select any friend(s) they wish to send a message to. Be sure to specify friend[] as the field name so the field can accept multiple user ID's.

friends_message

<textarea name="friends_message"></textarea>

This form field is where the user would enter in a subject title for the message they are sending to their friend(s).

friends_subject

<input type="text" name="friends_subject" />

This form field is where the user would enter in a subject title for the message they are sending to their friend(s).

Examples

Composer Form

The code below will output a complete Message Form (Composer) for your users to send messages to others:

<h3>Send a Message</h3>

{exp:friends:message_form
    return="friends/messages"
    notification_template="friends/email_private_message"
}

    <p>
        Select Recipients:
        <select name="friend[]" multiple="multiple">
        {friends}
            <option value="{friends_member_id}">{friends_screen_name}</option>
        {/friends}
        </select>
    </p>
    <p>
        Subject:
        <input type"text" name="friends_subject" />
    </p>
    <p>
        Message:
        <textarea name="friends_message"></textarea>
    </p>
    <p>
        <input type="submit" name="submit" value="Send" />
    </p>

{/exp:friends:message_form}

Reply Form

The code below will output a complete Reply Form for your users to reply to messages they receive from others:

<h3>Reply to this Message</h3>

{exp:friends:message_form
    return="friends/messages"
    notification_template="friends/email_private_message"
    reply_mode="y"
    message_id="{segment_3}"
}

    <p>
        Recipients:
        {friends_message_sender_screen_name}
        <input type="hidden"
            name="friend[]"
            value="{friends_message_sender_member_id}"
        />
    </p>
    <p>
        Subject:
        <input type"text"
            name="friends_subject"
            value="RE: {friends_message_subject}"
        />
    </p>
    <p>
        Message:
        <textarea name="friends_message">

            ------- Original Message -------
            {friends_message}
        </textarea>
    </p>
    <p>
        <input type="submit" name="submit" value="Reply" />
    </p>

{/exp:friends:message_form}

Forward Form

The code below will output a complete Forward Form for your users to forward messages to other users:

<h3>Forward this Message</h3>

{exp:friends:message_form
    return="friends/messages"
    notification_template="friends/email_private_message"
    forward_mode="y"
    message_id="{segment_3}"
}

    <p>
        Select Recipients:
        <select name="friend[]" multiple="multiple">
        {friends}
            <option value="{friends_member_id}">{friends_screen_name}</option>
        {/friends}
        </select>
    </p>
    <p>
        Subject:
        <input type"text"
            name="friends_subject"
            value="FW: {friends_message_subject}"
        />
    </p>
    <p>
        Message:
        <textarea name="friends_message">

            ------- Original Message -------
            {friends_message}
        </textarea>
    </p>
    <p>
        <input type="submit" name="submit" value="Forward" />
    </p>

{/exp:friends:message_form}

Notification Templates

For your notification template, you use regular EE templates, and just add code like this:

Example 1 ("friends_notifications/new_message")

Hello {friends_recipient_screen_name}!

You have received a message from
{friends_sender_screen_name} on the {site_name} website.

To read the message, click here:
{site_url}/friends/view_message/{friends_message_id}/

Example 2 ("friends_notifications/new_message")

Hello {friends_recipient_screen_name}!

You have received a message from
{friends_sender_screen_name} on the {site_name} website.

Subject: {friends_subject}
Message:
{friends_message}

To respond to this message, click here:
{site_url}/friends/view_message/{friends_message_id}/