$wsProducts - Product data - WEBSALE Dokumentation

With the $wsProducts module, you can dynamically load and display product data in the frontend.

Module overview

Example / excerpt of $wsProducts

{{= $wsProducts | json }}

JSON output

{
  "load": "ƒ()",
  "loadByNumber": "ƒ()",
  "loadByCustomNumber": "ƒ()",
  "variantInfo": "ƒ()"
}

Note: ƒ() denotes a function. Methods overview

Method	Return type	Description
`load()`	map	Returns a product based on the product ID.
`loadByNumber()`	map	Returns a product based on the item number.
`loadByCustomNumber()`	map	Returns a product based on a user-defined number.
`variantInfo()`	map	Returns the variant data for a product.

Templates

By default, products are displayed via the template product.htm. This is located in the views directory. The name product.htm and the storage location must not be changed, as the template is hard-wired in the software and is not configurable or customizable. However, product data can be flexibly integrated on other pages as well, for example:

Home page → display of top sellers, offers, or a product selection.
Basket page → cross-selling products as purchase recommendations.
Category pages & search results → custom product lists with filters.
Checkout & order confirmation → display of complementary products or discount campaigns.

With $wsProducts, product information can be retrieved dynamically and integrated individually into various templates to enable targeted presentation of items.

Variables

No variables are available for $wsProducts.

Methods

$wsProducts.load()

Returns a product based on the product ID. Signature
$wsProducts.load(productId) Return value
map - Product map with all product data. Parameters

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

Example that loads a product and outputs the product name.

{{ var $myProduct = $wsProducts.load("100-12345") }}
Name: {{= $myProduct.name }}

$wsProducts.loadByNumber()

Returns a product based on the item number. Signature
$wsProducts.loadByNumber(itemNumber) Return value
map - Product map with all product data. Parameters

Parameter	Type	Required	Description
`itemNumber`	string	yes	Item number of the product.

Example that loads a product by item number:

{{ var $myProduct = $wsProducts.loadByNumber("ART-001") }}
Name: {{= $myProduct.name }}

$wsProducts.loadByCustomNumber()

Returns a product based on a user-defined number, for example EAN or GTIN. Signature
$wsProducts.loadByCustomNumber(customNumber) Return value
map - Product map with all product data. Parameters

Parameter	Type	Required	Description
`customNumber`	string	yes	User-defined number.

Example that loads a product by GTIN.

{{ var $myProduct = $wsProducts.loadByCustomNumber("4006381333931") }}
Name: {{= $myProduct.name }}

By using the $wsProducts.load..() functions, various variables are available to retrieve and output data about the product. Below is an overview of which variables are available.

Product data (return value of $wsProducts.load())

First, it is necessary to assign the map with the product 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": "...",
  "active": "...",
  "name": "...",
  "descr": "...",
  "itemNumber": "...",
  "price": "...",
  "rawPrice": "...",
  "promotionInfo": "...",
  "taxRateId": "...",
  "storeId": "...",
  "custom": { ... },
  "base": null,
  "variantSelection": { },
  "getFullPriceInfo": "ƒ()"
}

Variables overview

Variable	Type	Description
`id`	string	Unique product ID assigned by the shop.
`active`	string	Returns whether the product is active in the shop. Return values: - `always` - the product is always active. - `never` - the product is never active. - `test` - the product is active in test mode.
`name`	string	Name of the product.
`descr`	string	Description of the product.
`itemNumber`	string	Item number of the product.
`price`	float	The currently valid price of the product. If a promotional price is active, this is the promotional price. See Price of a product.
`rawPrice`	float	The standard price of the product, independent of active promotional prices. Intended for display as a strikethrough price.
`promotionInfo`	string	Text of the active promotional price. The field is only present if a promotional price is active and it carries a text.
`taxRateId`	string	Tax rate ID of the product.
`storeId`	string	Stock item number of the product.
`custom`	map	Contains all configured free product fields of the product.
`base`	map	Contains the data of the base product if it is a variant.
`variantSelection`	map	Contains the selected variant attributes, for example colour and size.
`getFullPriceInfo()`	ƒ()	Returns price, standard price and promotion text for any price field. See Read further price fields.

