A split shipping web form allows users to populate shipping options for each cart item. The shippingGroupRelationships
property (which is an observable array) captures the split shipping options for each cart item. Each instance of a ShippingGroupRelationships
object associates a quantity of cart item with a given shipping address and shipping method. A single cart item can have several ShippingGroupRelationships
instances, allowing the cart item to be split across several shipping groups.
Quantity field
The Quantity field allows the shopper to specify the portion of cart item to be associated with a given shipping group. The following code shows a sample UI binding pattern for this feature:
<!-- ko foreach: cart().items --> <!-- ko foreach: shippingGroupRelationships --> <input type="number" name="quantity" class="form-control" data-bind=" value: quantity, event: {change: $parents[1].priceSplitShippingCartForCheckout}"> <!-- /ko --> <!-- /ko -->
Note: A change of Quantity will cause the widget to make a pricing call, provided the split shipping form is complete and valid.
Shipping Address field
The Shipping Address field allows the shopper to select a shipping address for the specified quantity of the cart item. The following code shows a sample UI binding pattern for this feature:
<!-- ko foreach: cart().items --> <!-- ko foreach: shippingGroupRelationships --> <select class="form-control" name="shippingAddress" data-bind="options: $parents[1].user().shippingAddressBook(), optionsText: $parents[1].getOptionTextForAddress, value: shippingAddress, optionsCaption: 'Select shipping address', event: {change: $parents[1].lookupShippingOptions}"> </select> <!-- /ko --> <!-- /ko -->
Shipping Address options should be retrieved from the profile’s shipping address book so that updates to the shipping address book will automatically be reflected in the options list. A change of Shipping Address must trigger a method in your widget that makes an AJAX service call to retrieve the valid shipping options for the selected address and product. The product ID must be passed in this call because some products may have a shipping surcharge and not all shipping methods can be used for products with surcharges.
Shipping Method field
The Shipping Method field allows the shopper to select a shipping method for the specified quantity of the cart item. The following code shows a sample UI binding pattern for this feature:
<!-- ko foreach: cart().items --> <!-- ko foreach: shippingGroupRelationships --> <select class="form-control" name="shippingMethod" data-bind="options: shippingOptions, optionsText: 'displayName', value: shippingMethod, optionsCaption: 'Select shipping method', enable: shippingAddress, event: {change: $parents[1].priceSplitShippingCartForCheckout}"> </select> <!-- /ko --> <!-- /ko -->
The Shipping Method options displayed to the shopper must be populated by a method in your widget that makes an AJAX service call to retrieve the valid shipping options for the selected address. A change of Shipping Address should trigger this method.
A change of Shipping Method should cause the widget to make a pricing call, provided the split shipping form is complete and valid.
Split Items button
The Split Items button creates another shipping group relationship instance for this cart item, allowing the same cart item to be associated with more than one shipping group. The following code shows a sample UI binding pattern for this feature:
<!-- ko foreach: cart().items --> <!-- ko if: $parent.canAddShippingGroupRelationship($parent) --> <button class="btn btn-link" data-bind="click: addShippingGroupRelationship"> Split items </button> <!-- /ko --> <!-- /ko -->
It is only possible to split a cart item if the cart item quantity is greater than shippingGroupRelartionships.length
.
Remove Item (X) button
The Remove Item button, shown as an X in the sample UI displayed in this section, removes a shipping group relationship instance. The following code shows a sample UI binding pattern for this feature:
<!-- ko foreach: cart().items --> <!-- ko foreach: shippingGroupRelationships --> <button class="btn btn-sm btn-link" data-bind="click: parents[1].removeShippingGroupRelationship.bind($parent)"> <span class="glyphicon glyphicon-remove"></span> </button> <!-- /ko --> <!-- /ko -->
The removeShippingGroupRelationship
method, used in the click
binding above, is a widget method and not the CartItem.removeShippingGroupRelationship
method. It does, however, delegate to CartItem.removeShippingGroupRelationship
, and also makes a pricing call, provided the split shipping form is complete and valid.
Add Address button
The Add Address button opens an address form where a shopper can save a new address to his profile address book. Once created, the new address will automatically appear in the Shipping Address options in the split shipping form. Apart from the inclusion of an alias
field, no new address management APIs are required for split shipping. Re-using existing address management functionality is wholly sufficient to for this purpose.
The following illustration shows what an Add Address form might look like with fields for name, address, and phone number information. Note the addition of the Alias field.
ShippingGroupsRelationships array validation
The shippingGroupRelationships
property has two predefined custom Knockout validators:
Quantity of item allocated to shipping groups exceeds quantity of item in cart: Checks that the sum of the shipping group quantities is not greater than the cart item quantity.
Cart item quantity not fully allocated to shipping groups: Checks that the sum of the shipping group quantities is not less than the cart item quantity.
The above validators are computed automatically. The illustration below shows an error message that indicates to the shopper when a validation has failed.
To output the error message on screen, use the validationMessage
binding shown below:
<!-- ko foreach: cart().items --> <div class="text-danger" data-bind="validationMessage: shippingGroupRelationships" role="alert"></div> <!-- /ko -->