Friends 1.x

Legacy documentation for Friends 1.x.

The Friends:Form function allows your users to add/confirm/remove multiple friends within 1 submission. It's an alternate method to using the Friends:Add method. it displays a list of either all current friends, or all site members. Upon form submission, the Friends:Form function will output relevant message(s), and will take care of the rest. Additionally, notifications can be sent out to other members when you request or confirm them as a friend.

{exp:friends:form} content {/exp:friends: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 an ID of any type.

form_name=

form_name="your_form_name"

This parameter allows you to establish a name attribute for the form.

form_id=

form_id="your_form_id"

This parameter allows you to establish an ID attribute for the form.

group_id=

group_id="5|6|9"

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

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 view a list of friends for a specific member by specifying their member ID. You can hardcode a member ID, pass it through an embed, or grab it from the URI. Alternatively, you can use the username parameter.

notification_confirm=

notification_confirm="friends_notifications/friend_confirm"

This parameter controls which EE template to use for your friend confirm notification template. This is the template that will be used for the message that someone receives when their friend request has been confirmed by the other user.

notification_request=

notification_request="friends_notifications/friend_request"

This parameter controls which EE template to use for your friend request notification template. This is the template that will be used for the message that someone receives when a user has requested to be friends with them.

onsubmit=

onsubmit="some_javascript()"

This parameter allows you to execute Javascript functions at form submission.

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.

return=

return="template_group/template"

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

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.

subject_confirm=

subject_confirm="{friends_inviter_screen_name} has confirmed you as a Friend!"

This parameter outputs the subject line for the notification email when a user is confirming a friend request.

subject_request=

subject_request="{friends_inviter_screen_name} has added you as a Friend!"

This parameter outputs the subject line for the notification email when a user is initiating a friend request.

type=

type="mine"

This parameter allows you to designate which type of member list to retrieve. Indicating mine will display a list of your friends. Indicating member will display a list of all members of the site.

username=

username="{segment_3}"

This parameter allows you view a list of friends for a specific member by specifying their username. You can hardcode a username, pass it through an embed, or grab it from the URI. Alternatively, you can use the member_id parameter.

Variables

All standard and custom member fields and usual Friends variables are available for use here. Additionally, these exist as well:

friends_invitee_member_field

{friends_invitee_member_field}

You can parse standard member fields for both the invitee and inviter for use in the Notification Templates as well as the subject_request and subject_confirm parameters. To parse standard member fields for the invitee, prepend your variables with friends_invitee_. To construct this variable, simply use friends_invitee_ + member_field_name.

friends_inviter_member_field

{friends_inviter_member_field}

You can parse standard member fields for both the invitee and inviter for use in the Notification Templates as well as the subject_request and subject_confirm parameters. To parse standard member fields for the inviter, prepend your variables with friends_inviter_. To construct this variable, simply use friends_inviter_ + member_field_name.

Variable Pairs

The following variable pairs are available for use:

Note: You cannot use both variable pairs together in the same form. They must each be used seperately.

invites

{invites} {/invites}

This variable pair will display all "incoming" friend requests from other users, and is used to establish the formatting of each row of results contained inside your form. This way, you can quickly check off all friend requests you wish to confirm or remove.

members

{members} {/members}

This variable pair is used to establish the formatting of each row of the member list that will be contained inside your form.

Conditionals

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

if friend

{if friend == "y"}{/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.

Form Fields

The following form fields are available for use:

friends_delete

<input type="checkbox" name="friends_delete" value="yes" />

This field allows your users to remove the selected members from their list of friends when they submit the form. If this checkbox is selected, it will remove any friends the user has selected in the list upon submission. If left unchecked, the members selected in the list will be invited/confirmed.

friends_member_id

<input type="checkbox" name="friends_member_id[]" value="{friends_member_id}" />

This field allows you to create a list of members to either be added or deleted from a friends list. Make sure you specify the name of the field with [ ] so that the Friends module knows that an array of members is being submitted.

Examples

The following example will display a list of all site members, allowing a user to multi add or remove other members from their friends list (and will send email notifications upon successful Friend requests/confirms):

<h3>Add or Delete Members to your account using the form below:</h3>

{exp:friends:form
    type="member"
    return="friends/form/thanks"
    notification_request="friends_notifications/friend_request"
    notification_confirm="friends_notifications/friend_confirm"
    subject_request="{friends_inviter_screen_name} added you as a friend!"
    subject_confirm="{friends_inviter_screen_name} confirmed your friend request!"
}

    <ul>
    {members}
        <li>
            <input type="checkbox" name="friends_member_id[]"
                id="member_{friends_member_id}" value="{friends_member_id}"
                {if friend == "y"}
                    checked="checked"
                {/if}
            />
            {if friend == "y"}
                <label for="member_{friends_member_id}">
                    {friends_screen_name}
                </label>
                <small>(already added)</small>
            {if:else}
                <label for="member_{friends_member_id}">
                    {friends_screen_name}
                </label>
            {/if}
        </li>
    {/members}
    </ul>

    <p><input type="checkbox" name="friends_delete"
        id="friends_delete" value="yes" />
        <label for="friends_delete">Delete?</label></p>

    <p><input type="submit" name="submit" value="Submit" /></p>

{/exp:friends:form}

The following example will display a list of all “incoming” friend requests from other users, allowing a user to multi add or remove the requests from their lists. (and will send email notifications upon successful Friend confirmation):

<h3>Friend Requests Awaiting Confirmation:</h3>

{exp:friends:form
    type="member"
    return="friends/form/thanks"
    notification_request="friends_notifications/friend_request"
    notification_confirm="friends_notifications/friend_confirm"
    subject_request="{friends_inviter_screen_name} added you as a friend!"
    subject_confirm="{friends_inviter_screen_name} confirmed your friend request!"
}

    <ul>
    {invites}
        <li>
            <input type="checkbox" name="friends_member_id[]"
                id="member_{friends_member_id}" value="{friends_member_id}"
            />
            <label for="invite_{friends_member_id}">
                {friends_screen_name}
            </label>
            (requested {friends_entry_date format="%Y-%m-%d"})
        </li>
    </ul>

    <p><input type="checkbox" name="friends_delete"
        id="friends_delete" value="yes" />
        <label for="friends_delete">Delete?</label></p>

    <p><input type="submit" name="submit" value="Submit" /></p>

{/exp:friends:form}

Notification Templates

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

Friend Request ("friends_notifications/friend_request")

Hello {friends_invitee_screen_name}!

You have just received a Friend Request from
{friends_inviter_screen_name}.

Click the link below to accept this invitation:
{path='friends/add'}/{friends_inviter_member_id}/

Friend Confirm ("friends_notifications/friend_confirm")

Hello {friends_invitee_screen_name}!

You are now friends with {friends_inviter_screen_name}
because they have accepted your invitation.

Click the link below to view their profile:
{path='friends/profile'}/{friends_inviter_member_id}/