Denne artikkelen forklarer hvordan du legger til nShift Checkout-widgeten på nettsiden din slik at du grafisk kan presentere de forskjellige leveringsalternativene i nettbutikken din.

 

Innhold i denne artikkelen:

• Legg til lenker til widget-filene
• Opprett widgeten på siden
• Vis widgeten
• Fyll widgeten med fraktalternativer

Legg til lenker til widget-filene

To filer må inkluderes på nettsiden for widgeten: en JavaScript-fil som inneholder widget-koden og en CSS-fil som legger til stilen til widgeten.

Lenke til JavaScript-filen med en script-tag:

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

JavaScript-filen vil inkludere flere JavaScript-filer ved behov når widgeten legges til på siden. Hvis dette skaper problemer, kan alternativfilen nshift.checkout-widget.all.js brukes. Den inneholder all koden for widgeten i én enkelt fil.

Lenke til CSS-filen med en link-tag:

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

For å forenkle stilen til widgeten kan det være fordelaktig å plassere lenken til CSS-filen før eventuelle lenker til CSS-filer som inneholder regler som overstyrer widget-stilen.

Hosting av filene lokalt

Et alternativ til å lenke til widget-filene på nShift-servere er å hoste filene lokalt. I så fall bør filen nshift-checkout-widget-all.js brukes sammen med den vanlige nshift-checkout-widget.css-filen.

Merk at hovedulempen med å hoste filen lokalt er at eventuelle oppdateringer av widgeten fra nShift ikke vil bli tilgjengelige før de hostede filene oppdateres. Fordelen er at widgeten vil være tilgjengelig på nettsiden selv om det oppstår problemer med å lese filene fra nShift-serverne. I en fallback-løsning kan dette være et viktig aspekt.

Opprett widgeten på siden

Med JavaScript-koden for widgeten lastet inn på siden, kan selve widgeten opprettes slik:

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

Container-element
Container-element-argumentet til createWidget-funksjonen er enten et faktisk HTML DOM-elementobjekt som vil være forelder til widgeten, eller det kan være en streng som inneholder en selektor for HTML DOM-elementet. Selektorstrengen vil bli brukt i et kall til document.querySelector for å finne elementet.

Widget-innstillinger
Widget-innstillingsargumentet til createWidget-funksjonen 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 egenskapen må for øyeblikket alltid være strengen "2" for å indikere hvilken versjon av widgeten som forventes.
   
• theme - Navnet på stiltemaet er valgfritt, og det eneste gyldige temaet akkurat nå er "nshift-theme1"
   
• themeOverride - Underobjektet som inneholder endringer til det valgte temaet er valgfritt.
  • showLogos - Hvis denne egenskapen settes til false, vil ingen transportørlogoer vises i widgeten.
     
  • showMap - Hvis denne egenskapen settes til false, vil ikke noe kart vises ved valg av hentepunkter i widgeten.
     
  • showPickupPointInfo - Hvis denne egenskapen settes til false, vil ingen tilleggsinformasjon for hentepunkter vises.
     
  • showCategories - Hvis denne egenskapen settes til false, vil ingen kategorititler vises i widgeten.
     
  • showOriginalPrices - Hvis denne egenskapen settes til false, vil ingen opprinnelige priser vises ved siden av normalprisen i widgeten.
     
  • showDeliveryTime - Hvis denne egenskapen settes til false, vil ingen leveringstider vises i de dedikerte leveringstidfeltene i widgeten.
     
  • selectFirstAvailableOption - Hvis denne egenskapen settes til false, vil ikke det første alternativet lenger bli valgt automatisk.
     
  • numberOfAlwaysVisibleTextLines - Det er mulig å sette en verdi mellom 1-4 for å vise tekstfelt 1-4 uten at et alternativ er valgt.
     
  • numberOfInitiallyVisibleOptions - Eventuelle alternativer etter dette antallet vil i utgangspunktet være skjult. Hvis denne egenskapen mangler eller settes til undefined, er det ingen grense, og alle alternativer vil alltid vises. 
     
• widthBreakpoints - Underobjektet for bredde-brytepunkter er valgfritt. Hvis det oppgis, skal det inneholde nøkler og breddeverdier. Nøkkelen med den minste breddeverdien mindre enn bredden på widgeten vil bli valgt. Den valgte nøkkelen kombineres med prefikset "nshift-breakpoint-" og legges til som en CSS-klasse på toppnivå-elementet for widgeten. Dette kan brukes til å justere stilen basert på bredden til widgeten på nettsiden.
   
• mode - Denne egenskapen kan settes til "standard" for normal widget, eller til "product" for å få den skrivebeskyttede produktside-widgeten. 
   
• accessibilityChangeCallback og accessibilityValidationCallback - Disse valgfrie egenskapene kan brukes til å koordinere tilgjengelighetsmeldinger til en sideomfattende live-region. Hvis en av callback-funksjonene mangler, vil widgeten opprette og bruke et live-region-element inne i widget-containeren. 
   
• popupContainerElement - Denne egenskapen er et valgfritt HTML DOM-element som skal brukes som forelder til eventuelle popup-dialoger opprettet av widgeten. Hvis ingen element oppgis, vil widget-koden opprette et div-element som direkte barn av body-elementet.
   
• resizeCallback - Denne valgfrie callback-funksjonen kalles når størrelsen på widgeten endres. size-argumentet er et objekt med egenskapene w og h for bredde og høyde.
   
• resultCallback - Denne valgfrie callback-funksjonen kalles når en bruker endrer noe i widgeten. Dette inkluderer valg av fraktalternativ, men også inntasting i et felt som telefonnummer.

Vis widgeten

For å få widgeten til å vises på nettsiden må metoden install kalles på widget-instansen. Dette vil opprette HTML-elementene som utgjør widgeten inne i container-elementet.

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

Hvis det er behov for å fjerne widgeten fra siden, kan dette gjøres ved å kalle uninstall-metoden.

widget.uninstall();

Fyll widgeten med fraktalternativer

Når widgeten først vises, vil den være tom. For å fylle den med fraktalternativer må widgeten oppdateres med data fra fraktalternativ-endepunktet til nShift Checkout REST API. updateOptions-metoden til widget-instansen tar fraktalternativ-dataene som argument og viser dem i widgeten.

// Deaktiver brukerinteraksjon med widgeten under forespørselen om data.
widget.disable();
// Hent fraktalternativdata fra serveren.
fetch(url).then(function(response) {
   return response.json();
}).then(function(data) {
   // Oppdater widgeten med fraktalternativdata.
   widget.updateOptions(data);
}).catch(function() {
   // Håndter feil.
}).then(function() {
   // Aktiver alltid brukerinteraksjon med widgeten.
   widget.enable();
});

Les om håndtering av eksterne og interne endringer i widgeten her.