Wishlist developer guide

The wishlist allows customers to keep track of products they are interested in. It allows customers to:

  • Add products to the wish list from a product cluster
  • Add products to the wish list from the product details page
  • See a summary of the wishlist on every page in the form of a mini wishlist
  • See the status of the wishlist (icon with counter)
  • See the list of items in the wishlist
  • Move products from the cart to the wishlist
  • Move products from the wishlist to the cart
  • Remove an item from the wishlist

Design

The wishlist is based on the normal Sitecore Commerce Cart functionality, but has its own UI components. The wishlist is part of the checkout and can be found in the Mercury.Feature.Checkout and the Mercury.Foundation.Checkout modules.

React components

Mini wishlist

  • miniwishlist.jsx
  • miniwishliststatus.jsx
  • miniwishlistlineitem.jsx

Main wishlist

  • mainwishlist.jsx
  • mainwishlistlineitem.jsx

The lineitems themselve reuse the lineitem field components that are in the lineitem subfolder. These are also used by the cart and the order components. This structure adheres to the atomic design principle that components should consist of (replaceable) building blocks.

Functionality

Add products to the wish list from a product cluster

The product cluster itself cannot yet be modified in Sitecore. Therefore, the add to wishlist button is hidden on the product cluster by default and can be shown / switched on in the wishlist settings. The wishlist settings can be added by creating a Sitecore item based on the /sitecore/templates/Mercury/Foundation/Checkout/Settings/Wishlist Settings template. The Enable field indicates if the add to cart button should be shown or not.

Add products to the wish list from the product details page

The add to wishlist button can be added to the product details page by adding the /sitecore/layout/Renderings/Mercury/Feature/Catalog/Product/AddToWishlist rendering to the presentation details.

See the status of the wishlist (icon with counter)

This will only show the icon of the wishlist with a number indicating the number of items in the wishlist. It can be added by using the following redering: /sitecore/layout/Renderings/Mercury/Feature/Checkout/Wishlist/MiniWishlistStatus

See a summary of the wishlist on every page in the form of a mini wishlist

This is the wishlist status with a flyout showing the wishlist status (mini wishlist). It can be added using the following rendering: /sitecore/layout/Renderings/Mercury/Feature/Checkout/Wishlist/MiniWishlist

See the list of items in the wishlist

The contents of the wishlist can be shown by adding the /sitecore/layout/Renderings/Mercury/Feature/Checkout/Wishlist/Wishlist rendering to a page. This list shows the same product properties as the cart, except for the quantity.

The catalog fields that are displayed in the line items are configured in the same way as the cart. These are defined per product type and can be found in the product type configuration based on the template: /sitecore/templates/Mercury/Foundation/Catalog/Settings/Product Type Settings. The exact same configuration is used for the cart and the wishlist. So changing these, will influence both.

Move products from the cart to the wishlist

The add to wishlist button in the cart is visible by default and can be hidden / switched off in the wishlist settings. The wishlist settings can be added by creating a Sitecore item based on the /sitecore/templates/Mercury/Foundation/Checkout/Settings/Wishlist Settings template. The Enable field indicates if the add to cart button should be shown or not.

Move products from the wishlist to the cart

The add to cart button in the wishlist moves an item from the wishlist to the cart. It is shown by default and can only be disabled by styling or overriding de wishlistlineitem UI component.

Remove an item from the wishlist

A button on each line item makes it possible for the customer to remove items from their wishlist.

Extension points

The wishlist feature provides the following pipelines as extension points for customization:

  • mercury.translate.wishlistToViewModel
  • mercury.checkout.addToWishlist

mercury.translate.wishlistToViewModel

Translates the wishlist connect entity to the Mercury view model that is serialized to the client in JSON. Override this to add custom fields to the wishlist.

mercury.checkout.addToWishlist

Contains the logic for adding the given product to the wishlist.

Used pipelines

The wishlist uses several pipelines of which the following are worth noting:

  • commerce.carts.addCartLines
  • commerce.carts.removeCartLines

Adding a custom lineitem

The wishlist UI components use the same extension mechanism as the cart. A custom line item strategy can be registered by calling MercuryCheckout.checkout.registerLineItemStrategy. A strategy is a JavaScript component that needs to implement the method: getLineItemComponent. This method takes a cartType and a lineitem. The cartType can be:

  • maincart
  • minicart
  • cartsummary
  • order
  • mainwishlist
  • miniwishlist

Based on this and the lineitem, which contains the line item data, the strategy can return a custom lineitem component. The wishlist, cart, etc. will evaluate all the registered strategies and use the component that is returned first.

Extending a wishListLine

A wishListLine can be extended with additional fields by specifing a different commerce entity in the config. For example:

<commerce.Entities>
  <WishListLine>
    <patch:attribute name="type">YourClass, YourNamespace</patch:attribute>
  </WishListLine>
</commerce.Entities>
Note

Note that the custom wishListLine needs to inherit from the MercuryWishListLine class.

For mapping the additional fields an processor needs to be added to the following pipelines:

  • mercury.translate.cartLineToWishListLine
  • mercury.translate.wishListLineToCartLine

An example of such a processor is provided below.

using Mercury.Foundation.Checkout.Models;
using Mercury.Foundation.Checkout.Pipelines.TranslateWishListLineToCartLine;

namespace MyNamespace
{
    public class MyProcessor : TranslateWishListLineToCartLineProcessor
    {
        protected override void TranslateToWishListLineItem(TranslateWishListLineToCartLineRequest request, MercuryCartLine destination)
        {
            var origin = request.WishListLine as MyWishlistLine;
            var myDestination = destination as MyCartLine;

            myDestination.MyField = origin.MyField;
        }
    }
}

Extending the wishList

The wishList can be extended with additional fields by specifying a different commerce entity in the config and extending the 'mercury.translate.cartToWishList' pipeline.