Friends 1.x

Legacy documentation for Friends 1.x.

The Friends:Group_Entry_Add function is part of the Group feature of Friends. It allows your users to add channel entries to their Friends group(s). It is a form function that is placed into a template and submitted as a POST to another template with the Friends:Group_Entry_Add function. The Friends:Group_Entry_Add function will then display a success or error message accordingly. It also allows you to send notifications to members of your group, mentioning that the entry has been added to the Group.

{exp:friends:group_entry_add} content {/exp:friends:group_entry_add}

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 message ID.

entry_id=

entry_id="{segment_4}"

You would normally submit a POST request though a form to the Friends:Group_Entry_Add function, but this parameter is available to use, should you need to pass the entry ID through the URI or an embed.

friends_group_id=

friends_group_id="{segment_3}"

You would normally submit a POST request though a form to the Friends:Group_Entry_Add function, but this parameter is available to use, should you need to pass the group ID through the URI or an embed.

group_name=

group_name="{segment_3}"

You would normally submit a POST request though a form to the Friends:Group_Entry_Add function, but this parameter is available to use, should you need to pass the group short_name through the URI or an embed.

notification_template=

notification_template="friends_notifications/group_entry_add"

This parameter allows you specify an EE template to generate and format a notification to all of the members of the group, informing them of the new entry added. If this is not specified, a notification will NOT be sent.

subject=

subject="A new entry titled {title} has been added to your group"

This parameter allows you specify the subject line message to generate for an email notification to all of the members of the group, informing them of the new entry added.

Variables

The following variables are available for use:

friends_message

{friends_message}

This variable will output the success message or any errors upon loading the Friends:Group_Entry_Add 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 sender and the 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 sender and the 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.

Variable Pairs

The following variable pairs are available for use:

entries

{entries} {/entries}

This variable pair allows you to display data for the channel entries added to a group, available in the Notification Template, and controls the formating of a list of entries since more than 1 channel entry can be assigned to a group in a single submission. Most usual Channel:Entries tag variables become available within this loop (ex: title, url_title, etc), and they need to be prepended with friends_. To construct this variable, simply use friends_ + 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.

Form Fields

The following form fields are available for use:

ajax

<input type="hidden" name="ajax" value="yes" />

This form field tells the method to behave nicely with AJAX calls.

friends_entry_id[]

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

This form field is necessary to submit the channel entry ID to the Friends:Group_Entry_Add template. Using [] in the form name allows you to have multiple check boxes within a list of channel entries so a user can select multiple entries to be assigned to a Group when submitting the form as a POST.

friends_group_id[]

<input type="hidden" name="friends_group_id[]" value="{friends_group_id}" />

This form field is necessary to submit the group ID to the Friends:Group_Entry_Add template. Using [] in the form name allows you to have a multiple select field of Friends groups so a user can select multiple groups for a channel entry to be assigned to when submitting the form as a POST.

friends_notification_template

<input type="hidden" name="friends_notification_template" value="friends_notifications/group_entry_add" />

This form field allows you specify an EE template to generate and format a notification to all of the members of the group, informing them of the new entry added. If this is not specified, a notification will NOT be sent.

friends_remove

<input type="checkbox" name="friends_remove" value="yes" />
<label for="friends_remove">Remove?</label>
<input type="hidden" name="friends_remove" value="yes" />

This form field is used to allow a user to remove a channel entry from a group when the value for this field is yes. An entry can ONLY be removed IF one of the following applies: 1) the logged in user was the original submitter of the entry to the group; 2) the logged in user is the owner of the group that the entry is assigned to; or 3) the logged in user is a Super Admin.

friends_subject

<input
    type="hidden"
    name="friends_subject"
    value="A new entry titled {title} has been added to your group"
/>

This form field allows you specify the subject line message to generate for an email notification to all of the members of the group, informing them of the new entry added.

Examples

The following code should be a complete example for using this function:

{exp:friends:group_entry_add}

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

    <p>{friends_message}</p>

{/exp:friends:group_entry_add}

Setup

To implement this feature (including email notifications to group members) into a template for viewing a single entry, your code might look like this:

{exp:channel:entries}

    <h2>{title}</h2>
    <p>{body}</p>

{!-- Begin Group Entry Add form --}

    <h4>Add this entry to your Group</h4>

    <form method="post" action="{path='friends/group_entry_add'}/">

        <input type="hidden" name="csrf_token" value="{csrf_token}">

        <input type="hidden"
            name="friends_notification_template"
            value="friends_notifications/group_entry_add"
        />
        <input type="hidden"
            name="friends_subject"
            value="A new entry titled {title} has been added to your group"
        />
        <input type="hidden"
            name="friends_entry_id[]"
            value="{entry_id}"
        />

        <select name="friends_group_id[]" multiple="multiple">
        {exp:friends:groups dynamic="off"}
            <option value="{friends_group_id}">{friends_group_title}</option>
        {/exp:friends:groups}
        </select>

        <input type="submit" name="submit" value="Add to Group" />

</form>

{!-- End Group Entry Add form --}

{/exp:channel:entries}

Removing Entries from Groups

To remove a channel entry from a Group, your code may look something like this (submitting to a template with the Group_Entry_Add function):

<ul>
{exp:friends:group_entries group_name="{segment_3}"}
    <li>
        <a href="{url_title_path='blog/article'}">{title}</a>

        <form method="post" action="{path='friends/group_entry_add'}/">
            <input type="hidden" name="csrf_token" value="{csrf_token}">
            <input type="hidden" name="friends_entry_id[]" value="{entry_id}" />
            <input type="hidden" name="friends_group_id[]" value="{friends_group_id}" />
            <input type="hidden" name="friends_remove" value="yes" />
            <input type="submit" name="submit" value="Remove?" />
        </form>
    </li>
    {if no_results}
        <li>This group currently has no entries assigned to it.</li>
    {/if}
{/exp:friends:group_entries}
</ul>

Using with Channel Form

To assign an entry you're currently publishing to a group, you can place the following code somewhere in your Channel Form tag. Your code may look something like this (WITHOUT submitting to a template with the Group_Entry_Add function):

Tell your group(s) about this:

<input type="hidden"
    name="friends_notification_template"
    value="friends_notifications/group_entry_add"
/>
<input type="hidden"
    name="friends_subject"
    value="A new entry titled {title} has been added to your group"
/>

<select name="friends_group_id[]" multiple="multiple">
{exp:friends:groups dynamic="off"}
    <option value="{friends_group_id}">{friends_group_title}</option>
{/exp:friends:groups}
</select>

Notification Templates

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

User adds a channel entry to a Group (“friends_notifications/group_entry_add”)

Hello {friends_recipient_screen_name}!

{friends_sender_screen_name} just added a new channel
entry to {friends_group_title} group.

{entries}
    Title: {friends_title} ({site_url}/blog/article/{friends_url_title}/)
{/entries}

Click here to view more info about the group:
{site_url}/friends/view_group/{friends_group_name}/