This article will explain how to add the nShift Checkout widget to your web page so you can graphically present the different delivery options in your webshop.

 

Content in this article:

• Add links to the widget files
• Create the widget on the page
• Show the widget
• Fill the widget with shipping options

Add links to the widget files

Two files must be included in the web page for the widget: a JavaScript file that contains the widget code and a CSS file that adds the styling of the widget.

Link to the JavaScript file with a script tag:

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

The JavaScript file will include additional JavaScript files on demand when the widget is added to the page. If this causes any problems, the alternative file nshift.checkout-widget.all.js can be used. It contains all of the code for the widget in a single file.

Link to the CSS file with a link tag:

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

To simplify styling the widget, it might be beneficial to place the link to the CSS file before any links to CSS files that contain rules that override widget styling.

Hosting the files locally

An alternative to linking to the widget files on nShift servers is to host the files locally. In that case, the nshift-checkout-widget-all.js file should be used together with the normal nshift-checkout-widget.css file.

Note that the main downside to hosting the file locally is that any updates to the widget by nShift will not become available until the hosted files are updated. The advantage is that the widget will be available on the web page even if there is a problem reading the files from nShift servers. In a fallback solution, this might be an important aspect.

Create the widget on the page

With the JavaScript code for the widget loaded into the page, the actual widget can be created like this:

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

Container Element
The container element argument to the createWidget function is either an actual HTML DOM element object that will be the parent of the widget. Or it can be a string containing a selector for the HTML DOM element. The selector string will be used in a call to document.querySelector to find the element.

Widget Settings
The widget settings argument to the createWidget function is a JavaScript object with the following structure:

{
  "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 - This property must currently always be the string "2" to indicate what version of the widget is expected.
   
• theme - The name of the styling theme is optional, and the only valid theme right now is "nshift-theme1"
   
• themeOverride - The sub object containing changes to the selected theme is optional.
  • showLogos - If this property is set to false, no carrier logos will be shown in the widget.
     
  • showMap - If this property is set to false, no map will be shown when selecting pickup points in the widget.
     
  • showPickupPointInfo - If this property is set to false, no additional information for pickup points will be shown.
     
  • showCategories - If this property is set to false, no category headers will be shown in the widget.
     
  • showOriginalPrices - If this property is set to false, no original prices will be shown next to the normal price in the widget.
     
  • showDeliveryTime - If this property is set to false, no delivery times will be shown in the dedicated delivery time fields of the widget.
     
  • selectFirstAvailableOption - If this property is set to false, the first option is no longer automatically selected.
     
  • numberOfAlwaysVisibleTextLines - It is possible to set a value between 1-4 to display text fields 1-4 without an option being selected.
     
  • numberOfInitiallyVisibleOptions - Any options after this number of options will initially be hidden. If this property is missing or set to undefined, then there is no limit, and all options will always be shown. 
     
• widthBreakpoints - The subobject for width breakpoints is optional. If it is provided, it should contain keys and width values. The key with the smallest width value less than the width of the widget will be selected. The selected key is combined with the prefix "nshift-breakpoint-" and added as a CSS class to the toplevel widget element. This can be used to adjust styling based on the width of the widget on the web page.
   
• mode - This property can be set to "standard" for the normal widget, or to "product" to get the read-only product page widget. 
   
• accessibilityChangeCallback and accessibilityValidationCallback - These optional properties can be used to coordinate accessibility messages into a page-wide live region. If either callback is missing, the widget will create and use a live region element inside the widget container. 
   
• popupContainerElement - This property is an optional HTML DOM element that should be used as the parent of any popup dialog created by the widget. If no element is provided, the widget code will create a div element as a direct child of the body element.
   
• resizeCallback - This optional callback function will be called when the size of the widget changes. The size argument is an object with the properties w and h for width and height.
   
• resultCallback - This optional callback function will be called whenever a user changes something in the widget. This includes selecting a shipping option, but also entering text in a field like a phone number.

Show the widget

To get the widget to show up on the web page, the method install must be called on the widget instance. This will create the HTML elements that make up the widget inside the container element.

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

If there is a need to remove the widget from the page, this can be done by calling the uninstall method.

widget.uninstall();

Fill the widget with shipping options

When first shown, the widget will be empty. To fill it with shipping options, the widget must be updated with data from the shipping options endpoint of the nShift Checkout REST API. The updateOptions method of the widget instance takes the shipping options data as an argument and displays it in the widget.

// Disable user interaction with the widget during the request for data.
widget.disable();
// Fetch shipping options data from the server.
fetch(url).then(function(response) {
   return response.json();
}).then(function(data) {
   // Update the widget with shipping options data.
   widget.updateOptions(data);
}).catch(function() {
   // Handle error.
}).then(function() {
   // Always enable user interaction with the widget.
   widget.enable();
});

Read about handling external and internal changes in the widget here.