> ## 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.

# $wsInserts - Insert codes

> Module $wsInserts: read the insert code remembered for each product and the insert code settings in the frontend for the product detail page, category tiles and the basket.

With the `$wsInserts` module, you can retrieve the [insert codes](/en/frontend/funktionsubersicht/werbemittelkennzeichnung) that the shop has remembered for individual products, as well as the insert code settings. The module provides the remembered code wherever a product is displayed, including category tiles and the product detail page, not just in the basket.

This page is about reading the values. How the shop captures and validates an insert code and assigns it to a basket item is described in the [insert codes feature overview](/en/frontend/funktionsubersicht/werbemittelkennzeichnung). The code of a basket item that has already been added is provided by [\$wsBasket](/en/frontend/referenz/module/wsbasket) via `$item.insert`.

***

## Basic concept

`$wsInserts` is a read-only module. It combines two types of information:

* **Remembered codes per product** in `byProduct`: If a customer calls up a product with an insert code, for example via a link from a mailing, the shop remembers the corresponding code. `byProduct` returns this code and checks it against the codes valid for the product.
* **The settings** in [`enabled`](#wsinserts-enabled), [`separator`](#wsinserts-separator), [`position`](#wsinserts-position) and `defaultInsertCode`: have the same values as in `$wsConfig.inserts`. This means a single object is sufficient in templates dealing with insert codes, while `$wsConfig.inserts` remains available.

The module does not return the finished display of item number and code. It is generated in the template using the `components/itemNumberWithInsert.htm` component, see [Examples](#examples-of-data-access).

***

## Module overview

**Example / excerpt of** `$wsInserts`

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

**JSON output**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "enabled": true,
  "separator": "-",
  "position": "after",
  "defaultInsertCode": "",
  "byProduct": {
    "71-3953": "09",
    "<ID einer Variante>": "DA"
  }
}
```

**Module variables**

| **Variable** | **Return type** | **Description** |
| - | - | - |
| `byProduct` | map | Remembered, valid insert codes per product. The key is the product ID, or the full variant ID for variants. |
| `enabled` | bool | Whether the insert codes feature is active in the shop. |
| `separator` | string | Separator between item number and code. |
| `position` | string | Position of the code relative to the item number: `before` or `after`. |
| `defaultInsertCode` | string | Default code that applies if no code or an invalid code was entered. Can be empty. |

***

## Templates

The module can be used on any page where products are displayed. Typical use cases are:

* **Product detail page:** display the item number with the remembered code after the customer has arrived via a link with an insert code.
* **Category tiles and product lists:** output the remembered code for every product that has one.
* **Basket and checkout:** only display output related to insert codes when the feature is active (`enabled`).

***

## Variables

### \$wsInserts.byProduct

Returns the remembered insert codes per product. Using the product ID as the key, you can read the code for a specific product.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{= $wsInserts.byProduct[$cProduct.id] }}
```

The following behavior applies:

* The key is the full product ID. For variants, it includes the corresponding variant. Therefore, two variants of the same product each have their own entry.
* Each code is checked against the codes valid for the respective product. If the remembered code is invalid, the [default code](/en/frontend/funktionsubersicht/werbemittelkennzeichnung#configuration) is displayed instead, provided one is configured.
* Products without a remembered code and products for which no valid code results are missing from the list. Access then returns an empty value.
* If the feature is deactivated, `byProduct` is empty.
* The remembered codes only apply to the current session. After the order is completed, a new session begins, so they are discarded. In addition, the shop resets the codes when the basket is emptied on logout or when switching customer accounts.

### \$wsInserts.enabled

Returns whether the insert codes feature is active in the shop. Use this value to display output related to insert codes only when the feature is active.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ if $wsInserts.enabled }}
  <!-- Output for insert codes -->
{{ /if }}
```

### \$wsInserts.separator

Returns the configured separator between item number and code, for example `-`.

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

### \$wsInserts.position

Returns whether the code is placed before (`before`) or after (`after`) the item number.

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

### \$wsInserts.defaultInsertCode

Returns the configured default code. If none is set, the value is empty.

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

<Note>
  The `insertCodeLength` setting from the [content.inserts](/en/konfiguration/content-katalog-kategorien-produkte#content-inserts-insert-code) configuration node is not available in the template, neither via `$wsInserts` nor via `$wsConfig.inserts`.
</Note>

***

## Examples of data access

### Display the item number with the remembered insert code on the product detail page

If a code is stored for the product, pass it together with the item number to the `components/itemNumberWithInsert.htm` component. The component takes the separator and position into account.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ if $wsInserts.enabled and $wsInserts.byProduct[$cProduct.id] }}
  <p>Item no.: {{ include "components/itemNumberWithInsert.htm" with $cNumber = $cProduct.itemNumber, $cCode = $wsInserts.byProduct[$cProduct.id] }}</p>
{{ else }}
  <p>Item no.: {{= $cProduct.itemNumber }}</p>
{{ /if }}
```

**Result** <br />If the customer arrives at the product page via the link `/buntes-t-shirt?insert=09`, the item number `123456-09` is displayed. Without a remembered code, only the plain item number is displayed.

### Display the remembered code on a category tile

In a product tile, you have access to the ID of the respective product. This way, the notice only appears for products that have a code stored.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ var $cInsert = $wsInserts.byProduct[$cProduct.id] }}
{{ if $cInsert }}
  <span class="badge">Insert code {{= $cInsert }}</span>
{{ /if }}
```

**Result** <br />Only tiles of products with a remembered code display the notice "Insert code" together with the code.

***

## Related links

* [Insert codes](/en/frontend/funktionsubersicht/werbemittelkennzeichnung): functional overview with entry methods, resolution logic and setup.
* [\$wsBasket](/en/frontend/referenz/module/wsbasket): insert code and item number per basket item via `$item.insert` and `$item.itemNumber`.
* [\$wsConfig](/en/frontend/referenz/module/wsconfig): the same settings via `$wsConfig.inserts`.
* [content - Catalog](/en/konfiguration/content-katalog-kategorien-produkte#content-inserts-insert-code): configuration node `content.inserts`.


## Related topics

- [Insert codes](/en/frontend/funktionsubersicht/werbemittelkennzeichnung.md)
- [$wsBasket - Basket](/en/frontend/referenz/module/wsbasket.md)
- [$wsConfig - Configuration](/en/frontend/referenz/module/wsconfig.md)
- [content - Catalogue (categories & products)](/en/konfiguration/content-katalog-kategorien-produkte.md)
- [$wsDirectOrder - Direct order](/en/frontend/referenz/module/wsdirectorder.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.