$wsProducts.variantInfo()

Returns the variant data for a product. Signature
$wsProducts.variantInfo(productId) Return value
map - Map with variant data. Parameters

Name	Type	Required	Description
`productId`	string	yes	ID of the product whose variants are to be loaded.

Example that loads the variant info of a product.

{{ var $myVariants = $wsProducts.variantInfo("100-12345") }}
Number of variants: {{= $myVariants.numVariants }}

By using the $wsProducts.variantInfo() function, various variables are available to retrieve and output data about the product. Below is an overview of which variables are available.

Variant data (return value of $wsProducts.variantInfo())

First, it is necessary to assign the map with the variant 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

{
  "numVariants": 5,
  "variantAttributes": [
    {
      "name": "Color",
      "options": [
        { "name": "Red" },
        { "name": "Blue" }
      ]
    }
  ],
  "resolve": "ƒ()"
}

Variables overview

Variable	Type	Description
`numVariants`	int	Number of variants.
`variantAttributes`	array	List of variant attributes.
`[$i].name`	string	Name of the attribute, for example “Colour”.
`[$i].options`	array	List of options.
`[$i].name`	string	Name of the option, for example “Red”.

$wsProducts.variantInfo().resolve()

resolve() is a method of the return value of $wsProducts.variantInfo(). It takes a possibly incomplete or invalid attribute selection and returns the closest matching existing variant. Why resolve() is needed
Variant products only exist in certain attribute combinations.
When a customer changes a single attribute, for example the colour, the previously selected overall combination may no longer be available.
In this case, resolve() finds the next possible valid variant without you having to search through all available combinations yourself.

Example
A T-shirt is available in these combinations:

Colour	Size
Red	S
Blue	S
Red	L

The customer currently sees “Red, L” and clicks on “Blue”. However, the combination “Blue, L” does not exist, so resolve() returns “Blue, S” instead, that is the only valid variant in which the colour Blue is preserved.
The fixate parameter controls which attribute is considered immutable. In this case it is the colour, since the user selected the colour. Signature
$variantInfo.resolve(selection, fixate) Parameters

Name	Type	Required	Description
`selection`	map	yes	The currently selected attribute values. The map contains attribute names as keys and selected option values as values, for example `{"Colour": "Blue", "Size": "L"}`. Not all attributes need to be set.
`fixate`	string	yes	Name of the attribute that the user just changed. This value is mandatorily preserved by `resolve()`. All other attributes are adjusted as needed to produce a valid combination.

Return value
map - A product object that corresponds to the resolved variant. Its structure is identical to the return value of $wsProducts.load(). In case of error, that is when no variant with the fixated attribute value exists, resolve() returns null.

Example
The user had selected “Red, size L” and clicks on “Blue”. Because “Blue, L” does not exist, resolve() returns the closest matching variant with the colour Blue.

{{ var $varInfo  = $wsProducts.variantInfo("100-12345") }}
{{ var $resolved = $varInfo.resolve({"Color": "Blue", "Size": "L"}, "Color") }}

{{ if $resolved }}
  <a href="/produkt/{{= $resolved.id }}">Select variant</a>
{{ /if }}

Actions

No actions are available for $wsProducts.

Examples

In the following examples, the product is assigned to a variable $myProduct. This means that all product information can be retrieved and further processed via this variable.

Name and description of the product

Name and description are standard product data fields that are predefined by the shop system. They belong to the essential fields used to record and display basic product information and are indispensable for order processing. The technical field names are firmly defined and are addressed in the following form:

$myProduct.<technical name>

The syntax for accessing the product name and the product description is:

<h1>{{= $myProduct.name }}</h1>
<p>{{= $myProduct.descr }}</p>

Weight as an additional product data field

