Dieser Artikel erklärt, wie Sie das nShift Checkout Widget zu Ihrer Webseite hinzufügen können, um die verschiedenen Lieferoptionen in Ihrem Webshop grafisch darzustellen.

 

Inhalt dieses Artikels:

• Links zu den Widget-Dateien hinzufügen
• Widget auf der Seite erstellen
• Widget anzeigen
• Widget mit Versandoptionen füllen

Links zu den Widget-Dateien hinzufügen

Für das Widget müssen zwei Dateien in die Webseite eingebunden werden: eine JavaScript-Datei, die den Widget-Code enthält, und eine CSS-Datei, die das Styling des Widgets hinzufügt.

Link zur JavaScript-Datei mit einem Script-Tag:

<script src="https://www.nshiftportal.com/checkout/widget/nshift-checkout-widget.js"></script>

Die JavaScript-Datei lädt bei Bedarf weitere JavaScript-Dateien, wenn das Widget zur Seite hinzugefügt wird. Falls dies Probleme verursacht, kann alternativ die Datei nshift.checkout-widget.all.js verwendet werden. Diese enthält den gesamten Code für das Widget in einer einzigen Datei.

Link zur CSS-Datei mit einem Link-Tag:

<link rel="stylesheet" href="https://www.nshiftportal.com/checkout/widget/nshift-checkout-widget.css">

Um das Styling des Widgets zu vereinfachen, kann es vorteilhaft sein, den Link zur CSS-Datei vor allen Links zu CSS-Dateien zu platzieren, die Regeln enthalten, die das Widget-Styling überschreiben.

Lokales Hosting der Dateien

Eine Alternative zum Verlinken der Widget-Dateien auf den nShift-Servern ist das lokale Hosting der Dateien. In diesem Fall sollte die Datei nshift-checkout-widget-all.js zusammen mit der normalen Datei nshift-checkout-widget.css verwendet werden.

Beachten Sie, dass der Hauptnachteil des lokalen Hostings darin besteht, dass Updates des Widgets durch nShift erst verfügbar sind, wenn die gehosteten Dateien aktualisiert werden. Der Vorteil ist, dass das Widget auf der Webseite verfügbar bleibt, selbst wenn es Probleme beim Lesen der Dateien von den nShift-Servern gibt. In einer Fallback-Lösung kann dies ein wichtiger Aspekt sein.

Widget auf der Seite erstellen

Nachdem der JavaScript-Code für das Widget in die Seite geladen wurde, kann das eigentliche Widget wie folgt erstellt werden:

var widget = nShiftCheckoutWidget.createWidget(containerElement, widgetSettings);

Container-Element
Das Container-Element-Argument der Funktion createWidget ist entweder ein tatsächliches HTML-DOM-Element-Objekt, das das übergeordnete Element des Widgets sein wird, oder es kann ein String sein, der einen Selektor für das HTML-DOM-Element enthält. Der Selektor-String wird in einem Aufruf von document.querySelector verwendet, um das Element zu finden.

Widget-Einstellungen
Das Argument für die Widget-Einstellungen der Funktion createWidget ist ein JavaScript-Objekt mit folgender Struktur:

{
  "widgetVersion": "2",
  "theme": "nshift-theme1",
  "themeOverride": {
    "showLogos": true,
    "showMap": true,
    "showPickupPointInfo": true,
    "showCategories": true,
    "showOriginalPrices": true,
    "showDeliveryTime": true,
    "selectFirstAvailableOption": true,
    "numberOfAlwaysVisibleTextLines": 1,
    "numberOfInitiallyVisibleOptions": 1
  },
  "mode": "standard",
  "widthBreakpoints": {
    "narrow": 400,
    "ultra-narrow": 300
  },
  "popupContainerElement": "document.querySelector('#root')",
  "resizeCallback": "(function(size) {
  })",
  "resultCallback": "(function(result) {
  })",
  "accessibilityChangeCallback": "(function(diff) {
  })",
  "accessibilityValidationCallback": "(function(message) {
  })"
}

• widgetVersion - Diese Eigenschaft muss derzeit immer der String "2" sein, um anzugeben, welche Version des Widgets erwartet wird.
   
• theme - Der Name des Styling-Themas ist optional, und das aktuell einzige gültige Thema ist "nshift-theme1"
   
