Das Modul $wsProducts ermöglicht den Zugriff auf Produktdaten innerhalb des Shops. Damit können sowohl Einzelprodukte als auch Produktlisten ausgelesen und im Frontend dargestellt werden.

Mit $wsProducts lassen sich Produktdetails eines einzelnen Artikels abrufen, wenn man nicht auf der Produktdetailansicht oder Kategorieansichten ist - also alle Seiten, auf denen die Daten nicht bereits durch die ViewController vorgeladen werden.

Inhaltsverzeichnis

Modulübersicht

Beispiel / Ausschnitt über $wsProducts

{{= $wsProducts | json }}

JSON-Ausgabe

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

Anmerkung: ƒ() kennzeichnet eine Funktion.

Methoden in der Übersicht

Methode	Rückgabe-Typ	Beschreibung

Methode	Rückgabe-Typ	Beschreibung
`load()`	map	Gibt ein Produkt anhand der Produkt-ID zurück.
`loadByNumber()`	map	Gibt ein Produkt anhand der Artikelnummer zurück.
`loadByCustomNumber()`	map	Gibt ein Produkt anhand einer benutzerdefinierten Nummer zurück.
`variantInfo()`	map	Liefert die Varianten-Daten zu einem Produkt zurück.

Templates

Standardmäßig werden Produkte über das Template product.htm angezeigt. Dieses befindet sich im Verzeichnis views. Der Name product.htm und der Speicherort dürfen nicht geändert werden, da das Template fest in der Software hinterlegt ist und nicht konfigurierbar oder anpassbar ist.

Produktdaten können jedoch flexibel auch auf anderen Seiten eingebunden werden, zum Beispiel:

Startseite → Darstellung von Top-Sellern, Angeboten oder einer Produktauswahl.
Warenkorbseite → Cross-Selling-Produkte als Kaufempfehlungen.
Kategorieseiten & Suchergebnisse → Individuelle Produktlisten mit Filtern.
Checkout & Bestellbestätigung → Anzeige von ergänzenden Produkten oder Rabattaktionen.

Mit $wsProducts lassen sich Produktinformationen dynamisch abrufen und individuell in verschiedenen Templates integrieren, um eine gezielte Präsentation von Artikeln zu ermöglichen.

Variablen

Für $wsProducts stehen keine Variablen zur Verfügung.

Methoden

$wsProducts.load()

Gibt ein Produkt anhand der Produkt-ID zurück.

Signatur
$wsProducts.load(productId)

Rückgabe
map - Product-Map mit allen Produktdaten.

Parameter

Name	Typ	Pflicht	Beschreibung

Name	Typ	Pflicht	Beschreibung
`productId`	string	ja	ID des Produkts.

Beispiel, das ein Produkt lädt und den Namen des Produkts ausgibt.

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

$wsProducts.loadByNumber()

Gibt ein Produkt anhand der Artikelnummer zurück.

Signatur
$wsProducts.loadByNumber(itemNumber)

Rückgabe
map - Product-Map mit allen Produktdaten.

Parameter

Parameter	Typ	Pflicht	Beschreibung

Parameter	Typ	Pflicht	Beschreibung
`itemNumber`	string	ja	Artikelnummer des Produkts.

Beispiel, das ein Produkt anhand der Artikelnummer lädt:

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

$wsProducts.loadByCustomNumber()

Gibt ein Produkt anhand einer benutzerdefinierten Nummer zurück (z.B. EAN, GTIN).

Signatur
$wsProducts.loadByCustomNumber(customNumber)

Rückgabe
map - Product-Map mit allen Produktdaten.

Parameter

Parameter	Typ	Pflicht	Beschreibung

Parameter	Typ	Pflicht	Beschreibung
`customNumber`	string	ja	Benutzerdefinierte Nummer.

Beispiel, das ein Produkt anhand der GTIN lädt.

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