In contrast to standard product data fields, weight is one of the additional product data fields. These offer extended possibilities for recording and displaying product features that go beyond the basic information. Additional product data fields are:

Not mandatorily required for order processing, but helpful for product presentation.
Individually customizable and can be added as required.
Created via the admin interface or supplied via the product data interface.

The technical names of these fields are addressed in the form:

$myProduct.custom.<technical name>

If a field weight was created in the admin area, the weight of a product can be output like this:

<p>Weight: {{= $myProduct.custom.weight }} kg</p>

Product images

The data fields for product images are not standard fields but additional product data fields. To output product images flexibly and in different sizes, these fields must be created as the MultiFormatImage data type. This field type enables storing an image in multiple formats and at the same time provides automatic conversion, so the images are available in the desired sizes. The number of additional product data fields with this type is not limited, so any number of images can be stored for a product. The configuration of the image sizes is done in the admin interface in the image converter service. There you can define the desired formats needed for various areas of use. Typically, four image sizes are used:

mini (thumbnail)
small
normal and
large

In the admin interface image converter service, you also define the storage directory for the images on the server. The path to the image is then output directly via the corresponding variable. Product images are accessed according to the following scheme

$myProduct.custom.<technical field name>.<defined format>

If, for example, the field image01 was created for the main image of the product, the images can be output in the various sizes as follows:

<img src="{{= $myProduct.custom.image01.mini}}" alt="{{= $myProduct.name }}">
<img src="{{= $myProduct.custom.image01.small}}" alt="{{= $myProduct.name }}">
<img src="{{= $myProduct.custom.image01.normal}}" alt="{{= $myProduct.name }}">
<img src="{{= $myProduct.custom.image01.large}}" alt="{{= $myProduct.name }}">

Variants of a product

Products that are available in different versions such as size, colour, or material are created as variant products. Variants are not standalone items, but subordinate versions of a main product that differ in certain features. So that variants can be correctly managed and displayed in the shop, special product data fields are used, which are referred to as type-specific product data fields. These fields are specifically designed to support the requirements of variant products, set products, and other complex product structures. They are deeply anchored in the shop software, firmly predefined, and cannot be changed technically. This means that both the designation and the specifications of these fields cannot be adjusted. This concerns, for example, allowed values, field types, and inheritance mechanisms. The actual product information of a variant, such as name, description, price, or images, is maintained via the standard and additional product data fields defined for the variants. This data can either be set individually per variant. If no specific values are stored, they are automatically inherited from the main product. The following syntax is used to access variants of a product:

{{ var $myProductVariant = $wsProducts.variantInfo($myProduct.id) }}
{{ foreach $myVariant in $myProductVariant.variantAttributes }}
   <p>Variant name: {{= $myVariant.name }}</p>
{{ /foreach }}

Price of a product

Every product has a sales price displayed in the shop. In addition, a product can carry time-controlled promotional prices that only apply within a maintained period. This section first describes the two fields for the regular price and the promotional price, then the display as a strikethrough price, then the prices of set products, and finally access to further price fields.

Current price and standard price

The shop resolves the price anew on every page load. You therefore do not have to check yourself whether a promotion is running. Three fields are available for this.

Variable	Type	Description
`price`	float	The currently valid sales price. If a promotional price is active, this is the promotional price, otherwise the standard price.
`rawPrice`	float	The standard price, independent of active promotional prices.
`promotionInfo`	string	The text of the active promotional price, for example “Sommeraktion”. The field is only present if a promotional price is active and it carries a text.

So that the prices are output with the correct currency, the currency formatting is automatically taken from the shop settings in the admin interface. This means that the currency is displayed either as an ISO code (EUR) or as a symbol (€), depending on the configuration of the shop. Whether the prices in the shop are treated net (excl. VAT) or gross (incl. VAT) is also a setting that can be configured in the admin interface.

Display strikethrough price and promotion notice

A strikethrough price only makes sense if the standard price is actually above the current price. Therefore, check this before output.

