Friends 1.x

Legacy documentation for Friends 1.x.

The Friends:Add function is how your users will normally add other users to their Friends list. This is done with friend requests and confirming, just like in Facebook. You create links on other templates that link to a template with this code on it. Based on the member ID in the URI, the Friends:Add function will output a success/failure message, and it will take care of the rest. Additionally, notifications can be sent out to other members when you request or confirm them as a friend.

To remove a user from your friends list, your link to this template would look exactly the same, except you would append a delete segment at the end of the URL. To block friend requests from a specific member, you would append a block segment at the end of the URL.

{exp:friends:add} content {/exp:friends:add}

Parameters

The following parameters are available for use:

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.

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.

trigger=

trigger="cheese"

If you'd like to specify a username in the URI when coding a link to the Add function template, this parameter allows you to specify which trigger you're using in the URI to prepend the username segment. For example, your link might look like this: http://www.yoursite.com/friends/add/cheese/pie_man/

Variables

The following variables are available for use:

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.

friends_message

{friends_message}

This variable will output the success message or any errors upon loading the Friends:Add template.

Conditionals

The following conditionals are available for use:

failure

{if failure}Error!{/if}

This conditional shows its contents if the request action DOES NOT execute successfully.

success

{if success}Successful!{/if}

This conditional shows its contents if the request action executes successfully.

Examples

The following code should be a complete example for using this function, as well as using notifications:

{exp:friends:add
    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!"
}

    {if success}
        <h3>Successful!</h3>
    {/if}
    {if failure}
        <h3>Error!</h3>
    {/if}

    <p>{friends_message}</p>

{/exp:friends:add}

If this template was located at friends/add, you would link to this page from another template like one of the options below:

  • http://www.yoursite.com/friends/add/MEMBER_ID/
  • http://www.yoursite.com/friends/add/trigger/MEMBER_ID/

To remove a friend or a friend request, you would link to this page with one of these options:

  • http://www.yoursite.com/friends/add/MEMBER_ID/delete/
  • http://www.yoursite.com/friends/add/trigger/MEMBER_ID/delete/

To block a user from sending you friend requests, you would link to this page with one of these options:

  • http://www.yoursite.com/friends/add/MEMBER_ID/block/
  • http://www.yoursite.com/friends/add/trigger/MEMBER_ID/block/

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}/