Den här artikeln förklarar hur du lägger till nShift Checkout-widgeten på din webbsida så att du grafiskt kan visa de olika leveransalternativen i din webbshop.

 

Innehåll i denna artikel:

• Lägg till länkar till widget-filerna
• Skapa widgeten på sidan
• Visa widgeten
• Fyll widgeten med leveransalternativ

Lägg till länkar till widget-filerna

Två filer måste inkluderas på webbsidan för widgeten: en JavaScript-fil som innehåller widget-koden och en CSS-fil som lägger till widgetens stil.

Länk till JavaScript-filen med en script-tag:

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

JavaScript-filen kommer att inkludera ytterligare JavaScript-filer vid behov när widgeten läggs till på sidan. Om detta orsakar problem kan alternativfilen nshift.checkout-widget.all.js användas. Den innehåller all kod för widgeten i en enda fil.

Länk till CSS-filen med en link-tag:

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

För att förenkla formateringen av widgeten kan det vara fördelaktigt att placera länken till CSS-filen före andra länkar till CSS-filer som innehåller regler som skriver över widgetens stil.

Hosta filerna lokalt

Ett alternativ till att länka till widget-filerna på nShift-servrar är att hosta filerna lokalt. I så fall bör filen nshift-checkout-widget-all.js användas tillsammans med den vanliga filen nshift-checkout-widget.css.

Observera att den största nackdelen med att hosta filen lokalt är att eventuella uppdateringar av widgeten från nShift inte blir tillgängliga förrän de hostade filerna uppdateras. Fördelen är att widgeten kommer att vara tillgänglig på webbsidan även om det uppstår problem med att läsa filerna från nShift-servrar. I en fallback-lösning kan detta vara en viktig aspekt.

Skapa widgeten på sidan

Med JavaScript-koden för widgeten inläst på sidan kan själva widgeten skapas så här:

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

Container Element
Argumentet container element till funktionen createWidget är antingen ett faktiskt HTML DOM-elementobjekt som kommer att vara widgetens förälder, eller en sträng som innehåller en selector för HTML DOM-elementet. Selector-strängen används i ett anrop till document.querySelector för att hitta elementet.

Widget-inställningar
Argumentet widgetSettings till funktionen createWidget är ett JavaScript-objekt med följande 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 - Denna egenskap måste för närvarande alltid vara strängen "2" för att indikera vilken version av widgeten som förväntas.
   
• theme - Namnet på stiltemat är valfritt, och det enda giltiga temat just nu är "nshift-theme1"
   
• themeOverride - Underobjektet som innehåller ändringar av det valda temat är valfritt.
  • showLogos - Om denna egenskap är satt till false, visas inga transportörslogotyper i widgeten.
     
  • showMap - Om denna egenskap är satt till false, visas ingen karta när upphämtningsställen väljs i widgeten.
     
  • showPickupPointInfo - Om denna egenskap är satt till false, visas ingen ytterligare information för upphämtningsställen.
     
  • showCategories - Om denna egenskap är satt till false, visas inga kategorirubriker i widgeten.
     
  • showOriginalPrices - Om denna egenskap är satt till false, visas inga ursprungliga priser bredvid det normala priset i widgeten.
     
  • showDeliveryTime - Om denna egenskap är satt till false, visas inga leveranstider i widgetens dedikerade fält för leveranstid.
     
  • selectFirstAvailableOption - Om denna egenskap är satt till false väljs inte längre det första alternativet automatiskt.
     
  • numberOfAlwaysVisibleTextLines - Det går att ange ett värde mellan 1-4 för att visa textfält 1-4 utan att något alternativ är valt.
     
  • numberOfInitiallyVisibleOptions - Eventuella alternativ efter detta antal alternativ kommer initialt att vara dolda. Om denna egenskap saknas eller är satt till undefined finns ingen gräns, och alla alternativ visas alltid. 
     
• widthBreakpoints - Underobjektet för breddbrytningar är valfritt. Om det anges ska det innehålla nycklar och breddvärden. Nyckeln med det minsta breddvärdet som är mindre än widgetens bredd kommer att väljas. Den valda nyckeln kombineras med prefixet "nshift-breakpoint-" och läggs till som en CSS-klass på widgetens översta element. Detta kan användas för att justera stilen baserat på widgetens bredd på webbsidan.
   
• mode - Denna egenskap kan sättas till "standard" för den normala widgeten, eller till "product" för att få widgeten för produkt-sidan i läsläge. 
   
• accessibilityChangeCallback och accessibilityValidationCallback - Dessa valfria egenskaper kan användas för att samordna tillgänglighetsmeddelanden till en sida-omfattande live-region. Om någon av callbacks saknas kommer widgeten att skapa och använda ett live-region-element inuti widgetens container. 
   
• popupContainerElement - Denna egenskap är ett valfritt HTML DOM-element som bör användas som förälder för eventuella popup-dialoger som skapas av widgeten. Om inget element anges kommer widget-koden att skapa ett div-element som direkt barn till body-elementet.
   
• resizeCallback - Denna valfria callback-funktion anropas när widgetens storlek ändras. Argumentet size är ett objekt med egenskaperna w och h för bredd och höjd.
   
• resultCallback - Denna valfria callback-funktion anropas varje gång en användare ändrar något i widgeten. Detta inkluderar att välja ett leveransalternativ, men också att skriva text i ett fält som ett telefonnummer.

Visa widgeten

För att få widgeten att visas på webbsidan måste metoden install anropas på widget-instansen. Detta skapar HTML-elementen som utgör widgeten inuti container-elementet.

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

Om det finns behov av att ta bort widgeten från sidan kan detta göras genom att anropa metoden uninstall.

widget.uninstall();

Fyll widgeten med leveransalternativ

När widgeten visas första gången är den tom. För att fylla den med leveransalternativ måste widgeten uppdateras med data från endpointen för leveransalternativ i nShift Checkout REST API. Metoden updateOptions på widget-instansen tar leveransalternativens data som argument och visar dem i widgeten.

// Inaktivera användarinteraktion med widgeten under begäran om data.
widget.disable();
// Hämta leveransalternativ-data från servern.
fetch(url).then(function(response) {
   return response.json();
}).then(function(data) {
   // Uppdatera widgeten med leveransalternativ-data.
   widget.updateOptions(data);
}).catch(function() {
   // Hantera fel.
}).then(function() {
   // Aktivera alltid användarinteraktion med widgeten.
   widget.enable();
});

Läs om hantering av externa och interna ändringar i widgeten här.