Upgrading from Favorites 3.x to 5.x

Favorites 4.x was a very significant update to the add-on (Favorites 5.x contains no changes from 4.x), and this page should be very carefully read before performing an update to Favorites from 3.x on your site. It's highly recommended that you setup a staging server to perform the Favorites 3.x to 5.x update so the transition is smooth for your site users.

Here's a list of the key changes beginning in Favorites 4.x:

• Favorites are no longer saved through links to the Favorites:Save tag. This method was flawed in that the data could be manipulated, and that it was not flexible in what could be done with the data. We have replaced this functionality with the new Favorites:Form and Favorites:Edit tags, which use a form process to securely save favorites, along with other data such as collection name and notes. More information is available below.
• Favorites 4.x allows your users to favorite member profiles now, so the favoriting process now accounts for the option to save a channel entry as a favorite, or a member profile as a favorite.
• There is no longer the concept of public and private favorites. Instead, a new concept of collections has been introduced. Collections are created by admin(s), and you can have as many as you like, with whatever names you like. If your site still relies on the need to have public and private favorites, then you can simply have a public collection and a private collection. The upgrade process from Favorites 3.x to 4.x automatically does this. Then just update your template tags to include the collection parameter and only specify public.
• Multiple favorites can be saved for the same entry/member. Because of this, favorites data isn't readily available for all the template tags the same way it used to be. Instead, a new looping template tag named Favorites:Info needs to be called to display favorites info about each entry/member for the currently logged in user.
• Almost all template tags have been renamed for a variety of reasons - accounting for differences between channel entry favoriting and member favoriting, renaming template tags to be more obvious about what they do, etc.

Here is the detailed list of changes:

• Renamed Template Tags
• Removed Template Tags
• New Template Tags
• Unchanged Template Tags
• Introduction to Collections
• Changes to Favorite Saving Process
• Prefixed Variables
• Robust Pagination & Count/Results Variable Support

Renamed Template Tags

Below is a list of all template tags that have been renamed from Favorites 3.x to 4.x.

• Favorites:Entry_Count --> changed to Favorites:Count, and updated to account for both entries and members.
• Favorites:Shared --> changed to Favorites:Related_Entries for channel entries (and Favorites:Related_Members for members).
• Favorites:Rank --> changed to Favorites:Rank_Entries for channel entries (and Favorites:Rank_Members for members).
• Favorites:Author_Rank --> changed to Favorites:Rank_Authors to be more consistent with the other Rank tag names.
• Favorites:Members --> changed to Favorites:Saved_By to better clarify what it does, and free up the Favorites:Members tag name for member profile favoriting functionality.

Removed Template Tags

Below is a list of all template tags that have been removed in Favorites 4.x.

• Favorites:Saved in favor of the new robust looping Favorites:Info tag.
• Favorites:Save in favor of new Favorites:Form and Favorites:Edit tags.

New Template Tags

Below is a list of all template tags that are new for Favorites 4.x.

• Favorites:Form to securely handle and enhance the adding of new favorites.
• Favorites:Edit for the ability to edit/update favorites.
• Favorites:Info a loop that is used for displaying the currently logged in members favorite data for each entry/member, and helping with handling the formatting for adding/removing/editing favorites.
• Favorites:Members displays all saved member account favorites for the currently logged in user.
• Favorites:Collections displays a list of all collections for the site, filterable by entry collections or member collections (or both).
• Favorites:Collection_Form for adding and updating existing collections on the front end templates.
• Favorites:Rank_Members for displaying a list of most favorited members (like Favorites:Rank_Entries).
• Favorites:Related_Members for displaying a list of other member profiles saved as favorites by users that also saved the given member (like Favorites:Related_Entries).

Unchanged Template Tags

Below is a list of all template tags that have been unchanged for Favorites 4.x.

• Favorites:Delete_All --> remains unchanged, but includes type parameter to distinguish whether you want to delete all entry favorites or member favorites.

Introduction to Collections

Favorites 4.x introduces a new feature called collections. It essentially allows your users to save their favorites into different groups. This is an optional feature. If you wish not to use collections, just don't create any additional collections to the 1 default collection, and let all favorites be saved to that one.

• Collections are global: all users see the same list of collections available (though you could technically manipulate this to a small extent by applying the collection parameter on relevant tags or by using member group conditionals)
• Collections are pre-defined: collections are created/edited/removed in the Favorites module control panel area. Favorites can also be administrated by Admins via the front end with the use of the Favorites:Collection_Form tag, though we strongly recommend you wrap the template tag in member group conditionals and only let admins have access to it.
• A collection parameter is available in all Favorites template tags, allowing you to filter results by collection names.
• The availability of collections allows users to save the same entry or member multiple times to different collections if they want (if you allow it).
• All of the code examples in Favorites documentation will show a collection select menu in place for adding/editing favorites, but it is not required to be used. If you want to simplify the favorites implementation on your site and not use collections, simply ignore the collection field altogether. Favorites will just automatically assign the default collection, and other template tags will assume that as well. Simply put, you can pretend that the collection feature does not exist, if you wish.

Changes to Favorite Saving Process

The old way of setting up favoriting logic looked like this:

{exp:channel:entries}
    <h2>{title}</h2>
    <p>{body}</p>
    <ul>
    {exp:favorites:saved
        entry_id="{entry_id}"
    }
    {if not_saved}
        <li>
            <a href="{permalink='favorites/save'}">
                Add this entry to my favorites
            </a>
        </li>
    {/if}
    {if saved}
        <li>
            <a href="{permalink='favorites/save'}/delete/">
                Remove from my favorites
            </a>
        </li>
    {/if}
    {/exp:favorites:saved}
    </ul>
{/exp:channel:entries}

...With the favorites/save template containing this:

{exp:favorites:save}

This is the new way of setting up your template:

{exp:channel:entries}
    <h2>{title}</h2>
    <p>{body}</p>
    {exp:favorites:info
        entry_id="{entry_id}"
    }
        <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}

Prefixed Variables

All variables across all Favorites template tags are now prefixed with favorites: to avoid any parsing conflicts with other template tags. This allows for nesting Favorites tags into other template tags such as Channel:Entries without having variables colliding. For example, {count} within the Favorites:Info tag becomes {favorites:count}.

Robust Pagination & Count/Results Variable Support

All Favorites template tags include robust support for advanced pagination (remember that some of the variable pairs are prefixed):

{favorites:paginate}
    <ul class="pagination">
    {favorites:pagination_links}
        {first_page}
            <li><a href="{pagination_url}">First</a></li>
        {/first_page}
        {previous_page}
            <li><a href="{pagination_url}">&laquo; Previous</a></li>
        {/previous_page}
        {page}
            <li{if current_page} class="active"{/if}><a href="{pagination_url}">{pagination_page_number}</a></li>
        {/page}
        {next_page}
            <li><a href="{pagination_url}">Next &raquo;</a></li>
        {/next_page}
        {last_page}
            <li><a href="{pagination_url}">Last</a></li>
        {/last_page}
    {/favorites:pagination_links}
    </ul>
{/favorites:paginate}

All Favorites template tags include robust support for count and total results variables (remember that these are prefixed):

{favorites:count}
{favorites:total_results}
{favorites:absolute_count}
{favorites:absolute_results}