Mit Verwendung der Funktionen $wsProducts.load..() stehen verschiedene Variablen zur Verfügung, um Daten zum Produkt abzurufen und auszugeben. Nachfolgend eine Übersicht, welche Variablen verfügbar sind.

Produkt-Daten (Rückgabe von $wsProducts.load() )

Zunächst ist es notwendig, die Map mit den Produkt-Daten, wie im obigen Beispiel dargestellt, einer lokalen Variable zuzuweisen. Diese kann anschließend an verschiedenen Stellen im Template verwendet werden.

JSON-Ausgabe der Variablen

{
  "id": "...",
  "active": "...",
  "name": "...",
  "descr": "...",
  "itemNumber": "...",
  "price": "...",
  "taxRateId": "...",
  "storeId": "...",
  "custom": { ... },
  "base": null,
  "variantSelection": { }
}

Variablen in der Übersicht

Variable	Typ	Beschreibung

Variable	Typ	Beschreibung
`id`	string	Eindeutige vom Shop vergebene Produkt-ID.
`active`	string	Gibt zurück, ob das Produkt im Shop aktiv ist. Rückgabewerte: “always” - das Produkt ist immer aktiv. “never” - das Produkt ist nie aktiv. “test” - das Produkt ist im Testmodus aktiv.
`name`	string	Name des Produkts.
`descr`	string	Beschreibung des Produkts.
`itemNumber`	string	Artikelnummer des Produkts.
`price`	float	Preis des Produkts.
`taxRateId`	string	Steuersatz-ID des Produkts.
`storeId`	string	Lagerartikelnummer des Produkts.
`custom`	map	Enthält alle konfigurierten, freien Produktfelder des Produkts.
`base`	map	Enthält die Daten des Basisprodukts, wenn es sich um eine Variante handelt.
`variantSelection`	map	Enthält die gewählten Variantenattribute (z.B. Farbe, Größe).

$wsProducts.variantInfo()

Liefert die Varianten-Daten zu einem Produkt zurück.

Signatur
$wsProducts.variantInfo(productId)

Rückgabe
map - Map mit Varianten-Daten.

Parameter

Name	Typ	Pflicht	Beschreibung

Name	Typ	Pflicht	Beschreibung
`productId`	string	ja	ID des Produkts, dessen Varianten geladen werden sollen.

Beispiel, das die Varianten-Infos eines Produkts lädt.

{{ var $myVariants = $wsProducts.variantInfo("100-12345") }}
Anzahl Varianten: {{= $myVariants.numVariants }}

Mit Verwendung der Funktion $wsProducts.variantInfo() stehen verschiedene Variablen zur Verfügung, um Daten zum Produkt abzurufen und auszugeben. Nachfolgend eine Übersicht, welche Variablen verfügbar sind.

Varianten-Daten (Rückgabe von $wsProducts.variantInfo() )

Zunächst ist es notwendig, die Map mit den Varianten-Daten, wie im obigen Beispiel dargestellt, einer lokalen Variable zuzuweisen. Diese kann anschließend an verschiedenen Stellen im Template verwendet werden.

JSON-Ausgabe der Variablen

{
  "numVariants": 5,
  "variantAttributes": [
    {
      "name": "Farbe",
      "options": [
        { "name": "Rot" },
        { "name": "Blau" }
      ]
    }
  ]
}

Variablen in der Übersicht

Variable	Typ	Beschreibung

Variable	Typ	Beschreibung
`numVariants`	int	Anzahl der Varianten.
`variantAttributes`	array	Liste der Varianten-Attribute.
`[$i].name`	string	Name des Attributs (z.B. "Farbe").
`[$i].options`	array	Liste der Optionen.
`[$i].name`	string	Name der Option (z.B. "Rot").

Aktionen

Für $wsProducts stehen keine Aktionen zur Verfügung.

Beispiele