{{ if $myProduct.rawPrice > $myProduct.price }}
   <span class="text-decoration-line-through">{{= $myProduct.rawPrice | currency }}</span>
{{ /if }}
<span class="fw-bold">{{= $myProduct.price | currency }}</span>

{{ if $myProduct.promotionInfo }}
   <span class="badge bg-danger">{{= $myProduct.promotionInfo }}</span>
{{ /if }}

Promotional prices are maintained per price field in the Admin Interface with a from-to period. Via the interface, this is done with the scheduledPrices field, described in the API reference products.

Prices of set products

For set products, the price is calculated from the main product and the sub-products, anew on every page load. The fields price and rawPrice contain the values of the set. In addition, the following fields are available.

Variable	Type	Description
`setPrice`	float	Price of the set, that is the value that is also in `price`.
`setRawPrice`	float	Price of the set without promotional prices, that is the value that is also in `rawPrice`.
`setOrgPrice`	float	Reference price of the set from the price of the main product and the prices of all sub-products. Serves as strikethrough price.
`setDiscount`	float	Savings in percent, that is “You save X %”.
`setDiscountPrice`	float	Savings as an amount, that is “You save X euros”.

The syntax for access is:

{{ if $myProduct.isSetProduct }}
   <p>Price: {{= $myProduct.setPrice | currency }}</p>
   <p>Original price: {{= $myProduct.setOrgPrice | currency }}</p>
   <p>Discount in percent: {{= $myProduct.setDiscount }} %</p>
   <p>Discount in numbers: {{= $myProduct.setDiscountPrice | currency }}</p>
{{ /if }}

The five set fields are only available for set products. They are not present for all other products. Whether a product is a set is indicated by the isSetProduct field, which is present on every product.

Price in the basket

The price of a basket line item is fixed when it is added. Affected are $wsBasket.items[].price and the derived values total, totalNet, totalGross and totalTax. If a promotion ends while the item is in the basket, the line item retains the price at the time of adding. The same applies to the sub-products of a set and to automatically added line items. The product object inside a basket line item, that is $wsBasket.items[].product, resolves its price anew on every call. Both values can therefore diverge.

Changes to existing templates

The following changes can affect existing templates. Check your price outputs before updating.

Field	Change
`discountPrice`	Removed from the product and variant object. The identically named key on a basket line item, that is `$wsBasket.items[].discountPrice`, remains unchanged.
`totalPrice`	Removed from the product and variant object.
`setPrice`, `setOrgPrice`, `setDiscount`, `setDiscountPrice`	Previously present on every product, on normal items with the value 0.00. Now only present on set products. Outputs without a check for `isSetProduct` remain empty on normal items.
`setOrgPrice`	Now additionally contains the price of the main product. Previously the value only summed the sub-products. Strikethrough prices based on this field therefore become higher.
`setDiscount`, `setDiscountPrice`	Now also deliver values other than 0 where previously 0.00 was mandatory.
`price`	Now contains the resolved price; for set products the total sum of the set. This applies to all fields of type Price, including additional fields under `custom.`.

Read further price fields

In addition to the standard price, a shop can maintain further price fields as additional product data fields. These fields can also carry promotional prices, and the direct access via $myProduct.custom.<field> already returns the resolved price. You only need getFullPriceInfo() when you additionally need the standard price or the promotion text of such a field. Signature
$myProduct.getFullPriceInfo(field) Return value
map - Map with the fields price, rawPrice and promotionInfo. For an unknown field, null is returned. Parameters

Name	Type	Required	Description
`field`	string	yes	Technical name of the price field. Standard product data fields are addressed directly, for example `price`. Additional product data fields carry the prefix `custom.`, for example `custom.listPrice`.

Example that outputs an additional price field with strikethrough price.

{{ var $cPriceInfo = $myProduct.getFullPriceInfo("custom.listPrice") }}

