Skip to main content
With the $wsWatchList module, you can access the user’s watchlists (wish lists) and display them in the frontend. You can check whether products are on a watchlist, add or remove products, and display the watchlist in the basket. In this section, you will learn how to load and manage watchlists.

​
Module overview

Example / excerpt of $wsWatchList 
{{= $wsWatchList | json }}
JSON output: 
{
  "watchLists": [
    {
      "watchListId": "...",
      "watchListName": "..."
    }
  ],
  "countWatchListsWithProduct": "ƒ()",
  "isProductOnWatchList": "ƒ()",
  "loadWatchList": "ƒ()",
  "loadWatchListItemId": "ƒ()"
}
Note: ƒ() denotes a function. Variables and methods overview
NameReturn typeDescription
watchListsarrayReturns a list of all watchlists of the user.
[$i].watchListIdstringReturns the ID of the watchlist.
[$i].watchListNamestringReturns the name of the watchlist.
loadWatchList()mapLoads a watchlist by its ID.
isProductOnWatchList()boolChecks whether a product is on a specific watchlist.
countWatchListsWithProduct()intReturns the number of watchlists on which a specific product is.
loadWatchListItemId()stringReturns the ID of the watchlist item for a specific product.

​
Templates

Watchlist products are loaded via $wsWatchList in the template basket.htm. There they can be added to the basket or removed from the watchlist. Additionally, it is possible to display the watchlist in the header or in the off-canvas flyout.

​
Variables

​
$wsWatchList.watchLists

Returns a list of all the user’s watchlists. 
{{ foreach $myWatchlistVariable in $wsWatchList.watchLists }}
    {{= $myWatchlistVariable.watchListId }} - {{= $myWatchlistVariable.watchListName }}
{{ /foreach }}

​
Methods

​
$wsWatchList.loadWatchList()

Loads a watchlist by its ID. Signature
$wsWatchList.loadWatchList(watchlistId) Return value
map - WatchList map with all data. Parameters
NameTypeRequiredDescription
watchlistIdstringyesID of the watchlist.
Example that loads the default watchlist. 
{{ var $myWatchList = $wsWatchList.loadWatchList("watchlist_1_default") }}
By using the $wsWatchList.loadWatchList() function, various variables are available to retrieve and output further watchlist data. Below is an overview of which variables are available.

​
Watchlist data (return value of $wsWatchList.loadWatchList())

First, it is necessary to assign the map with the watchlist data, as shown in the example above, to a local variable. This can then be used at various places in the template. JSON output of the variable: 
{
  "id": "...",
  "watchListName": "...",
  "items": [
    {
      "id": "...",
      "freeFields": { },
      "product": { ... }
    }
  ]
}
Variables overview
VariableTypeDescription
idstringID of the watchlist.
watchListNamestringName of the watchlist.
itemsarrayList of products on the watchlist.
[$i].idstringID of the watchlist item.
[$i].freeFieldsmapUser-defined fields for the watchlist item (e.g. notes, desired quantity).
[$i].productmapProduct data (map “Product”).

​
$wsWatchList.isProductOnWatchList()

Checks whether a product is on a specific watchlist. Signature
$wsWatchList.isProductOnWatchList(watchlistId, productId) Return value
bool - true if the product is on the watchlist, otherwise false. Parameters
NameTypeRequiredDescription
watchlistIdstringyesID of the watchlist.
productIdstringyesID of the product.
Example that checks whether a product is on the watchlist. 
{{ if $wsWatchList.isProductOnWatchList("watchlist_1_default", $product.id) }}
  <span>On the watchlist</span>
{{ /if }}

​
$wsWatchList.countWatchListsWithProduct()

Returns the number of watchlists on which a specific product is. Signature
$wsWatchList.countWatchListsWithProduct(productId) Return value
int - Number of watchlists on which the product is. Parameters
NameTypeRequiredDescription
productIdstringyesID of the product.
Example that outputs the number of watchlists containing a product: 
On {{= $wsWatchList.countWatchListsWithProduct($product.id) }} watchlists

​
$wsWatchList.loadWatchListItemId()

Returns the ID of the watchlist item for a specific product. This ID is required to remove the product from the watchlist. Signature
$wsWatchList.loadWatchListItemId(watchlistId, productId) Return value
string - ID of the watchlist item. Parameters
NameTypeRequiredDescription
watchlistIdstringyesID of the watchlist.
productIdstringyesID of the product.
Example that loads the entry ID of a product. 
{{ var $myItemId = $wsWatchList.loadWatchListItemId("watchlist_1_default", $product.id) }}

​
Actions

Actions for this module that trigger changes are documented separately in the “Actions” chapter: Watchlist

​
Examples for displaying watchlist information

​
Check whether the watchlist contains products