In den folgenden Beispielen wird das Produkt einer Variable $myProduct zugewiesen. Das bedeutet, dass alle Produktinformationen über diese Variable abgerufen und weiterverarbeitet werden können.

Name und Beschreibung des Produkts

Name und Beschreibung sind Standard-Produktdatenfelder, die vom Shopsystem vorgegeben sind. Sie gehören zu den essenziellen Feldern, die zur Erfassung und Darstellung grundlegender Produktinformationen dienen und für die Bestellabwicklung unerlässlich sind.

Die technischen Feldnamen sind fest definiert und werden in der folgenden Form angesprochen:

$myProduct.<technischer Name>

Die Syntax für den Zugriff auf den Produktnamen und die Produktbeschreibung lautet:

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

Gewicht als Zusatz-Produktdatenfeld

Im Gegensatz zu Standard-Produktdatenfeldern gehört das Gewicht zu den Zusatz-Produktdatenfeldern. Diese bieten erweiterte Möglichkeiten zur Erfassung und Darstellung von Produktmerkmalen, die über die grundlegenden Informationen hinausgehen.

Zusatz-Produktdatenfelder sind:

Nicht zwingend für die Bestellabwicklung erforderlich, aber hilfreich für die Produktdarstellung.
Individuell anpassbar und können je nach Bedarf hinzugefügt werden.
Über das Admin Interface erstellt oder über die Produktdaten-Schnittstelle geliefert werden.

Die technischen Namen dieser Felder werden in der Form angesprochen:

$myProduct.custom.<technischer Name>

Falls ein Feld weight im Admin-Bereich erstellt wurde, kann das Gewicht eines Produkts so ausgegeben werden:

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

Produktbilder

Die Datenfelder für Produktbilder gehören nicht zu den Standardfeldern, sondern sind Zusatz-Produktdatenfelder. Um Produktbilder flexibel und in unterschiedlichen Größen auszugeben, müssen diese Felder als Datentyp MultiFormatImage angelegt werden. Dieser Feldtyp ermöglicht die Speicherung eines Bildes in mehreren Formaten und sorgt gleichzeitig für eine automatische Konvertierung, sodass die Bilder in den gewünschten Größen verfügbar sind. Die Anzahl der Zusatz-Produktdatenfelder mit diesem Typ ist nicht begrenzt, sodass beliebig viele Bilder für ein Produkt gespeichert werden können.

Die Konfiguration der Bildgrößen erfolgt im Admin Interface im Service Bildkonverter. Dort können die gewünschten Formate festgelegt werden, die für verschiedene Anwendungsbereiche benötigt werden. Typischerweise werden vier Bildgrößen verwendet:

mini (Thumbnail)
klein
normal und
groß

Im Admin Interface Service Bildkonverter wird auch das Speicherverzeichnis für die Bilder auf dem Server definiert. Der Pfad zum Bild wird dann durch die entsprechende Variable direkt mit ausgegeben.

Der Zugriff auf Produktbilder erfolgt nach dem folgenden Schema

$myProduct.custom.<technischer Feldname>.<Definiertes Format>

Wurde beispielsweise das Feld image01 für das Hauptbild des Produkts angelegt, können die Bilder in den verschiedenen Größen folgendermaßen ausgegeben werden:

<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 }}">

Varianten eines Produktes

Produkte, die in unterschiedlichen Ausführungen wie Größe, Farbe oder Material erhältlich sind, werden als Variantenprodukte angelegt. Varianten sind keine eigenständigen Artikel, sondern untergeordnete Versionen eines Hauptprodukts, die sich in bestimmten Merkmalen unterscheiden. Damit Varianten korrekt im Shop verwaltet und dargestellt werden können, werden spezielle Produktdatenfelder verwendet, die als typspezifische Produktdatenfelder bezeichnet werden.