• themeOverride - Das Unterobjekt, das Änderungen am ausgewählten Thema enthält, ist optional.
  • showLogos - Wenn diese Eigenschaft auf false gesetzt ist, werden keine Versanddienstleister-Logos im Widget angezeigt.
     
  • showMap - Wenn diese Eigenschaft auf false gesetzt ist, wird beim Auswählen von Abholpunkten keine Karte im Widget angezeigt.
     
  • showPickupPointInfo - Wenn diese Eigenschaft auf false gesetzt ist, werden keine zusätzlichen Informationen zu Abholpunkten angezeigt.
     
  • showCategories - Wenn diese Eigenschaft auf false gesetzt ist, werden keine Kategorienüberschriften im Widget angezeigt.
     
  • showOriginalPrices - Wenn diese Eigenschaft auf false gesetzt ist, werden keine Originalpreise neben dem normalen Preis im Widget angezeigt.
     
  • showDeliveryTime - Wenn diese Eigenschaft auf false gesetzt ist, werden keine Lieferzeiten in den dafür vorgesehenen Lieferzeit-Feldern des Widgets angezeigt.
     
  • selectFirstAvailableOption - Wenn diese Eigenschaft auf false gesetzt ist, wird die erste Option nicht mehr automatisch ausgewählt.
     
  • numberOfAlwaysVisibleTextLines - Es ist möglich, einen Wert zwischen 1-4 festzulegen, um Textfelder 1-4 ohne Auswahl einer Option anzuzeigen.
     
  • numberOfInitiallyVisibleOptions - Alle Optionen nach dieser Anzahl von Optionen werden zunächst ausgeblendet. Wenn diese Eigenschaft fehlt oder auf undefined gesetzt ist, gibt es keine Begrenzung, und alle Optionen werden immer angezeigt. 
     
• widthBreakpoints - Das Unterobjekt für Breiten-Breakpoints ist optional. Wenn es bereitgestellt wird, sollte es Schlüssel und Breitenwerte enthalten. Der Schlüssel mit dem kleinsten Breitenwert, der kleiner als die Breite des Widgets ist, wird ausgewählt. Der ausgewählte Schlüssel wird mit dem Präfix "nshift-breakpoint-" kombiniert und als CSS-Klasse zum obersten Widget-Element hinzugefügt. Dies kann verwendet werden, um das Styling basierend auf der Breite des Widgets auf der Webseite anzupassen.
   
• mode - Diese Eigenschaft kann auf "standard" für das normale Widget oder auf "product" gesetzt werden, um das schreibgeschützte Produktseiten-Widget zu erhalten. 
   
• accessibilityChangeCallback und accessibilityValidationCallback - Diese optionalen Eigenschaften können verwendet werden, um Barrierefreiheitsmeldungen in eine seitenweite Live-Region zu koordinieren. Wenn einer der Callbacks fehlt, erstellt das Widget einen Live-Region-Element innerhalb des Widget-Containers und verwendet diesen. 
   
• popupContainerElement - Diese Eigenschaft ist ein optionales HTML-DOM-Element, das als übergeordnetes Element für alle vom Widget erstellten Popup-Dialoge verwendet werden soll. Wenn kein Element bereitgestellt wird, erstellt der Widget-Code ein div-Element als direktes Kind des body-Elements.
   
• resizeCallback - Diese optionale Callback-Funktion wird aufgerufen, wenn sich die Größe des Widgets ändert. Das Argument size ist ein Objekt mit den Eigenschaften w und h für Breite und Höhe.
   
• resultCallback - Diese optionale Callback-Funktion wird immer dann aufgerufen, wenn ein Benutzer etwas im Widget ändert. Dies umfasst das Auswählen einer Versandoption, aber auch das Eingeben von Text in ein Feld wie eine Telefonnummer.

Widget anzeigen

Damit das Widget auf der Webseite angezeigt wird, muss die Methode install auf der Widget-Instanz aufgerufen werden. Dies erstellt die HTML-Elemente, die das Widget innerhalb des Container-Elements bilden.

  var widget = nShiftCheckoutWidget.createWidget(containerElement, widgetSettings);
  widget.install();

Falls das Widget von der Seite entfernt werden muss, kann dies durch Aufruf der Methode uninstall erfolgen.

widget.uninstall();

Widget mit Versandoptionen füllen

Beim ersten Anzeigen ist das Widget leer. Um es mit Versandoptionen zu füllen, muss das Widget mit Daten vom Versandoptionen-Endpunkt der nShift Checkout REST API aktualisiert werden. Die Methode updateOptions der Widget-Instanz nimmt die Versandoptionen-Daten als Argument und zeigt sie im Widget an.

// Deaktivieren der Benutzerinteraktion mit dem Widget während der Datenanforderung.
widget.disable();
// Versandoptionen-Daten vom Server abrufen.
fetch(url).then(function(response) {
   return response.json();
}).then(function(data) {
   // Widget mit Versandoptionen-Daten aktualisieren.
   widget.updateOptions(data);
}).catch(function() {
   // Fehler behandeln.
}).then(function() {
   // Benutzerinteraktion mit dem Widget immer wieder aktivieren.
   widget.enable();
});

Lesen Sie mehr über den Umgang mit externen und internen Änderungen im Widget hier.