This example checks whether the watchlist contains products and outputs the number of products. 
{{ if $wsWatchList.items }}
  <p>There are {{= $wsWatchList.items | len }} products on the watchlist</p>
{{ /if }}

​
Properties of the products on the watchlist

After the watchlist data has been loaded and assigned to a variable, you can output it flexibly. The assignment can be done as follows:

​
Display product data

This example outputs the usual product info, such as product name, price, and image. 
{{ if $wsWatchList.items }}
  {{ foreach $product in $wsWatchList.items }}
      <img src="{{= $watchListItem.product.custom.image.thumbnail }}" alt="{{= $watchListItem.product.name }}">
      <p>Product name: {{= $watchListItem.product.name }}</p>
      <p>Price: {{= $watchListItem.product.price }}</p>
  {{ /foreach }}
{{ /if }}

​
Display product variants

This example checks whether a product variant is on the watchlist. If so, the properties of the product variant are read out. 
{{if $wsWatchList.items}}
   {{ foreach $watchListItem in $wsWatchList.items }}
      ...
      {{ if $watchListItem.product.variantSelection }}
         {{ foreach $varAttr in $watchListItem.product.variantSelection | keys }}
            <p>{{= $varAttr}}: {{= $watchListItem.product.variantSelection[$varAttr] }} </p>
         {{ /foreach }}
      {{ /if }}
   {{ /foreach }}
   ...
{{/if}}

​
Show free fields on the watchlist

This example checks whether the product has free fields, such as country of origin or weight, and displays them. 
{{if $wsWatchList.items}}
   {{ foreach $watchListItem in $wsWatchList.items }}
      ...
      {{ if $watchListItem.freeFields }}
         {{ foreach $freeFieldName in $watchListItem.freeFields | keys }}
            <p>{{= $freeFieldName}}: {{= $watchListItem.freeFields[$freeFieldName] }}</p>
         {{ /foreach }}
      {{ /if }}
   {{ /foreach }}
   ...
{{/if}}

​
Add product to the basket

This example shows how a product is added from the watchlist to the basket. 
{{if $wsWatchList.items}}
   {{ foreach $watchListItem in $wsWatchList.items }}
      ...
      {{ var $basketItemAdd = $wsActions.create("BasketItemAdd", tag=$watchListItem.id) }}
      {{ if $basketItemAdd.error }}
         Errors occurred:
         {{ foreach $error in $basketItemAdd.errors }}
            {{ if $error.text }}
               <p> {{= $error.text }} </p>
            {{ else }}
               <p> {{= $error.code }} </p>
            {{ /if }}
         {{ /foreach }}
      {{ /if }}
      <form method="post" action="{{= $wsViews.viewUrl('basket.htm') }}">
         <input type="hidden" name="wscsrf" value="{{= $basketItemAdd.csrf }}">
         <input type="hidden" name="wsact" value="{{= $basketItemAdd.id }}">
         <input type="hidden" name="wstarget" value="{{= $wsViews.viewUrl('basket.htm') }}">
         <input type="hidden" name="productId" value="{{= $watchListItem.product.id }}">
         <input type="hidden" name="quantity" value="1">
         {{ foreach $freeFieldName in $watchListItem.freeFields | keys }}
            <input type="hidden" name="freeFields.{{= $freeFieldName}}" value="{{= $watchListItem.freeFields[$freeFieldName] }}">
         {{ /foreach }}
         <button type="submit">Add to basket</button>
      </form>
   {{ /foreach }}
   {{ else }}
   ...
{{/if}}

​
Delete product from the watchlist

This example shows how a product is deleted from the watchlist. 
{{if $wsWatchList.items}}
   {{ foreach $watchListItem in $wsWatchList.items }}
      ...
      {{ var $watchListItemDelete = $wsActions.create("WatchListItemDelete", tag=$watchListItem.id) }}
      {{ if $watchListItemDelete.error }}
         Errors occurred:
         {{ foreach $error in $watchListItemDelete.errors }}
            {{ if $error.text }}
               <p> {{= $error.text }} </p>
               {{ else }}
               <p> {{= $error.code }} </p>
            {{ /if }}
         {{ /foreach }}
      {{ /if }}
      <form method="post" action="{{= $wsViews.viewUrl('basket.htm') }}">
         <input type="hidden" name="wscsrf" value="{{= $watchListItemDelete.csrf }}">
         <input type="hidden" name="wsact" value="{{= $watchListItemDelete.id }}">
         <input type="hidden" name="wstarget" value="{{= $wsViews.viewUrl('basket.htm') }}">
         <input type="hidden" name="productId" value="{{= $watchListItem.product.id }}">
         <input type="hidden" name="watchListItemId" value="{{= $watchListItem.id }}">
         <button type="submit">Delete</button>
      </form>
   {{ /foreach }}
   {{ else }}
   ...
{{/if}}
You can find more practical examples on using the watchlist and watchlist functions here: → Practical examples: watchlist