Dit artikel legt uit hoe u de nShift Checkout widget aan uw webpagina toevoegt, zodat u grafisch de verschillende leveringsopties in uw webshop kunt presenteren.

 

Inhoud van dit artikel:

• Links toevoegen naar de widget-bestanden
• De widget op de pagina aanmaken
• De widget weergeven
• De widget vullen met verzendopties

Links toevoegen naar de widget-bestanden

Twee bestanden moeten in de webpagina worden opgenomen voor de widget: een JavaScript-bestand met de widgetcode en een CSS-bestand dat de styling van de widget toevoegt.

Link naar het JavaScript-bestand met een script-tag:

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

Het JavaScript-bestand zal op aanvraag aanvullende JavaScript-bestanden laden wanneer de widget aan de pagina wordt toegevoegd. Als dit problemen veroorzaakt, kan het alternatieve bestand nshift.checkout-widget.all.js worden gebruikt. Dit bevat alle code voor de widget in één bestand.

Link naar het CSS-bestand met een link-tag:

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

Om het stylen van de widget te vereenvoudigen, kan het nuttig zijn om de link naar het CSS-bestand vóór links naar CSS-bestanden te plaatsen die regels bevatten die de widget-styling overschrijven.

Bestanden lokaal hosten

Een alternatief voor het linken naar de widget-bestanden op de nShift-servers is om de bestanden lokaal te hosten. In dat geval moet het bestand nshift-checkout-widget-all.js worden gebruikt samen met het normale nshift-checkout-widget.css bestand.

Let op: het grootste nadeel van lokaal hosten is dat eventuele updates van de widget door nShift niet beschikbaar zijn totdat de gehoste bestanden zijn bijgewerkt. Het voordeel is dat de widget beschikbaar blijft op de webpagina, zelfs als er een probleem is met het lezen van de bestanden van de nShift-servers. Dit kan een belangrijk aspect zijn in een fallback-oplossing.

De widget op de pagina aanmaken

Met de JavaScript-code voor de widget geladen in de pagina, kan de daadwerkelijke widget als volgt worden aangemaakt:

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

Container Element
Het container element argument van de createWidget functie is ofwel een daadwerkelijk HTML DOM element object dat de ouder van de widget zal zijn, of het kan een string zijn met een selector voor het HTML DOM element. De selector string wordt gebruikt in een aanroep naar document.querySelector om het element te vinden.

Widget Instellingen
Het widget instellingen argument van de createWidget functie is een JavaScript-object met de volgende structuur:

{
  "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 - Deze eigenschap moet momenteel altijd de string "2" zijn om aan te geven welke versie van de widget wordt verwacht.
   
• theme - De naam van het stylingthema is optioneel, en het enige geldige thema op dit moment is "nshift-theme1"
   
• themeOverride - Het subobject met wijzigingen ten opzichte van het geselecteerde thema is optioneel.
  • showLogos - Als deze eigenschap op false wordt gezet, worden er geen vervoerderslogo’s in de widget getoond.
     
  • showMap - Als deze eigenschap op false wordt gezet, wordt er geen kaart getoond bij het selecteren van afhaalpunten in de widget.
     
  • showPickupPointInfo - Als deze eigenschap op false wordt gezet, worden er geen extra informatie voor afhaalpunten getoond.
     
  • showCategories - Als deze eigenschap op false wordt gezet, worden er geen categorie-koppen in de widget getoond.
     
  • showOriginalPrices - Als deze eigenschap op false wordt gezet, worden er geen originele prijzen naast de normale prijs in de widget getoond.
     
  • showDeliveryTime - Als deze eigenschap op false wordt gezet, worden er geen levertijden getoond in de speciale levertijdvelden van de widget.
     
  • selectFirstAvailableOption - Als deze eigenschap op false wordt gezet, wordt de eerste optie niet automatisch geselecteerd.
     
  • numberOfAlwaysVisibleTextLines - Het is mogelijk een waarde tussen 1-4 in te stellen om tekstvelden 1-4 te tonen zonder dat een optie geselecteerd is.
     
  • numberOfInitiallyVisibleOptions - Opties na dit aantal opties worden aanvankelijk verborgen. Als deze eigenschap ontbreekt of op undefined staat, is er geen limiet en worden alle opties altijd getoond. 
     
• widthBreakpoints - Het subobject voor breedte-breakpoints is optioneel. Als het wordt opgegeven, moet het sleutels en breedtewaarden bevatten. De sleutel met de kleinste breedtewaarde die kleiner is dan de breedte van de widget wordt geselecteerd. De geselecteerde sleutel wordt gecombineerd met het voorvoegsel "nshift-breakpoint-" en toegevoegd als CSS-klasse aan het top-level widget-element. Dit kan worden gebruikt om de styling aan te passen op basis van de breedte van de widget op de webpagina.
   
• mode - Deze eigenschap kan worden ingesteld op "standard" voor de normale widget, of op "product" om de alleen-lezen productpagina widget te krijgen. 
   
• accessibilityChangeCallback en accessibilityValidationCallback - Deze optionele eigenschappen kunnen worden gebruikt om toegankelijkheidsberichten te coördineren in een pagina-brede live regio. Als een van beide callbacks ontbreekt, maakt de widget een live regio-element aan binnen de widgetcontainer. 
   
• popupContainerElement - Deze eigenschap is een optioneel HTML DOM element dat als ouder moet worden gebruikt voor elke popupdialoog die door de widget wordt gemaakt. Als geen element wordt opgegeven, maakt de widgetcode een div-element aan als directe kind van het body-element.
   
• resizeCallback - Deze optionele callback-functie wordt aangeroepen wanneer de grootte van de widget verandert. Het size argument is een object met de eigenschappen w en h voor breedte en hoogte.
   
• resultCallback - Deze optionele callback-functie wordt aangeroepen telkens wanneer een gebruiker iets wijzigt in de widget. Dit omvat het selecteren van een verzendoptie, maar ook het invoeren van tekst in een veld zoals een telefoonnummer.

De widget weergeven

Om de widget op de webpagina te laten verschijnen, moet de methode install worden aangeroepen op de widget-instantie. Dit creëert de HTML-elementen die de widget vormen binnen het container-element.

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

Als er behoefte is om de widget van de pagina te verwijderen, kan dit worden gedaan door de uninstall-methode aan te roepen.

widget.uninstall();

De widget vullen met verzendopties

Wanneer de widget voor het eerst wordt getoond, is deze leeg. Om deze te vullen met verzendopties, moet de widget worden bijgewerkt met gegevens van het verzendopties-eindpunt van de nShift Checkout REST API. De updateOptions-methode van de widget-instantie neemt de verzendopties-gegevens als argument en toont deze in de widget.

// Schakel gebruikersinteractie met de widget uit tijdens het opvragen van gegevens.
widget.disable();
// Haal verzendopties-gegevens op van de server.
fetch(url).then(function(response) {
   return response.json();
}).then(function(data) {
   // Werk de widget bij met verzendopties-gegevens.
   widget.updateOptions(data);
}).catch(function() {
   // Fout afhandelen.
}).then(function() {
   // Schakel altijd gebruikersinteractie met de widget weer in.
   widget.enable();
});

Lees over het omgaan met externe en interne wijzigingen in de widget hier.