Merkliste

Die Integration der Merkliste bietet eine umfassende Möglichkeit, Produkte in einer zentralen Liste zu verwalten und benutzerfreundlich zu präsentieren. Dabei steht eine Vielzahl von Funktionen zur Verfügung, die flexibel konfiguriert werden können, um spezifischen Anforderungen gerecht zu werden. Von der initialen Konfiguration über das Hinzufügen und Verwalten von Produkten bis hin zur Anzeige der Liste in unterschiedlichen Kontexten decken die bereitgestellten Integrationen alle wesentlichen Anwendungsfälle ab.

Die Voraussetzung für die Verwendung der Merkliste ist das Upgrade „Zugriff auf Artikeldaten, Videos und Exposés“ für Ihren OXOMI-Account (ab dem Paket „enterprise“ bereits enthalten).

Die Implementierung erfolgt über eine einfache JavaScript-API, welche sowohl für Entwickler leicht zugänglich als auch in bestehende Systeme nahtlos integrierbar ist. Die Nutzung von Promises zur Fehler- und Erfolgshandhabung sowie die Bereitstellung von Events ermöglichen eine reaktive und dynamische Benutzererfahrung. Die nachfolgende ausführliche Beschreibung der JavaScript-Integration setzt die im Artikel JavaScript Integrationsgrundlagen beschriebenen Grundlagen voraus. Der Artikel geht dabei insbesondere auf die Parameter (sowie deren Wertebereiche) der vorhandenen Integrationsmöglichkeiten ein und veranschaulicht diese jeweils in einem interaktiven Showcase.

Mit der Integration oxomi.configureWatchlist kann die Merkliste konfiguriert werden. Diese Konfiguration ist global gültig und sollte nach dem Aufruf von oxomi.init erfolgen. Der folgende Pseudo-Code stellt diesen Zusammenhang dar:

oxomi.init({
    // Initialisierung von OXOMI
    ...
});
document.addEventListener('oxomi-configured', function oxomi_ready() {
    oxomi.configureWatchlist({
        ...
    });
});

Die nachfolgende Tabelle enthält eine Übersicht über die verfügbaren Parameter. Fett gedruckte Parameter sind Pflichtparameter. Die Beschreibung der Parameter enthält Informationen über den Typ des Parameters, die möglichen Werte und die Bedeutung sowie weitere Verwendungshinweise.

Parameter	Parametertyp	Beschreibung
name	String	Gibt den Namen der Merkliste an. Hinweis: Wird der Parameter nicht angegeben, so wird Merkliste als Default-Wert verwendet.
appendixHtml	String	Gibt zusätzlichen HTML-Inhalt an, welcher am unteren Ende der Merkliste angezeigt werden soll. Hinweis: Das HTML ist immer sichtbar. Das HTML wird unterhalb des Gesamtpreises angezeigt.
emailReceiverCode	String	Gibt den E-Mail-Code des Empfängers der Produkt-Anfrage an. Hinweis: Wird der Parameter nicht angegeben, so wird die in den Portaleinstellungen eingetragene E-Mail-Adresse als Default-Wert verwendet. Bei diesem Parameter handelt es sich um einen Code, welcher innerhalb der Portaleinstellungen einer E-Mail-Adresse zugeordnet wurde. Die Angabe des Empfängers via Code muss mit dem OX-Support eingerichtet werden.
addProductsAsSeparatePositions	boolean	Gibt an, ob jedes zur Merkliste hinzugefügte Produkt als eigenständige Position geführt werden soll. Hinweis: Wird der Parameter nicht angegeben, so wird true als Default-Wert verwendet. Wird dieser Parameter auf true gesetzt, so wird jedes zur Merkliste hinzugefügte Produkt als eigenständige Position geführt. Wird dieser Parameter auf false gesetzt, so kann jedes Produkt nur einmal als Position aufgeführt werden. Ein erneutes Hinzufügen zur Merkliste führt zu einer Addition der angegebenen Menge.

Die Integration oxomi.openWatchlist kann verwendet werden, um die Merkliste zu öffnen. Die Merkliste stellt die hinzugefügten Produkte in einer Listenansicht inklusive optionalem Gesamtpreis dar. Damit die Produktinformationen vollständig angezeigt werden können, muss die buzz-Capability fetchProductData bereitgestellt werden. Andernfalls kann nur die Artikelnummer angezeigt werden. Damit die Merkliste auch den Gesamtpreis aller Positionen anzeigt, kann die buzz-Capability calculateTotalPrice bereitgestellt werden.

