Favorite Lists

Introduction

Users save products on a favorite list. An app either provides a single list, or lets the user create, rename, and delete several named lists and choose a list when a product is saved. Which of the two applies depends on the app configuration and on the pipelines that the connected shop system provides.

The frontend uses the same actions and selectors in both cases. An app without support for multiple lists works with one implicit list that has the ID DEFAULT, so extension code that passes a list ID keeps working, and code that omits it addresses that single list.

Enabling Multiple Lists

Support for multiple favorite lists is active when one of the following applies:

• The @shopgate/connect core extension is attached to the app. It is the connection to the Omnichannel services, which implement the list pipelines.
• The app configuration sets favoritesMode.hasMultipleFavoritesLists. Use this for a shop system whose own favorites extension implements the list pipelines.

The selector getHasMultipleFavoritesListsSupport evaluates both conditions. Use it in an extension instead of checking the configuration directly.

When neither applies, the app never calls the list pipelines. fetchFavoritesLists then returns a single list with the ID DEFAULT and an empty name, without sending a request.

Required Pipelines

An extension that provides favorites for a shop system has to implement the following pipelines to support multiple lists. See the Favorite pipeline reference for their inputs and outputs.

Pipeline	Purpose
shopgate.user.getFavoritesLists.v1	Returns all lists of the user
shopgate.user.addFavoritesList.v1	Creates a list and returns its ID
shopgate.user.updateFavoritesList.v1	Renames a list
shopgate.user.removeFavoritesList.v1	Deletes a list and its items

In addition, the pipelines that operate on the items of a list receive a favoritesListId:

Pipeline	Purpose
shopgate.user.getFavorites.v1	Returns the products of one list
shopgate.user.getFavorites.v2	Returns the items of one list, including quantity and notes
shopgate.user.addFavorites.v1	Adds a product to a list
shopgate.user.updateFavorites.v1	Updates the quantity or the note of an item
shopgate.user.deleteFavorites.v1	Removes a product from a list

The app only sends favoritesListId when support for multiple lists is active. An extension that implements the item pipelines without the list pipelines therefore continues to work, and receives requests without that field.

Working With Lists in an Extension

Retrieve the lists before you use them. The lists are cached, so the action sends a request only when the cache has expired or when ignoreCache is set.

import { fetchFavoritesLists, getFavoritesLists } from '@shopgate/engage/favorites';

dispatch(fetchFavoritesLists());

const lists = getFavoritesLists(getState());
// [{ id: '1', name: 'Wishlist' }, { id: '2', name: 'Birthday' }]

To retrieve the lists together with their items, use fetchFavoritesListsWithItems.

To add a product from your own component, dispatch toggleFavoriteWithListChooser. It adds the product when the user has one list, and opens the list chooser when the user has more than one, so your component does not have to handle the two cases.

import { toggleFavoriteWithListChooser } from '@shopgate/engage/favorites';

dispatch(toggleFavoriteWithListChooser(productId));

When your extension already knows the target list, address it directly.

import { addFavorite, removeFavorites } from '@shopgate/engage/favorites';

dispatch(addFavorite(productId, listId));
dispatch(removeFavorites(productId, false, listId));

For the complete parameter lists, see the Favorites Actions reference.

Quantity and Notes

An item can carry a quantity and a note. Both are optional app settings, and the app sends the corresponding fields only when the setting is enabled. Version 2 of the getFavorites pipeline returns them with every item, version 1 does not.

Backwards Compatibility

An app that supports multiple lists sends favoritesListId to the item pipelines. A favorites extension that was written before the feature has to ignore unknown input fields rather than reject the request. Extensions that were built against Engage Theme versions below 6.7.0 use shopgate.user.putFavorites.v1 to replace the whole list, which remains supported.