Friends 1.x

Legacy documentation for Friends 1.x.

The Friends:Hug function allows your users to virtually "hug" their friends or other members with a click of a button. It's basically the equivelant to the Facebook "Poke" feature. Just set up a link on a members profile that links to a template with the Hug function with the friend's member ID and it will send a notification to that user. And because there's so much love happening at Solspace, we felt it was most appropriate to go with "Hug". You can refer to the function with whatever name you wish though. Hugs can also be viewed in a list for display in your template with the Hugs are given to friends/members from users by using the Friends:Hugs loop.

NOTE: There's an additional check so that a person cannot hug the same person more than 3 times in one hour. This can be adjusted manually in the code.

{exp:friends:hug} content {/exp:friends:hug}

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.

friends_only=

friends_only="y"

By default, the Hug function allows a member to hug any other member. This parameter allows you to control whether or not you restrict this to reciprocal friends only.

hug_label=

hug_label="{segment_4}"

By default, the Hug feature is a simple function that allows you to simply hug/poke a person that's that. However, if you want it all, we've included the optional hug_label parameter, which allows you to specify custom actions to do more than just hugging, such as Poked, Tickled, etc. The default value is hug. This could be hardcoded, or something that you pass into the URI. For example, if you build a URI like this: http://www.yoursite.com/friends/hug/MEMBER_ID/poked/

The "poked" value is loaded into the hug_label parameter and recorded into the database, which will be available as a variable in the Friends:Hugs loop.

notification_template=

notification_template="friends_notifications/hug"

This parameter controls which EE template to use for notifying the friend you have hugged.

subject=

subject="{friends_hugger_screen_name} has Hugged you!"

This parameter outputs the subject line for the notification email when a user hugs a friend.

trigger=

trigger="cheese"

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

Variables

The following variables are available for use:

friends_hug_label

{friends_hug_label}

This variable displays the label that was given to the hug and is available for use in the Notification Templates. If the hug_label parameter was never specified, this variable will contain the default value of hug.

friends_message

{friends_message}

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

friends_recipient_member_field

{friends_recipient_member_field}

You can parse any of the standard member fields (including screen_name, username and member_id) for both the hugger/sender and the huggee/recipient for use in the Notification Templates as well as the subject parameter. To parse these member fields for the recipient, prepend the variables with friends_recipient_. To construct this variable, simply use friends_recipient_ + member_field_name.

friends_sender_member_field

{friends_sender_member_field}

You can parse any of the standard member fields (including screen_name, username, and member_id) for both the hugger/sender and the huggee/recipient for use in the Notification Templates as well as the subject parameter. To parse these member fields for the sender, prepend the variables with friends_sender_. To construct this variable, simply use friends_sender_ + member_field_name.

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 regularly:

{exp:friends:hug
    notification_template="friends_notifications/hug"
    subject="{friends_sender_screen_name} has Hugged you!"
}

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

    <p>{friends_message}</p>

{/exp:friends:hug}

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

  • http://www.yoursite.com/friends/hug/MEMBER_ID/
  • http://www.yoursite.com/friends/hug/trigger/USERNAME/

The following code is an example of how to use this function with the custom hug_label feature:

{exp:friends:hug
    notification_template="friends_notifications/hug"
    subject="{friends_sender_screen_name} has {segment_4} you!"
    hug_label="Poked"
}

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

    <p>{friends_message}</p>

{/exp:friends:hug}

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

  • http://www.yoursite.com/friends/hug/MEMBER_ID/poked/
  • http://www.yoursite.com/friends/hug/trigger/USERNAME/poked/

Notification Templates

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

Hug Notification ("friends_notifications/hug")

Hello {friends_recipient_screen_name}!

You have just received a Hug from {friends_sender_screen_name}.

Click the link below to Hug them back!
{path='friends/hug'}/{friends_sender_member_id}/

Custom Hug Notification ("friends_notifications/custom_hug")

Hello {friends_recipient_screen_name}!

You have just been {friends_hug_label} by {friends_sender_screen_name}.

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