> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# $wsWatchList - Watchlists

> Reference for $wsWatchList: load and manage customer watchlists, check if products are saved and display wish list items in WEBSALE templates.

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`

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{= $wsWatchList | json }}
```

**JSON output:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "watchLists": [
    {
      "watchListId": "...",
      "watchListName": "..."
    }
  ],
  "countWatchListsWithProduct": "ƒ()",
  "isProductOnWatchList": "ƒ()",
  "loadWatchList": "ƒ()",
  "loadWatchListItemId": "ƒ()"
}
```

**Note:** `ƒ()` denotes a function.

**Variables and methods overview**

| **Name**                       | **Return type** | **Description**                                                  |
| ------------------------------ | --------------- | ---------------------------------------------------------------- |
| `watchLists`                   | array           | Returns a list of all watchlists of the user.                    |
| `[$i].watchListId`             | string          | Returns the ID of the watchlist.                                 |
| `[$i].watchListName`           | string          | Returns the name of the watchlist.                               |
| `loadWatchList()`              | map             | Loads a watchlist by its ID.                                     |
| `isProductOnWatchList()`       | bool            | Checks whether a product is on a specific watchlist.             |
| `countWatchListsWithProduct()` | int             | Returns the number of watchlists on which a specific product is. |
| `loadWatchListItemId()`        | string          | Returns 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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ 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**

| **Name**      | **Type** | **Required** | **Description**      |
| ------------- | -------- | ------------ | -------------------- |
| `watchlistId` | string   | yes          | ID of the watchlist. |

**Example** that loads the default watchlist.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ var $myWatchList = $wsWatchList.loadWatchList("watchlist_1_default") }}
```

<Info>
  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.
</Info>

### 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:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "id": "...",
  "watchListName": "...",
  "items": [
    {
      "id": "...",
      "freeFields": { },
      "product": { ... }
    }
  ]
}
```

**Variables overview**

| **Variable**      | **Type** | **Description**                                                            |
| ----------------- | -------- | -------------------------------------------------------------------------- |
| `id`              | string   | ID of the watchlist.                                                       |
| `watchListName`   | string   | Name of the watchlist.                                                     |
| `items`           | array    | List of products on the watchlist.                                         |
| `[$i].id`         | string   | ID of the watchlist item.                                                  |
| `[$i].freeFields` | map      | User-defined fields for the watchlist item (e.g. notes, desired quantity). |
| `[$i].product`    | map      | Product 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**

| **Name**      | **Type** | **Required** | **Description**      |
| ------------- | -------- | ------------ | -------------------- |
| `watchlistId` | string   | yes          | ID of the watchlist. |
| `productId`   | string   | yes          | ID of the product.   |

**Example** that checks whether a product is on the watchlist.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ 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**

| **Name**    | **Type** | **Required** | **Description**    |
| ----------- | -------- | ------------ | ------------------ |
| `productId` | string   | yes          | ID of the product. |

**Example** that outputs the number of watchlists containing a product:

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
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**

| **Name**      | **Type** | **Required** | **Description**      |
| ------------- | -------- | ------------ | -------------------- |
| `watchlistId` | string   | yes          | ID of the watchlist. |
| `productId`   | string   | yes          | ID of the product.   |

**Example** that loads the entry ID of a product.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ 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](/en/frontend/referenz/aktionen/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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ 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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ 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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{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](/en/frontend/praxisbeispiele/memolist-offcanvas)

***

## Related links

* [Memolist (offcanvas)](/en/frontend/praxisbeispiele/memolist-offcanvas)
* [\$wsBasket](/en/frontend/referenz/module/wsbasket)