Denne artikel forklarer, hvordan du tilføjer nShift Checkout-widgeten til din webside, så du grafisk kan præsentere de forskellige leveringsmuligheder i din webshop.

 

Indhold i denne artikel:

• Tilføj links til widget-filerne
• Opret widgeten på siden
• Vis widgeten
• Fyld widgeten med forsendelsesmuligheder

Tilføj links til widget-filerne

To filer skal inkluderes på websiden for widgeten: en JavaScript-fil, der indeholder widget-koden, og en CSS-fil, der tilføjer styling til widgeten.

Link til JavaScript-filen med et script-tag:

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

JavaScript-filen vil inkludere yderligere JavaScript-filer efter behov, når widgeten tilføjes til siden. Hvis dette forårsager problemer, kan den alternative fil nshift.checkout-widget.all.js bruges. Den indeholder al koden til widgeten i én enkelt fil.

Link til CSS-filen med et link-tag:

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

For at forenkle stylingen af widgeten kan det være fordelagtigt at placere linket til CSS-filen før eventuelle links til CSS-filer, der indeholder regler, som tilsidesætter widget-stylingen.

Hosting af filerne lokalt

Et alternativ til at linke til widget-filerne på nShift-servere er at hoste filerne lokalt. I så fald bør filen nshift-checkout-widget-all.js bruges sammen med den normale nshift-checkout-widget.css-fil.

Bemærk, at hovedulemperne ved at hoste filerne lokalt er, at eventuelle opdateringer til widgeten fra nShift ikke bliver tilgængelige, før de hostede filer opdateres. Fordelen er, at widgeten vil være tilgængelig på websiden, selvom der er problemer med at læse filerne fra nShift-serverne. I en fallback-løsning kan dette være en vigtig faktor.

Opret widgeten på siden

Med JavaScript-koden til widgeten indlæst på siden kan den faktiske widget oprettes således:

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

Container Element
Argumentet container element til createWidget-funktionen er enten et faktisk HTML DOM-elementobjekt, som vil være widgetens overordnede element, eller det kan være en streng, der indeholder en selector for HTML DOM-elementet. Selector-strengen vil blive brugt i et kald til document.querySelector for at finde elementet.

Widget-indstillinger
Argumentet widgetSettings til createWidget-funktionen er et JavaScript-objekt med følgende 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 - Denne egenskab skal i øjeblikket altid være strengen "2" for at angive, hvilken version af widgeten der forventes.
   
• theme - Navnet på styling-temaet er valgfrit, og det eneste gyldige tema lige nu er "nshift-theme1"
   
• themeOverride - Underelementet, der indeholder ændringer til det valgte tema, er valgfrit.
  • showLogos - Hvis denne egenskab sættes til false, vises der ingen transportørlogoer i widgeten.
     
  • showMap - Hvis denne egenskab sættes til false, vises der ikke noget kort ved valg af afhentningssteder i widgeten.
     
  • showPickupPointInfo - Hvis denne egenskab sættes til false, vises der ingen yderligere information om afhentningssteder.
     
  • showCategories - Hvis denne egenskab sættes til false, vises der ingen kategorihoveder i widgeten.
     
  • showOriginalPrices - Hvis denne egenskab sættes til false, vises der ingen oprindelige priser ved siden af den normale pris i widgeten.
     
  • showDeliveryTime - Hvis denne egenskab sættes til false, vises der ingen leveringstider i de dedikerede leveringstidsfelter i widgeten.
     
  • selectFirstAvailableOption - Hvis denne egenskab sættes til false, vælges den første mulighed ikke automatisk.
     
  • numberOfAlwaysVisibleTextLines - Det er muligt at sætte en værdi mellem 1-4 for at vise tekstfelter 1-4 uden at en mulighed er valgt.
     
  • numberOfInitiallyVisibleOptions - Eventuelle muligheder efter dette antal vil oprindeligt være skjult. Hvis denne egenskab mangler eller sættes til undefined, er der ingen grænse, og alle muligheder vil altid blive vist. 
     
• widthBreakpoints - Underelementet for bredde-breakpoints er valgfrit. Hvis det leveres, skal det indeholde nøgler og breddeværdier. Nøglen med den mindste breddeværdi mindre end widgetens bredde vil blive valgt. Den valgte nøgle kombineres med præfikset "nshift-breakpoint-" og tilføjes som en CSS-klasse til det øverste widget-element. Dette kan bruges til at justere stylingen baseret på widgetens bredde på websiden.
   
• mode - Denne egenskab kan sættes til "standard" for den normale widget eller til "product" for at få den skrivebeskyttede produktside-widget. 
   
• accessibilityChangeCallback og accessibilityValidationCallback - Disse valgfrie egenskaber kan bruges til at koordinere tilgængelighedsmeddelelser i en sideomfattende live-region. Hvis en af callbacks mangler, opretter og bruger widgeten et live-region-element inde i widget-containeren. 
   
• popupContainerElement - Denne egenskab er et valgfrit HTML DOM-element, der bør bruges som overordnet element for eventuelle popup-dialoger oprettet af widgeten. Hvis der ikke leveres noget element, opretter widget-koden et div-element som direkte barn af body-elementet.
   
• resizeCallback - Denne valgfrie callback-funktion kaldes, når størrelsen på widgeten ændres. Argumentet size er et objekt med egenskaberne w og h for bredde og højde.
   
• resultCallback - Denne valgfrie callback-funktion kaldes, når en bruger ændrer noget i widgeten. Dette inkluderer valg af en forsendelsesmulighed, men også indtastning af tekst i et felt som f.eks. et telefonnummer.

Vis widgeten

For at få widgeten til at vises på websiden, skal metoden install kaldes på widget-instansen. Dette vil oprette de HTML-elementer, der udgør widgeten inde i container-elementet.

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

Hvis der er behov for at fjerne widgeten fra siden, kan dette gøres ved at kalde uninstall-metoden.

widget.uninstall();

Fyld widgeten med forsendelsesmuligheder

Når widgeten vises første gang, vil den være tom. For at fylde den med forsendelsesmuligheder skal widgeten opdateres med data fra forsendelsesmuligheds-endpointet i nShift Checkout REST API. Metoden updateOptions på widget-instansen tager forsendelsesdataene som argument og viser dem i widgeten.

// Deaktiver brugerinteraktion med widgeten under forespørgslen om data.
widget.disable();
// Hent forsendelsesdata fra serveren.
fetch(url).then(function(response) {
   return response.json();
}).then(function(data) {
   // Opdater widgeten med forsendelsesdata.
   widget.updateOptions(data);
}).catch(function() {
   // Håndter fejl.
}).then(function() {
   // Aktiver altid brugerinteraktion med widgeten.
   widget.enable();
});

Læs om håndtering af eksterne og interne ændringer i widgeten her.