Friends 1.x

Legacy documentation for Friends 1.x.

The Friends:Group_Form function allows your users to create and manage virtual group memberships on your website. Users on your site can be invited to join, or request to join a group.

{exp:friends:group_form} content {/exp:friends:group_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_class=

form_class="your_form_class"

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

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.

friends_group_id=

friends_group_id="{segment_3}"

This parameter allows you to hardcode a group ID, pull a group ID dynamically from the URL, or pass an ID through an embed.

group_name=

group_name="{segment_3}"

This parameter allows you to hardcode a group name, pull a group name dynamically from the URL, or pass name through an embed.

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.

notification_accept=

notification_accept="friends_notifications/group_accept"

This parameter controls which EE template to use to format a notification to the group owner when someone accepts his invitation to join a group.

notification_approve=

notification_approve="friends_notifications/group_approve"

This parameter controls which EE template to use to format a notification to the user who requested membership to a group when their request has been confirmed.

notification_invite=

notification_invite="friends_notifications/group_invite"

This parameter controls which EE template to use to format a notification to the user who is being invited to join a group.

notification_leave=

notification_leave="friends_notifications/group_leave"

This parameter controls which EE template to use to format a notification to the group owner when a user leaves their group.

notification_remove=

notification_remove="friends_notifications/group_remove"

This parameter controls which EE template to use to format a notification to the user when they are removed from a group by the group owner.

notification_request=

notification_request="friends_notifications/group_request"

This parameter controls which EE template to use to format a notification to the group owner when a user requests to join his group.

onsubmit=

onsubmit="some_javascript()"

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

return=

return="template_group/template"

The 'return' parameter allows you to return the user to a specified template upon successful submittal of form. Also available within this parameter is %%friends_group_id%%, which will parse out as the group ID of the newly created group. This allows you to have a return URL with the group ID in the URI, which lets you dynamically view data of the newly created group.

subject_accept=

subject_accept="{friends_user_screen_name} has accepted your invitation to join your group!"

This parameter outputs the subject line for the notification email to the group owner when someone accepts his invitation to join a group.

subject_approve=

subject_approve="You are now a member of the {friends_group_title} group!"

This parameter outputs the subject line for the notification email to the user who requested membership to a group when their request has been confirmed.

subject_invite=

subject_invite="{friends_owner_screen_name} would like you to join the {friends_group_title} group"

This parameter outputs the subject line for the notification email to the user who is being invited to join a group.

subject_leave=

subject_leave="{friends_user_screen_name} has left the {friends_group_title} group"

This parameter outputs the subject line for the notification email to the group owner when a user leaves their group.

subject_remove=

subject_remove="You have been removed from the {friends_group_title} group"

This parameter outputs the subject line for the notification email to the user when they are removed from a group by the group owner.

subject_request=

subject_request="{friends_user_screen_name} has requested to join the {friends_group_title} group"

This parameter outputs the subject line for the notification email to the group owner when a user requests to join his group.

template=

template="path_to/friends_message_template"

This parameter allows you to specify an EE template to format the message provided by the Friends module when a group edit or create action is successful. This would generally be used for AJAX implementations.

Variables

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

friends_owner_member_field

{friends_owner_member_field}

You can parse the screen_name, username, and member_id member fields for both the user and the group owner for use in the Notification Templates as well as the subject_ parameters. All member fields are available within the members and friends variable pairs. To parse these member fields for the group owner, prepend the variables with friends_owner_. To construct this variable, simply use friends_owner_ + member_field_name.

friends_owner_user_field

{friends_user_member_field}

You can parse the screen_name, username, and member_id member fields for both the user and the group owner for use in the Notification Templates as well as the subject_ parameters. All member fields are available within the members and friends variable pairs. To parse these member fields for the user, prepend the variables with friends_user_. To construct this variable, simply use friends_user_ + member_field_name.

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.

confirmed

{confirmed} {/confirmed}

This variable pair will display all confirmed members of a group, which allows the owner to easily manage/remove members of a group. It is used to establish the formatting of each row of results contained inside your form.

friends

{friends} {/friends}

This variable pair will display all reciprocal friends or outgoing friend requests from other users, and is used to establish the formatting of each row of results contained inside your form.

members

{members} {/members}

This variable pair will display all members of the site, and is used to establish the formatting of each row of results contained inside your form.

requests

{requests} {/requests}

This variable pair will display all requests from members to join a specific group, which allows the owner to easily manage/remove members of a group. It is used to establish the formatting of each row of results contained inside your form.

Form Fields

The following form fields are available for use:

friends_group_description

<textarea name="friends_group_description">
    {friends_group_description}
</textarea> `

This field allows you to create or edit a description for your group.

friends_group_id=

<input type="text" name="friends_group_id" value="{friends_group_id}" />

This parameter allows to specify a group ID to edit.

friends_group_name

<input type="text" name="friends_group_name" value="{friends_group_name}" />

This field allows you to create or edit a "short_name" for your group.

friends_group_private

<input type="checkbox"
    name="friends_group_private" value="{friends_group_private}"
    {if friends_group_private}
        checked="checked"
    {/if}
/>

This field allows you make your group private (hidden from view of non-group members) or public (visible for all to see). Specifying y makes the group private, while n leaves it public.

friends_group_template

<input type="text" name="friends_group_template" value="path_to/friends_message_template" />

This field allows you to specify an EE template to format the message provided by the Friends module when a group edit or create action is successful. This would generally be used for AJAX implementations.

friends_group_title

<input type="text" name="friends_group_title" value="{friends_group_title}" />

This field allows you to create or edit a full name for your group.

friends_member_id[]

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

This field allows you to create a list of members to either be added or deleted from a Group. Make sure you specify the name of the field with an open and closing square brackets so that the Friends module knows that an array of members is being submitted.

friends_notification_accept

<input type="text" name="friends_notification_accept" value="friends_notifications/group_accept" />

This form field controls which EE template to use to format a notification to the group owner when someone accepts his invitation to join a group. This would generally be used as an alternative to the notification_accept parameter for AJAX implementations or to allow the user to specify a notification template dynamically.

friends_notification_approve

<input type="text" name="friends_notification_approve" value="friends_notifications/group_approve" />

This parameter controls which EE template to use to format a notification to the user who requested membership to a group when their request has been confirmed. This would generally be used as an alternative to the notification_approve parameter for AJAX implementations or to allow the user to specify a notification template dynamically.

friends_notification_invite

<input type="text" name="friends_notification_invite" value="friends_notifications/group_invite" />

This parameter controls which EE template to use to format a notification to the user who is being invited to join a group. This would generally be used as an alternative to the notification_invite parameter for AJAX implementations or to allow the user to specify a notification template dynamically.

friends_notification_leave

<input type="text" name="friends_notification_leave" value="friends_notifications/group_leave" />

This parameter controls which EE template to use to format a notification to the group owner when a user leaves their group. This would generally be used as an alternative to the notification_leave parameter for AJAX implementations or to allow the user to specify a notification template dynamically.

friends_notification_remove

<input type="text" name="friends_notification_remove" value="friends_notifications/group_remove" />

This parameter controls which EE template to use to format a notification to the user when they are removed from a group by the group owner. This would generally be used as an alternative to the notification_remove parameter for AJAX implementations or to allow the user to specify a notification template dynamically.

friends_notification_request

<input type="text" name="friends_notification_request" value="friends_notifications/group_request" />

This parameter controls which EE template to use to format a notification to the group owner when a user requests to join his group. This would generally be used as an alternative to the notification_request parameter for AJAX implementations or to allow the user to specify a notification template dynamically.

friends_remove

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

This field allows you to change the form to Remove/delete member mode. In Remove mode, any of the selected members passed through the submission will be removed from the group.

friends_subject_accept

<input type="text" name="friends_subject_accept" value="{friends_user_screen_name} has accepted your invitation to join your group!" />

This parameter outputs the subject line for the notification email to the group owner when someone accepts his invitation to join a group. This would generally be used as an alternative to the subject_accept parameter for AJAX implementations or to allow the user to specify a subject line dynamically.

friends_subject_approve

<input type="text" name="friends_subject_approve" value="You are now a member of the {friends_group_title} group!" />

This parameter outputs the subject line for the notification email to the user who requested membership to a group when their request has been confirmed. This would generally be used as an alternative to the subject_approve parameter for AJAX implementations or to allow the user to specify a subject line dynamically.

friends_subject_invite

<input type="text" name="friends_subject_invite" value="{friends_owner_screen_name} would like you to join the {friends_group_title} group" />

This parameter outputs the subject line for the notification email to the user who is being invited to join a group. This would generally be used as an alternative to the subject_invite parameter for AJAX implementations or to allow the user to specify a subject line dynamically.

friends_subject_leave

<input type="text" name="friends_subject_leave" value="{friends_user_screen_name} has left the {friends_group_title} group" />

This parameter outputs the subject line for the notification email to the group owner when a user leaves their group. This would generally be used as an alternative to the subject_leave parameter for AJAX implementations or to allow the user to specify a subject line dynamically.

friends_subject_remove

<input type="text" name="friends_subject_remove" value="You have been removed from the {friends_group_title} group" />

This parameter outputs the subject line for the notification email to the user when they are removed from a group by the group owner. This would generally be used as an alternative to the subject_remove parameter for AJAX implementations or to allow the user to specify a subject line dynamically.

friends_subject_request

<input type="text" name="friends_subject_request" value="{friends_user_screen_name} has requested to join the {friends_group_title} group" />

This parameter outputs the subject line for the notification email to the group owner when a user requests to join his group. This would generally be used as an alternative to the subject_request parameter for AJAX implementations or to allow the user to specify a subject line dynamically.

Examples

Creating a New Group

The following example will display a form for creating a new Group:

<h3>Create a new Group</h3>

{exp:friends:group_form
    return="friends/groups/%friends_group_id%"
    notification_invite="friends_notifications/group_invite"
    subject_invite="{friends_screen_name} would like you to join their group"
}

    <p>Group Name:
        <input type="text" name="friends_group_name" /></p>
    <p>Group Title:
        <input type="text" name="friends_group_title" /></p>
    <p>Group Description:
        <br /><textarea name="friends_group_description"></textarea></p>
    <p>Is this Group Private?
        <input type="radio" name="friends_group_private" id="friends_group_private_yes" value="y" />
        <label for="friends_group_private_yes">Yes</label>
        <input type="radio" name="friends_group_private" id="friends_group_private_no" value="n" />
            <label for="friends_group_private_no">No</label></p>
    <p><input type="submit" name="submit" value="Create Group!" />

    <h4>Invite Your Friends?</h4>
    <ul>
    {friends}
        <li><input type="checkbox" name="friends_member_id[]" id="friend_{friends_member_id}" value="{friends_member_id}" /> <label for="friend_{friends_member_id}">{friends_screen_name}</label></li>
    {/friends}
    </ul>

{/exp:friends:group_form}

Editing an Existing Group

The following example will display a form for creating a new Group, as well as display a list of all of the currently logged in user’s friends, allowing them to multi invite their friends to join the group:

<h3>Edit your Group or Add Friends</h3>

{exp:friends:group_form
    return="friends/groups/{friends_group_id}"
    notification_invite="friends_notifications/group_invite"
    subject_invite="{friends_owner_screen_name} would like you to join the {friends_group_title} group"
    notification_approve="friends_notifications/group_approve"
    subject_approve="You are now a member of the {friends_group_title} group!"
}

    <h4>Edit Your Group Details</h4>

    <p>Group Name:
        <input type="text" name="friends_group_name" value="{friends_group_name}" /></p>
    <p>Group Title:
        <input type="text" name="friends_group_title" value="{friends_group_title}" /></p>
    <p>Group Description:
        <br /><textarea name="friends_group_description">
            {friends_group_description}
        </textarea></p>

    <p>Is this Group Private?
        <input type="radio" name="friends_group_private" id="friends_group_private_yes" value="y"
        {if friends_group_private == "y"}
            checked="checked"
        {/if} />
        <label for="friends_group_private_yes">Yes</label>
        <input type="radio" name="friends_group_private" id="friends_group_private_no" value="n"
        {if friends_group_private == "n"}
            checked="checked"
        {/if} />
        <label for="friends_group_private_no">No</label></p>

    <h4>Invite Your Friends?</h4>
    <ul>
    {friends}
        <li><input type="checkbox" name="friends_member_id[]" id="friend_{friends_member_id}" value="{friends_member_id}" {if friends_group_member == "y"}checked="checked"{/if} /> <label for="friend_{friends_member_id}">{friends_screen_name}</label></li>
    {/friends}
    </ul>

    <p><input type="submit" name="submit" value="Update Group" />

{/exp:friends:group_form}

Confirming Requests to Join a Group

The following example will display a form that allows the group owner to easily approve multiple requests to join their group at once (we’ve also included hidden fields for each group info field so the data is no lost on form submit):

<h3>Requests to Join Your Group</h3>

{exp:friends:group_form
    return="friends/groups/{friends_group_id}"
    notification_approve="friends_notifications/group_approve"
    subject_approve="You are now a member of the {friends_group_title} group!"
}

    <h4>Check off any of the members below to approve their request to join your group:</h4>
    <p>Group Title: "{friends_group_title}"
    <input type="hidden" name="friends_group_name" value="{friends_group_name}" />
    <input type="hidden" name="friends_group_title" value="{friends_group_title}" />
    <input type="hidden" name="friends_group_description" value="{friends_group_description}" />
    <input type="hidden" name="friends_group_private" value="{friends_group_private}" /></p>

    <ul>
    {requests}
        <li><input type="checkbox" name="friends_member_id[]" id="friend_{friends_member_id}" value="{friends_member_id}" /> <label for="friend_{friends_member_id}">{friends_screen_name}</label></li>
    {/requests}
    </ul>

    <p><input type="submit" name="submit" value="Approve these Members" />

{/exp:friends:group_form}

Removing Members from a Group

The following example will display a form that allows the group owner to easily approve multiple requests to join their group at once (we’ve also included hidden fields for each group info field so the data is no lost on form submit):

<h3>Remove Members From Your Group</h3>

{exp:friends:group_form
    return="friends/groups/{friends_group_id}"
    notification_remove="friends_notifications/group_remove"
    subject_remove="You have been removed from the {friends_group_title} group"
}

    <h4>Check off any of the members below to remove them from your group:</h4>
    <p>Group Title: "{friends_group_title}"
        <input type="hidden" name="friends_group_name" value="{friends_group_name}" />
        <input type="hidden" name="friends_group_title" value="{friends_group_title}" />
        <input type="hidden" name="friends_group_description" value="{friends_group_description}" />
        <input type="hidden" name="friends_group_private" value="{friends_group_private}" /></p>

    <ul>
    {confirmed}
        <li><input type="checkbox" name="friends_member_id[]" id="friend_{friends_member_id}" value="{friends_member_id}" /> <label for="friend_{friends_member_id}">{friends_screen_name}</label></li>
    {/confirmed}
    </ul>

    <p><input type="hidden" name="friends_remove" value="yes" />
    <input type="submit" name="submit" value="Remove these Members" />

{/exp:friends:group_form}

Notification Templates

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

User requests to join a group ("friends_notifications/group_request")

Hello {friends_owner_screen_name}!

{friends_user_screen_name} would like to join
the {friends_group_title} group.

Click the link below to accept this request to join your group:
{path='friends/group_add'}/group/{friends_group_id}/member/{friends_user_member_id}/

User accepts invitation to join group ("friends_notifications/group_accept")

Hello {friends_owner_screen_name}!

{friends_user_screen_name} has accepted your request and
joined the {friends_group_title} group!

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

User leaves group ("friends_notifications/group_leave")

Hello {friends_owner_screen_name}!

{friends_user_screen_name} has just left the
{friends_group_title} group.

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

Group Owner invites user to join his group ("friends_notifications/group_invite")

Hello {friends_user_screen_name}!

You have been invited to join the
{friends_group_title} group.

Click the link below to accept this request and join the group:
{path='friends/group_add'}/group/{friends_group_id}/

Group Owner approves of user request to join group ("friends_notifications/group_approve")

Hello {friends_user_screen_name}!

You request to join the {friends_group_title} group
has been accepted!

Click the link below to view the group:
{path='friends/group_info'}/{friends_group_id}/

Group Owner removes user from group ("friends_notifications/group_remove")

Hello {friends_user_screen_name}!

You have been removed from the {friends_group_title} group.

Click the link below to view the group:
{path='friends/group_info'}{friends_group_id}/