Optional stellt die Merkliste weiterhin einen Button für eine E-Mail-Anfrage bereit, mit welcher die in der Liste enthaltenen Produkte angefragt werden können. Die E-Mail-Produktanfrage muss hierfür vorher in den Portaleinstellungen aktiviert worden sein.

Bei der Nutzung der Merkliste werden verschiedene Events ausgelöst, um Benutzereingaben und Aktionen zu verarbeiten. Die folgende Tabelle gibt eine Übersicht der Events und deren Auslösebedingungen:

Event-Name	Auslösebedingung
oxomi-watchlist-product-added	Wird ausgelöst, wenn ein Produkt zur Merkliste hinzugefügt wird.
oxomi-watchlist-product-removed	Wird ausgelöst, wenn ein Produkt aus der Merkliste entfernt wird, entweder durch Klick auf den Entfernen-Button oder wenn die Menge auf 0 gesetzt wird.
oxomi-watchlist-cleared	Wird ausgelöst, wenn die gesamte Merkliste geleert wird.

Die Integration verfügt über keine Parameter.

Die Integration oxomi.addProductToWatchlist kann verwendet werden, um ein Produkt der Merkliste hinzuzufügen. Ob ein Produkt als eigenständige Position hinzugefügt wird oder mit einer bestehenden Position zusammengeführt wird, hängt von der Konfiguration des Parameters addProductsAsSeparatePositions ab in der oben beschriebenen configureWatchlist Integration. Die Merkliste kann maximal 256 individuelle Positionen enthalten.

Der Aufruf der Integration liefert ein Promise zurück, welches Ihnen die Möglichkeit gibt, entsprechend auf den Abschluss des Aufrufs zu reagieren. Hierfür können Sie die then und catch Methoden des Promise Objekts verwenden. Der nachfolgende JavaScript-Code zeigt ein Beispiel, wie Sie auf den Abschluss des Aufrufs reagieren können.

oxomi.addProductToWatchlist({
    itemNumber: 'ST.001.A',
    supplierNumber: 'ST',
    quantity: 1
}).then((result) => {
    console.log('successfully added ' + result.product);
}).catch((result) => {
    console.log('failed to add: ' + result.product);
    console.log('fail reason: ' + result.error.message);
});

Wie im Beispiel ersichtlich wird im Fehlerfall eine internationalisierte Fehlermeldung zusammen mit den Eingabeparametern übergeben. Im Erfolgsfall werden nur die Eingabeparameter übergeben. Weiterhin wird im Erfolgsfall ein Event wie bereits oben beschrieben ausgelöst.

Die nachfolgende Tabelle enthält eine Übersicht über die verfügbaren Parameter. Fett gedruckte Parameter sind Pflichtparameter. Die Beschreibung der Parameter enthält Informationen über den Typ des Parameters, die möglichen Werte und die Bedeutung sowie weitere Verwendungshinweise.

Parameter	Parametertyp	Beschreibung
itemNumber	String	Gibt die Artikelnummer des Produktes an.
supplierNumber	String	Gibt die Lieferantennummer des Produktes an.
quantity	Number	Gibt die Bestellmenge, mit welcher das Produkt in die Merkliste aufgenommen werden soll, an.

Die Integration oxomi.embedWatchlistInfoTile ermöglicht das Einbetten einer Informationskachel für die Merkliste. Die Informationskachel zeigt den Namen der Merkliste neben einem Warenkorb-Icon an. Zusätzlich wird die Anzahl der sich in der Merkliste derzeit befindlichen Produktpositionen über dem Warenkorb dargestellt.

Wird die buzz-Capability calculateTotalPrice bereitgestellt, so wird der Gesamtpreis der sich in der Merkliste befindenden Produkte unterhalb des Namens in der Informationskachel angezeigt. Mit einem Klick auf die Informationskachel wird die Merkliste geöffnet.

Die Integration verfügt über keine Parameter.

Interaktives Code-Beispiel

Mithilfe der Integration oxomi.fetchWatchlistProductsCount kann die Anzahl der sich aktuell in der Merkliste befindlichen Produktpositionen abgefragt werden.

Der Aufruf der Integration liefert ein Promise zurück, welches Ihnen die Möglichkeit gibt, entsprechend auf den Abschluss des Aufrufs zu reagieren. Hierfür können Sie die then und catch Methoden des Promise Objekts verwenden. Der nachfolgende JavaScript-Code zeigt ein Beispiel, wie Sie auf den Abschluss des Aufrufs reagieren können.

oxomi.fetchWatchlistProductsCount().then((result) => {
    console.log('number of positions: ' + result);
}).catch((error) => {
    console.log('error: ' + error);
});