{{ if $cPriceInfo }}
   {{ if $cPriceInfo.rawPrice > $cPriceInfo.price }}
      <span class="text-decoration-line-through">{{= $cPriceInfo.rawPrice | currency }}</span>
   {{ /if }}
   <span>{{= $cPriceInfo.price | currency }}</span>
{{ /if }}

Where these fields are available

The price fields belong to the product object itself. They are therefore available everywhere a product object is delivered, and not only for $wsProducts.load(). Via module methods:

$wsProducts.load(), $wsProducts.loadByNumber(), $wsProducts.loadByCustomNumber() and $wsProducts.loadNext()
$wsProducts.variantInfo(id).resolve(selection, fixate)
$wsProduct.load() and $wsProduct.variantInfo(id).resolve(selection, fixate)
$wsCategories.loadProducts(categoryId)
$wsSearch.search(params, id).products
$wsWatchList.loadWatchList(watchListId).items[].product
$wsLastSeenProducts.load()

Via page variables and nested objects:

$wsViews.current.info.product and $wsViews.current.info.products[]
$wsViews.current.info.basketItem.product and $wsViews.current.info.product
$wsBasket.items[].product
$wsNavigation.path[].object, when type has the value product
$product.base, that is the base product of a variant

Availability of a product

In addition to all other product information, the availability of a product is one of the most important pieces of information for the buyer. Each product can be given a stock level that determines whether and in what quantity an item can be ordered. Additionally, the current stock and the corresponding delivery status can be displayed in the shop. Access to the stock is not made directly via $wsProducts, but via the separate module $wsInventory.

{{ var $myProductInventoryInfo = $wsInventory.load($myProduct.id) }}
{{ if $myProductInventoryInfo.active }}
      Current quantity: {{= $myProductInventoryInfo.amount }}
{{ /if }}

You can find detailed information about data access of the stock module here. You can find more practical examples for implementing products and product variants here: → Practical examples: products

Frontend

The basics

Getting started

Feature overview

Examples

Reference – Actions

Reference – Language

Reference – Modules

$wsProducts - Product data

Module overview

Templates

Variables

Methods

$wsProducts.load()

$wsProducts.loadByNumber()

$wsProducts.loadByCustomNumber()

Product data (return value of $wsProducts.load())

$wsProducts.variantInfo()

Variant data (return value of $wsProducts.variantInfo())

$wsProducts.variantInfo().resolve()

Actions

Examples

Name and description of the product

Weight as an additional product data field

Product images

Variants of a product

Price of a product

Current price and standard price

Display strikethrough price and promotion notice

Prices of set products

Price in the basket

Changes to existing templates

Read further price fields

Where these fields are available

Availability of a product

​Module overview

​Templates

​Variables

​Methods

​$wsProducts.load()

​$wsProducts.loadByNumber()

​$wsProducts.loadByCustomNumber()

​Product data (return value of $wsProducts.load())

​$wsProducts.variantInfo()

​Variant data (return value of $wsProducts.variantInfo())

​$wsProducts.variantInfo().resolve()

​Actions

​Examples

​Name and description of the product

​Weight as an additional product data field

​Product images

​Variants of a product

​Price of a product

​Current price and standard price

​Display strikethrough price and promotion notice

​Prices of set products

​Price in the basket

​Changes to existing templates

​Read further price fields

​Where these fields are available

​Availability of a product

​Related links

Module overview

Templates

Variables

Methods

$wsProducts.load()

$wsProducts.loadByNumber()

$wsProducts.loadByCustomNumber()

Product data (return value of $wsProducts.load())

$wsProducts.variantInfo()

Variant data (return value of $wsProducts.variantInfo())

$wsProducts.variantInfo().resolve()

Actions

Examples

Name and description of the product

Weight as an additional product data field

Product images

Variants of a product

Price of a product

Current price and standard price

Display strikethrough price and promotion notice

Prices of set products

Price in the basket

Changes to existing templates

Read further price fields

Where these fields are available

Availability of a product

Related links