Introduction


Once you have the Swym Wishlist app installed on your store, getting the Add to Wishlist button across all the product touch-points such as collections pages, quick-view pop-ups, related products widgets etc can help a lot in driving user engagement with the Wishlist module. The Add to Wishlist button is injected out of the box on all your product pages. However, given the diversity of third party tools that one can use to build collections pages, search pages, quick-view pop-ups, related products widgets etc, the wishlist button won't appear out of the box across all your site pages.


Good news is, no matter which apps you might be using for any of the other experiences, Swym Wishlist can be integrated with the same 2 steps -


  1. Provide the data on the product - For Swym to add the correct product and its variant to the wishlist, it needs some basic information about the product in a pre-defined data object. 

  2. Initialize the click listener - once the wishlist button is ready with the data object, Swym needs to attach a click listener to the button so when the user clicks on it, the product is added to the user's wishlist.


Let's go over each of these two steps in more detail and then go into some examples of implementations from the wild. 


Provide the data


If you are a Shopify customer, you will see the file "swym-product-view.liquid" in your theme files. This file gets created at the time of installation of the Swym Wishlist Plus app. Let's open up this file and take a peek.


As you might notice, this file puts data together for a particular product. In the end, we have two objects - SwymViewProducts and SwymWatchProducts that contain data about the products on the current page with the product id as the key.

If you have implemented Wishlist on collections page using our customization blog post, but don't see the button, a popular way to debug is to look at the object SwymViewProducts in the developer console. If you don't see the data for the product, you might need to look at how products are rendered on your site. Here is what the SwymViewProducts object looks like - 




Initialize the click listener

Once the data is in place, Swym needs to attach the add to wishlist click listener to the button. Below is the default button markup we suggest for a simple add to wishlist button on a non-product page.


<button class="swym-button swym-add-to-wishlist-view-product product_{{product.id}}" data-swaction="addToWishlist" data-product-id="{{product.id | json}}" ></button>


Here, the highlighted attributes uniquely identify a button that can be initialized with Swym Wishlist. In other words, if you create your own button with these 2 attributes, your button should add the product to the user's wishlist as long as the data is available. 


Swym defers loading its Javascript package until all the critical resources have loaded. This ensures none of our code gets in the way of the site's load time.  By default, once the page is ready, our code looks at all the elements in DOM at that point, searches for elements with these attributes and attaches a click listener to them. However, if your button gets injected into the DOM at a later point in time (and not on page load), you will have to attach the click listener with the following API in your code once the button is rendered - 


_swat.initializeActionButtons(<< selector of the element containing wishlist button >>);


/* eg. if the markup is -


<div class="collections-listing">

  <a data-swaction="addToWishlist" data-product-id="{{product.id | json}}">

    Add to Wishlist

  </a>

</div>


Below is how you would initialize the button -

*/


_swat.initializeActionButtons('.collections-listing');


Cases from the wild

Case 1 - simple collections page


Please note, most of the examples here are Shopify specific and might use some liquid context. 


Let's say you are looking to add the wishlist button on your collections page. If your collections page is rendered using liquid, adding the following lines of code in the theme file that renders each product item should work - 


{% include 'swym-product-view', product: product %}


<button class="swym-button swym-add-to-wishlist-view-product product_{{product.id}}" data-swaction="addToWishlist" data-product-id="{{product.id | json}}"></button>


Here, we are passing the liquid product object to the "swym-product-view" liquid snippet and adding the wishlist button markup. 


Case 2 - simple collections page with a custom button


Let's say you have a theme that already comes with a wishlist button on the collections pages, or you have a custom button you have built for your site. To integrate this button with the Swym Wishlist, all you will need to do is add data-swaction="addToWishlist" and data-product-id  attributes to your button. Here's a quick example - 



{% include 'swym-product-view', product: product %}

    

<!-- My custom button  -->

<a class="wishlist-btn" data-swaction="addToWishlist" data-product-id="{{product.id | json}}">

   <img src="{{ 'like.png' | asset_img_url: '20x' }}" />

</a>


Here's how my custom button looks - 


Getting the state right

If you follow the steps above, you will see your button working but it won't update the button state or show the correct state on a page refresh. Displaying the correct state on the collections page will show your customers which products they already have in their wishlists. However, with what we have done so far, even if the product is added to wishlist, the button would appear the same. Since the button lies outside Swym, it's not possible for us to update the button correctly. Let's look at our custom button once again - 



Once the product is added to the wishlist, there is extra class that gets added to the button. As we can see, this class is "swym-added" . We can use this class to modify how our button looks once its added to wishlist. Below is how I have structured my CSS to change the way the button looks once clicked and the end-product.



.wishlist-btn {

  float: right; 

  top: 4px;

  position: relative;

  z-index: 100;

  cursor: pointer;

  background-image: url("{{ 'like.png' | asset_img_url: '20x' }}");

  height: 20px;

  width: 20px;

}


