Favorites Documentation

Favorites:Form template tag

The Favorites:Form tag is the essential part of Favorites, as it displays a form that allows your users to add favorite behavior for channel entries or members. For editing favorites, please see the Favorites:Edit tag.

{exp:favorites:form} content {/exp:favorites:form}

Parameters

The following parameters are available for use:

form:ATTRIBUTE_NAME=

form:class="your_class_name"

This parameter allows you to control any form attribute for the form in your template. Simply replace ATTRIBUTE_NAME with an attribute name such as id, name, class, onsubmit, etc, and specify a value for that attribute. You can specify this parameter multiple times to control as many attributes as necessary. This would normally be done to control your form with Javascript or style it with CSS.

collection=

collection="this_is_my_form_name"

Each saved favorite needs to belong to a collection. This parameter is used by Favorites to dynamically sort favorites into groups (collections) at submission. The organization happens dynamically when specifying this parameter on other Favorites loops - it allows you to filter down your favorites to those only contained by the specified group name. Entries/members can be favorited multiple times when under different collection names. Collections can be supplied either through this parameter or the collection form field. If a value is not supplied for the parameter or form field, the default collection name will be used.

entry_id

entry_id="{entry_id}"

When using with channel entries, specify this parameter and supply it with a channel entry ID so this form will know which entry to save the favorite to. This parameter can be hardcoded, set dynamically, or by having an entry ID passed through an embedded template.

member_id

member_id="{segment_3}"

When using with members, specify this parameter and supply it with a member ID so this form will know which member to save the favorite to. This parameter can be hardcoded, set dynamically, or by having a member ID passed through an embedded template.

username

username="{segment_3}"

When using with members, specify this parameter and supply it with a username so this form will know which member to save the favorite to. This parameter can be hardcoded, set dynamically, or by having a username passed through an embedded template.

return

return="template_group/template_name"

This parameter determines where to send users once they have submitted the form. If this parameter is not called, the form will return the current page.

error_page

error_page="path_to/template"

This parameter allows you to bypass the EE message template for displaying errors, and instead show your own regular template with the error messages. Your error template must follow guidelines mentioned in Favorites Error Page documentation.

Variable Pairs

The following variable pairs are available for use:

favorites:collections

<select name="collection">
{favorites:collections}
    <option value="{favorites:collection}">
        {favorites:collection}
    </option>
{/favorites:collections}
</select>

This variable pair is available to parse out a list of existing collection names for your collection form field.

Form Fields

The following form fields are available for use:

collection

<select name="collection">
{favorites:collections}
    <option value="{favorites:collection}">
        {favorites:collection}
    </option>
{/favorites:collections}
</select>

Collections can be supplied either through this form field or the collection parameter. When using the form field approach, you can supply a list of already existing collection names for them to choose from. A list of existing collection names can be populated by using the favorites:collections variable pair. If a value is not supplied for the parameter or form field, the default collection name will be used.

notes

<textarea name="notes"></textarea>

This is an optional form field that allows your users to add notes for the entry/member they are saving.

Examples

The following is a very basic example that allows adding entries to favorites:

{exp:channel:entries}
    <h2>{title}</h2>
    <p>{body}</p>
    <p>
    {exp:favorites:form
        entry_id="{entry_id}"
    }
        <select name="collection">
        {favorites:collections}
            <option value="{favorites:collection}">
                {favorites:collection}
            </option>
        {/favorites:collections}
        </select>
        <input type="text" name="notes" />
        <input type="submit" name="submit" value="Add" />
    {/exp:favorites:form}
    </p>
{/exp:channel:entries}

The following is a more elaborate example, with some logic built in for hiding the "Add to favorites" form if the user has already favorited the entry, displaying info about the saved entry, and including ability to edit favorites using the Favorites:Edit tag:

{exp:channel:entries}
    <h2>{title}</h2>
    <p>{body}</p>
<!-- DISPLAY the current favorites. This won't parse if there are no favorites for the item yet. -->
    {exp:favorites:info
        entry_id="{entry_id}"
        disable_pagination="yes"
    }
        <p>
            You saved this to {favorites:collection_name}
            on {favorites:favorited_date format="%F %j, %Y"}
            {if favorites:notes} with the notes: <i>{favorites:notes}</i>{/if}
        </p>
    <!-- EDIT this current favorite -->
        <p>
        {exp:favorites:edit
            favorite_id="{favorites:favorite_id}"
        }
            <select name="collection">
            {favorites:collections}
                <option value="{favorites:collection}" {favorites:selected}>
                    {favorites:collection}
                </option>
            {/favorites:collections}
            </select>
            <input type="text" name="notes" value="{favorites:notes}" />
            <input type="submit" name="submit" value="Update" />
        {/exp:favorites:edit}
    <!-- DELETE the current favorite -->
        {exp:favorites:edit
            favorite_id="{favorites:favorite_id}"
        }
            <input type="hidden" name="delete" value="yes">
            <input type="submit" name="submit" value="Remove" />
        {/exp:favorites:edit}
        </p>
    {if favorites:no_results}
        <p>
    <!-- ADD a Favorite -->
        {exp:favorites:form
            entry_id="{entry_id}"
        }
            <select name="collection">
            {favorites:collections}
                <option value="{favorites:collection}">
                    {favorites:collection}
                </option>
            {/favorites:collections}
            </select>
            <input type="text" name="notes" />
            <input type="submit" name="submit" value="Add" />
        {/exp:favorites:form}
        </p>
    {/if}
    {/exp:favorites:info}
{/exp:channel:entries}

The following is an example for adding/updating/removing members from favorites (with suggested, but not limited to, use of User add-on):

{exp:user:users}
    <h2><a href="{path='user/profile'}">{screen_name}</a></h2>
    <p>Location: {location}</p>
    <p>Bio: {bio}</p>
<!-- DISPLAY the current favorites. This won't parse if there are no favorites for the item yet. -->
    {exp:favorites:info
        member_id="{member_id}"
        disable_pagination="yes"
    }
        <p>
            You saved this to {favorites:collection_name}
            on {favorites:favorited_date format="%F %j, %Y"}
            {if favorites:notes} with the notes: <i>{favorites:notes}</i>{/if}
        </p>
    <!-- EDIT this current favorite -->
        <p>
        {exp:favorites:edit
            favorite_id="{favorites:favorite_id}"
        }
            <select name="collection">
            {favorites:collections}
                <option value="{favorites:collection}" {favorites:selected}>
                    {favorites:collection}
                </option>
            {/favorites:collections}
            </select>
            <input type="text" name="notes" value="{favorites:notes}" />
            <input type="submit" name="submit" value="Update" />
        {/exp:favorites:edit}
    <!-- DELETE the current favorite -->
        {exp:favorites:edit
            favorite_id="{favorites:favorite_id}"
        }
            <input type="hidden" name="delete" value="yes">
            <input type="submit" name="submit" value="Remove" />
        {/exp:favorites:edit}
        </p>
    {if favorites:no_results}
        <p>
    <!-- ADD a Favorite -->
        {exp:favorites:form
            member_id="{member_id}"
        }
            <select name="collection">
            {favorites:collections}
                <option value="{favorites:collection}">
                    {favorites:collection}
                </option>
            {/favorites:collections}
            </select>
            <input type="text" name="notes" />
            <input type="submit" name="submit" value="Add" />
        {/exp:favorites:form}
        </p>
    {/if}
    {/exp:favorites:info}
{/exp:user:users}

Support

Having problems setting up and/or using Favorites? Support is offered from 10am to 4pm EST weekdays. Send us an email at help@eeharbor.com and we will respond as quickly as we can.