$wsInserts - Insert codes - WEBSALE Dokumentation

With the $wsInserts module, you can retrieve the insert codes 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. The code of a basket item that has already been added is provided by $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, separator, 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.

Module overview

Example / excerpt of $wsInserts

{{= $wsInserts | json }}

JSON output

{
  "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.

{{= $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 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.

{{ if $wsInserts.enabled }}
  <!-- Output for insert codes -->
{{ /if }}

$wsInserts.separator

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

{{= $wsInserts.separator }}

$wsInserts.position

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

{{= $wsInserts.position }}

$wsInserts.defaultInsertCode

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

{{= $wsInserts.defaultInsertCode }}

The insertCodeLength setting from the content.inserts configuration node is not available in the template, neither via $wsInserts nor via $wsConfig.inserts.

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.

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

{{ var $cInsert = $wsInserts.byProduct[$cProduct.id] }}
{{ if $cInsert }}
  <span class="badge">Insert code {{= $cInsert }}</span>
{{ /if }}

Result
Only tiles of products with a remembered code display the notice “Insert code” together with the code.

Insert codes: functional overview with entry methods, resolution logic and setup.
$wsBasket: insert code and item number per basket item via $item.insert and $item.itemNumber.
$wsConfig: the same settings via $wsConfig.inserts.
content - Catalog: configuration node content.inserts.

Frontend

The basics

Getting started

Feature overview

Examples

Reference – Actions

Reference – Language

Reference – Modules

$wsInserts - Insert codes

Basic concept

Module overview

Templates

Variables

$wsInserts.byProduct

$wsInserts.enabled

$wsInserts.separator

$wsInserts.position

$wsInserts.defaultInsertCode

Examples of data access

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

Display the remembered code on a category tile

​Basic concept

​Module overview

​Templates

​Variables

​$wsInserts.byProduct

​$wsInserts.enabled

​$wsInserts.separator

​$wsInserts.position

​$wsInserts.defaultInsertCode

​Examples of data access

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

​Display the remembered code on a category tile

​Related links

Basic concept

Module overview

Templates

Variables

$wsInserts.byProduct

$wsInserts.enabled

$wsInserts.separator

$wsInserts.position

$wsInserts.defaultInsertCode

Examples of data access

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

Display the remembered code on a category tile

Related links