.wishlist-btn.swym-added {

  background-image: url("{{ 'like_1.png' | asset_img_url: '20x' }}");

}


If you want to enable clicking the button again to remove from wishlist, please contact our support team. It's a simple setting that we can enable from our side.


Note: If you have the remove from wishlist on second click feature enabled but it doesn't seem to work, please check if you have "pointer-events : none" CSS property set on the wishlist button. Many common CSS files have that CSS for a button with the class "disabled", which the wishlist button also has when a product is added to the wishlist.

Case 3 - collections page with BCSF filters app


If you are using BCSF filters app, or any other app that converts the default pagination on the collections page into a lazily loaded collections page with filters, the Swym Wishlist will not show up after the first page load. This is because the second page of the collection is loaded on-demand. Swym doesn't have the product data and doesn't know when to initialize the add-to-wishlist buttons on the newly added products. For this use-case, we have to perform the same 2 steps with the bc-sf filters library, just in a slightly different manner.


Step 1 - Getting the data with BCSF filter app 


On installation of the BCSF filters app, it adds a file named "bc-sf-filter.js" to your theme. This file contains the entire logic to render product list items on your collections pages. Let's look at the first few lines of code in the file.

The app creates a string for the product markup and for all the widgets it renders on the collections page. In the "buildProductListItem" function, it runs a search-and-replace procedure to inject the relevant product data for each of the strings with the curly braces.  For our use-case, we need to create a similar replaceable string to get the product data. The full code to add the data variables is here.

This is a good example of a use-case when the product data comes from a JavaScript object, instead of a liquid data object. Even though the data format is different, the process remains fairly identical.

Step 2 - Initializing the click listener

In the same file "bc-sf-filter.js", there is a function called "buildExtrasProductList" that gets called once the product tiles are rendered. This gives us the perfect opportunity for us to initialize our button with the following code - 


<script>

  if(window._swat){

    window._swat.initializeActionButtons("#bc-sf-filter-products");

  }else{

    window.SwymCallbacks = window.SwymCallbacks || [];


    window.SwymCallbacks.push(function(){

      window._swat.initializeActionButtons("#bc-sf-filter-products");

    });

  }

</script>


If you are

Case 4 - quick-view popup with Secomapp quick view


The Secomapp quick view installs a quick view popup for each of the product list items on your collections pages. To add the Wishlist button on your quick view popup, please contact our support team. Since this is a fairly common ask, we have written code that can do the heavy lifting for you. Our code covers the Secomapp quick view app, fancybox ajax and colorbox for quick view.


Even if you are working with quick view apps that are not among the ones mentioned above, the steps remain more or less the same - 

  1. Try to find how the quick view plugin is getting the product data. If its liquid, simply include the "swym-product-view.liquid" snippet in your quick view file. If it's not liquid, try to find a way to get access to the product data and create the relevant data objects.

  2. Find a point in code when the quick view is rendered with the wishlist button markup. If you are using Google Chrome, a good way to find the Javascript function that might be rendering the quick view is to go into the Network tab with "XHR" filter, find the API call that might be getting the product data for the desired product and hover over the "Initiator" column (as shown in the image below). This will give you the stack of files and their corresponding functions that were involved in making the XHR call for the quick view. Probing into one of these files will give you the right function that gets called once the quick view has rendered. If  _swat.initializeActionButtons is called at this point with the right parameters, the wishlist button should start showing up.



Case 5 - adding to wishlist with minimal data


On our paid plans (Pro and higher), we offer a simpler way to add a product to wishlist on collections or quick page. Instead of having to create the complete product data, you can simply pass the product id and the variant id with the wishlist button. The app will then automatically fetch the data from your store in real-time and render the rest of the data. In addition to being a much simpler implementation, this also ensures that only the most current data is displayed to the user on the Wishlist. If you have products that are frequently getting updated with changes in price, the image etc, using this approach will ensure users are always seeing the latest version of the product in their Wishlist. Here's a sample code snippet that illustrates how to accomplish this - 


<button class="swym-button swym-add-to-wishlist-view-product product_{{product.id}}" data-swaction="addToWishlist" data-with-epi="true" data-product-id="{{product.id | json}}" data-variant-id="{{product.variants[0].id | json}}"></button>


While defining the button markup, if you pass the product id and the variant id to add to wishlist as shown in yellow, Swym's Wishlist API pulls the rest of the data from its product data repository and adds the product to the user's wishlist. For a custom collections page or a quick view page, this can save a lot of time in doing the step 1 of the process explained in this post - you only have to find a way of getting the product id and the variant id. Also, the "swym-product-view.liquid" snippet isn't needed anymore since the complete product data comes from Swym's backend services.



Conclusion

Although the most common scenarios are covered here, there will be cases from the wild that might not cover the steps suggested here. Please reach out to our support team if your use-case isn't amongst the ones mentioned here. We also have a powerful set of Javascript APIs that you can use regardless of the apps you might be using for your collection or quick view pages. Check out our quick start with Swym JS APIs blog to get started.