Diese Felder sind speziell darauf ausgerichtet, die Anforderungen von Variantenprodukten, Setprodukten und anderen komplexen Produktstrukturen zu unterstützen. Sie sind tief in der Shop-Software verankert, fest vorgegeben und können technisch nicht geändert werden. Das bedeutet, dass sowohl die Bezeichnung als auch die Spezifikationen dieser Felder – wie erlaubte Werte, Feldtypen oder Vererbungsmechanismen – nicht angepasst werden können.

Die eigentlichen Produktinformationen einer Variante, wie Name, Beschreibung, Preis oder Bilder, werden über die Standard- und Zusatz-Produktdatenfelder gepflegt, die für die Varianten definiert wurden. Diese Daten können entweder individuell pro Variante festgelegt oder – falls keine spezifischen Werte hinterlegt sind – automatisch vom Hauptprodukt geerbt werden.

Für den Zugriff auf Varianten eines Produkts wird die folgende Syntax verwendet:

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

Preis eines Produkts

Jedes Produkt hat einen Verkaufspreis, der im Shop angezeigt wird. Neben dem regulären Preis können auch weitere Preise und Rabatte berücksichtigt werden, die entweder als fester Betrag oder als prozentualer Nachlass dargestellt werden.

Für die Preisberechnung stehen beispielsweise folgende Datenfelder zur Verfügung:

price → Der aktuelle Verkaufspreis des Produkts.
setDiscount → Der Rabatt in Prozent, also "Sie sparen X %".
setDiscountPrice → Der reduzierte Preis nach Abzug des Rabatts, also "Sie sparen X Euro".
setOrgPrice → Der ursprüngliche Preis vor dem Rabatt, also der Streichpreis.

Damit die Preise mit der richtigen Währung ausgegeben werden, wird die Währungsformatierung automatisch aus den Shopeinstellungen im Admin Interface übernommen. Das bedeutet, dass die Währung entweder als ISO-Code (EUR) oder als Symbol (€) angezeigt wird, je nach Konfiguration des Shops.

Ob die Preise im Shop netto (zzgl. MwSt.) oder brutto (inkl. MwSt.) behandelt werden, ist ebenfalls eine Einstellung, die im Admin Interface konfiguriert werden kann.

Die Syntax für den Zugriff auf die Preise und Rabatte lautet:

<p>Preis: {{= $myProduct.price | currency }}</p>
<p>Rabatt in Prozent: {{= $myProduct.setDiscount }} %</p>
<p>Rabatt in Zahlen: {{= $myProduct.setDiscountPrice | currency }}</p>
<p>Originalpreis: {{= $myProduct.setOrgPrice | currency }}</p>

Verfügbarkeit eines Produkts

Neben allen anderen Produktinformationen ist die Verfügbarkeit eines Produkts eine der wichtigsten Informationen für den Käufer. Jedes Produkt kann mit einem Lagerbestand versehen werden, der darüber entscheidet, ob und in welcher Menge ein Artikel bestellt werden kann. Zusätzlich besteht die Möglichkeit, den aktuellen Lagerbestand und den zugehörigen Lieferstatus im Shop anzuzeigen.

Der Zugriff auf den Lagerbestand erfolgt nicht direkt über $wsProducts, sondern über das separate Modul $wsInventory .

{{ var $myProductInventoryInfo = $wsInventory.load($myProduct.id) }}
{{ if $myProductInventoryInfo.active }}
      Aktuelle Stückzahl: {{= $myProductInventoryInfo.amount }}
{{ /if }}

Detaillierte Informationen für den Datenzugriff des Lagerbestands-Moduls finden Sie hier.

Zugriff auf ein bestimmtes Produkt über $wsProducts

Wenn ein bestimmtes Produkt anhand seiner ProduktID geladen werden soll, kann dies mit load() erfolgen.

In diesem Beispiel wird das Produkt mit der ProduktID 100-25229 geladen:

{{ var $myProduct = $wsProducts.load("100-25229") }}
<!--
 {{ print $myProduct }}
-->

