Skip to main content

Widget

ESSENTIAL

You can install the delivery checkout widget to graphically present the delivery options in your webshop.

Installation

To use the widget on a page the javascript file containing the widget code must be included. There are two possible javascript files to include. Both are UMD modules which means that they can be included either with a simple script tag or using a module loading system like RequireJS. The difference between the files is that one doesn't contain ReactJS and instead expects global variables window.React and window.ReactDOM to reference the react and react-dom modules respectively.

The javascript file without ReactJS can be accessed at:

https://api.unifaun.com/rs-extapi/v1/delivery-checkouts-widget/unifaun-checkout.min.js

The javascript file with all dependencies bundled can be accessed at:

https://api.unifaun.com/rs-extapi/v1/delivery-checkouts-widget/unifaun-checkout-all.min.js

Once one of the files has been included on the page you can access it depending on your method of inclusion. If you use a module loading system, refer to the standard way of accessing modules in that system. If you include the module with a script tag the module can be accessed through a global variable window.UnifaunCheckout.

Usage

To display the widget on a page and to get notified when a buyer makes choices in the widget, an instance of the widget must be created. An instance is created with the createAt function exported from the module.

var widget = UnifaunCheckout.createAt(containerElement, config;)

As argument containerElement pass an element selector as a string or a DOM element. The widget UI will be injected as a child to the containerElement.

The config argument must be a javascript object with any of these keys:

Key

Description

Type

Value

language

Language code for the language to be used in the UI

string

da, de, cs, en, es, et, fi, fr, it, nl, no, pl, ru, sv

useIcons

Use carrier logo icons or not

boolean

true, false

iconsInFront

Place carrier logo icons before the title and description of the delivery option. Otherwise after.

boolean

true, false

iconsBaseUrl

Base URL to use for carrier logo icon images.

string

Logos from nShift: https://api.unifaun.com/rs-extapi/v1/delivery-checkouts-widget/logos

installCSS

Install standard CSS rules for the widget. The CSS rules will be inserted as a style tag at the start of the head tag.

Note

To enable the map widget you need to use the "nshift" or "nshift-mp" value.

boolean⎮string

false = No design

true = Design 1

nshift = Design 2

nshift-mp = Design 3

(Deprecated:

unifaun = Design 2

unifaun-mp = Design 3)

narrowDisplay

Toggle narrow display mode on. When on the widget layout will stack some UI elements vertically to work better on screens with low horizontal resolution.

boolean

true, false

narrowBreakpointWidth

The min. width of the widget element when narrow mode will be activated. If this value is supplied an event listener will be added to the window to track size changes.

number

ultraNarrowBreakpointWidth

The min. width of the widget element when ultra narrow mode will be activated.

number

resultCallback

Callback function that will be called whenever a buyer makes a selection or data entry in the widget UI.

function

enableMap

Enable an interactive map where the user can select a pickup point from a map interface.

Only visible if pickup points with valid latitude and longitude coordinates are available for the selected option.

Caution

For the map to work you must use the "nshift" or "nshift-mp" CSS in the installCSS parameter.

Deprecated: "unifaun" and unifaun-mp"

boolean

true, false (default)

Once a widget instance has been created it can be used to control the widget. The methods available on the widget are:

Method

Description

installCSS()

Call this method to install the CSS rules.

uninstallCSS()

Call this method to remove the CSS rules from the page.

changeNarrowDisplay(narrow)

Call this method with a boolean argument to change the UI to, or from, narrow mode.

changeNarrowBreakpointWidth(narrowWidth, ultraNarrowWidth)

Call this method with the pixel width of the widget element when the widget UI should change to narrow mode. A second optional argument sets the pixel width of the widget element when ultra narrow mode should be activated.

checkWidthBreakpoints()

Call this method to let the widget check the width of its element and update, to or from, narrow/ultra narrow mode.

enable()

Call this method to enable the widget UI and allow users to change options.

disable()

Call this method to disable the widget UI and stop users from making changes.

updateList(optionsList)

Call this method with the result of a call to the /delivery-checkouts REST API. The optionsList object should contain the data to be displayed by the widget.

getResult

Call this method to get the result object last sent to the resultCallback.

setResult(result)

Call this method with a result object like the parameter to the resultCallback.The widget state will update to reflect the selections made in the result object.

Styling

A default style sheet can be injected into the page by setting the installCSS property in the widget configuration or by calling the installCSS method on the widget instance. The source of the injected style sheet in the form of a SASS file can be accessed at:

https://api.unifaun.com/rs-extapi/v1/delivery-checkouts-widget/unifaun-checkout.scss

User interaction

There are two types of user interaction that affect the widget:

  • External changes

  • Internal changes

External changes

When first created and every time the user makes changes to one of the input variables sent to the /delivery-checkouts API this sequence of actions should occur:

  • Disable the widget with a call to the disable method.

  • Make an AJAX request to the /delivery-checkouts API. The web shop backend will normally act as a proxy for this type of call so that a secret API key can be sent to the REST API.

  • When a response arrives, call the updateList method and then enable the widget with a call to the enable method.

// Disable widget while AJAX request is in progress.
widget.disable();
fetch(url).then(function(response) {
    return response.json();
}).then(function(data) {
    //Update the widget with new data.
    widget.updateList(data);
}).catch(function() {
    //Handle error
}).then(function() {
    //Always enable widget
    widget.enable();
});

Internal changes

Whenever the user selects one of the delivery checkout options or updates any value connected to the selected option, the resultCallback function in the widget configuration will be called. The callback function will receive a single argument in the form of a javascript object with the following properties:

Property

Description

Type

Value

valid

Indicates if the current values in the widget are all valid. Only if this is true should the user be able to proceed with the checkout.

boolean

true, false

deliveryCheckoutId

The delivery checkout ID including version.

string

 

selectedOptionId

The ID of the currently selected delivery option.

string

 

optionIds

An array of selected delivery checkout option ID:s from highest to lowest level.

string[]

 

price

The total price of all selected delivery options and addons

number

 

agent

The selected agent ID.

string

 

selectedAddons

An array of selected addons.

AddonResult[]

fields

An array of values for additional input related to the selected delivery option.

FieldResult[]