Die Ausgabe in der Developer-Konsole des Browsers könnte dann wie folgt aussehen:

{
  "variantSelection": {},
  "base": null,
  "taxRateId": "19",
  "descr": "Hochwertige Laufschuhe mit atmungsaktivem Mesh-Obermaterial und dämpfender Sohle.",
  "name": "Laufschuhe Pro Runner",
  "itemNumber": "RUN-001",
  "custom": {
    "weight": 0.8,
    "voucherProductTemplate": "",
    "voucherProductPrice": false,
    "voucherProductHtmlTemplate": "",
    "voucherProductActive": false,
    "validForDiscount": true,
    "productType": "standard",
    "brand": "SportActive",
    "robotsNoIndex": false,
    "metaDescriptionSetManually": false,
    "commission": 0.0,
    "filterField": "",
    "mainCategory": "Sportschuhe",
    "robotsNoFollow": false,
    "image": {
      "normal": "https://content.beispielshop.de/products/normal/laufschuhe_pro.png",
      "thumbnail": "https://content.beispielshop.de/products/thumbnail/laufschuhe_pro_thumbnail.png"
    },
    "commissionTaxRate": "",
    "metaDescription": "Hochwertige Laufschuhe mit ergonomischer Passform und atmungsaktivem Material.",
    "metaTitle": "Laufschuhe Pro Runner – Ideal für Training & Wettkampf",
    "oneTimeFeeTaxRate": "",
    "metaTitleSetManually": true,
    "multiProducts": "",
    "oneTimeFee": 0.0
  },
  "price": 89.99,
  "id": "100-25229",
  "active": "always"
}

Zugriff auf das aktuell gewählte Produkt über $wsViews

Auf einer Produktdetailseite muss keine Produktnummer angegeben werden. Das aktuell angezeigte Produkt kann über $wsViews.current.info.product abgerufen werden.

{{ var $myProduct = $wsViews.current.info.product }}
<!--
 {{ print $myProduct }}
-->

Die Ausgabe in der Developer-Konsole entspricht dem Beispiel “Zugriff auf ein bestimmtes Produkt über die Produktnummer”.

Zugriff auf alle Produkte einer Kategorie über $wsCategories

Hier werden alle Produkte der Kategorie mit der ID 5678 geladen und als Liste ausgegeben.

{{ foreach $myProduct in $wsCategories.loadProducts("5678") }}
    {{ print $myProduct }}
{{ /foreach }}

Zugriff auf Produkte der aktuell gewählten Kategorie über $wsViews

Hier wird automatisch die Kategorie verwendet, die der Nutzer gerade betrachtet, sodass keine Kategorie-ID angegeben werden muss.

{{ foreach $myProduct in $wsViews.current.info.category.loadProducts() }}
    {{ print $myProduct }}
{{ /foreach }}

Weitere Praxisbeispiele zur Umsetzung von Produkten und Produktvarianten finden Sie hier:

→ Praxisbeispiele Produkte

$wsProducts

Inhaltsverzeichnis

Modulübersicht

Templates

Variablen

Methoden

$wsProducts.load()

$wsProducts.loadByNumber()

$wsProducts.loadByCustomNumber()

Produkt-Daten (Rückgabe von $wsProducts.load() )

$wsProducts.variantInfo()

Varianten-Daten (Rückgabe von $wsProducts.variantInfo() )

Aktionen

Beispiele

Name und Beschreibung des Produkts

Gewicht als Zusatz-Produktdatenfeld

Produktbilder

Varianten eines Produktes

Preis eines Produkts

Verfügbarkeit eines Produkts

Zugriff auf ein bestimmtes Produkt über $wsProducts

Zugriff auf das aktuell gewählte Produkt über $wsViews

Zugriff auf alle Produkte einer Kategorie über $wsCategories

Zugriff auf Produkte der aktuell gewählten Kategorie über $wsViews

Weiterführende Links