Skip to content

Checkout Operations

Jump to bottom
Trevor Fayas edited this page Aug 4, 2021 · 2 revisions

Navigation

Initialize

The default JavaScript checkout can be retrieved through var checkout = InitializeEcommerceService('Checkout')

IT IS IMPORTANT THAT THIS SERVICE BE CALLED checkout FOR COMPATABILITY WITH CUSTOM PAYMENT METHOD EXTENSIONS

This allows you to set or update the order information, including addresses, payment options, shipping options, discounts and complete the order.

View-Component

The entire order screen, including all elements can be called in via this View-Component:

@await Component.InvokeAsync("Generic.Ecom.Checkout")

You can customize the various views, outlined in the customization wiki page. We will include individual sections though if you wish to have more control.

Checkout Cart

Along side the order checkout screen is a checkout cart. This is generated through the checkout.getOrder() method which returns the HTML of the checkout cart.

By default, this is called and updated on the update-order event:

document.body.addEventListener("update-order", function (ev) {
    checkout.getOrder().then((html) => { 
        var checkoutTotals = document.querySelector("#checkout-cart");
        if (checkoutTotals) {
            checkoutTotals.innerHTML = html;
        }
    });
});

View

This Checkout cart's view can be modified through overwriting the _CheckoutCart.cshtml.

setCustomer

Sets the current Customer's name and email. By default, this is triggered on the change event of elements with the customer class, creates a set-customer event with checkout.setBillingAddressEvent with the data from the #firstName.form-control, #lastName.form-control and #email.form-control elements, this event then calls the repository to update.

JS Event

you can manually call with

checkout.setCustomer();

Once complete, it will dispatch a CustomEvent to the body of type show-alertwith the message in the detail object that you can react to it.

document.body.addEventListener("show-alert", function (ev) {
    ecommerceClass.showAlert(ev.detail);
});

Template/Views

The setCustomer is integrated within the Generic.Ecom.Checkout view-component.

setBillingAddress

Sets the billing address. By default, this is triggered on the change event of elements with the billing-address class, creates a set-billing-address event with checkout.setBillingAddressEvent using the values from #billingAddress.form-control, #billingAddress2.form-control, #billingCity.form-control, #billingCountry , "#billingState, and #billingZip.form-control. This event then calls the repository to update.

JS Event

you can manually call with

checkout.setBillingAddress(address: Address);

Once complete, it will dispatch a CustomEvent to the body of type show-alertwith the message in the detail object that you can react to it.

document.body.addEventListener("show-alert", function (ev) {
    ecommerceClass.showAlert(ev.detail);
});

Template/Views

The setCustomer is integrated within the Generic.Ecom.Checkout view-component.

getAddresses

There is a helper method checkout.getAddresses(shippingID: string, billingID: string) that will load in existing addresses into the given select elements (by id). This is called by default via:

var addresses = document.body.querySelectorAll("#billingAddresses, #shippingAddresses");
    if (addresses.length > 0) {
        document.body.dispatchEvent(checkout.getAddressesEvent);
    }

setShippingAddress

Sets the shipping address. By default, this is triggered on the change event of elements with the shipping-address class, creates a set-shipping-address event with checkout.setShippingAddressEvent using the values from #shippingAddress.form-control, #shippingAddress2.form-control, #shippingCity.form-control, #shippingCountry , "#shippingState, and #shippingZip.form-control. This event then calls the repository to update.

JS Event

you can manually call with

checkout.setShippingAddress(address: Address);

Once complete, it will dispatch a CustomEvent to the body of type show-alertwith the message in the detail object that you can react to it.

document.body.addEventListener("show-alert", function (ev) {
    ecommerceClass.showAlert(ev.detail);
});

Template/Views

The setCustomer is integrated within the Generic.Ecom.Checkout view-component.

getAddresses

There is a helper method checkout.getAddresses(shippingID: string, billingID: string) that will load in existing addresses into the given select elements (by id). This is called by default via:

var addresses = document.body.querySelectorAll("#billingAddresses, #shippingAddresses");
    if (addresses.length > 0) {
        document.body.dispatchEvent(checkout.getAddressesEvent);
    }

getCountries/getStates

These get the available country or states, used in the Billing/Shipping Addresses. By default, these are called on document load for elements #billingCountry/#shippingCountry and #billingState/#shippingState.

JS Event

you can manually call with

checkout.getCountries(selectId: string);
checkout.getStates(selectId: string, countryId: Number);

By default, if select elements with ids billingCountry or shippingCountry are present, the checkout.getCountries(selectId: string) is called, passing the selector for that element. A change event listener is also added that when changed, it will create a get-states event with checkout.getStatesEvent(selectId: string, countryId: Number), which triggers checkout.getStates(selectId: string, countryId: Number) with the selected country.

This way when a country is selected, the change event triggers the logic to populate the states with the ones found in the selected country.

getShippingOptions/setShippingOptions

Gets and sets the Shipping Option. By default, this is triggered on a select element with id shippingOption.

JS Event

you can manually call with

checkout.getShippingOptions(selectId: string);
checkout.setShippingOptions(id: number);

Calling checkout.getShippingOptions(selectId: string) will fill the Shipping Options.

By default, a change event listener is added to the select box which dispatches on the body a custom event set-shipping-option with checkout.setShippingOptionEvent(result: number). This event then triggers a checkout.setShippingOption(id: number) to set the shipping option. This triggers a show-alert event which can be caught by:

document.body.addEventListener("show-alert", function (ev) {
    ecommerceClass.showAlert(ev.detail);
});

Additionally, by default this event is followed by an update-order event which is used to update the checkout-cart.

Template/Views

The getShippingOption is integrated within the Generic.Ecom.Checkout view-component.

setOrderNote

Sets the order note. By default, this is triggered on an input with class order-note.

JS Event

you can manually call with

checkout.setOrderNote(note: string);

By default, a change event listener is attached to the body, and when an element with class order-note is changed, it dispatches on the body a custom even set-order-note with checkout.setOrderNoteEvent(note: string). This event then triggers a checkout.setOrderNote(note: string) to set the order note. This triggers a show-alert event which can be caught by:

document.body.addEventListener("show-alert", function (ev) {
    ecommerceClass.showAlert(ev.detail);
});

Template/Views

The setOrderNote is integrated within the Generic.Ecom.Checkout view-component.

redeemCoupon/removeCoupon

Sets or removes a coupon code from the order. By default, this is triggered on an input with class order-note.

JS Event

you can manually call with

checkout.redeemCoupon(coupon: string);
checkout.removeCoupon(coupon: string);

For redeeming a coupon, by default, a click event listener is attached to the body, and when an element with class redeem-coupon is clicked, it dispatches on the body a custom even redeem-coupon with checkout.redeemCouponEvent(coupon: string), passing the value of the element input.coupon-code. This event then triggers a checkout.redeemCoupon(coupon: string) to add the coupon. Additional javascript also then clears the coupon input and calls the update-order event to update the cart totals.

For removing a coupon, by default, a click event listener is attached to the body, and when an element with class remove-coupon is clicked, it dispatches on the body a custom event remove-coupon with checkout.removeCouponEvent(coupon: string), passing the value of the sibling element .coupon's innerText. This event then triggers a checkout.removeCoupon(coupon: string) to remove the coupon. Additional javascript also then calls the update-order event to update the cart totals.

Template/Views

The setOrderNote is integrated within the Generic.Ecom.Checkout view-component on the CheckoutCart partial view.

getPaymentOptions/setPaymentOption/getPaymentForm

Sets the available payment options. By default, if a select with id paymentMethods is present it will fill it with the available options.

JS Event

you can manually call with

checkout.getPaymentOptions();
checkout.setPaymentOption(id: number);
checkout.getPaymentForm();

By default, if a select with id paymentMethods is present, it calls checkout.getPaymentOptions() and sets the values of the payment options to the select.

Then a change event is added to the selection, that on change it dispatches on the body a custom event set-payment-option event with checkout.setPaymentOptionEvent(result: number), passing the paymentMethods selected value. This event then triggers a checkout.setPaymentOption(id: number), followed by checkout.getPaymentForm() which returns the selected payment form's HTML. This gets set into the #paymentForm's innerHTML element, also evaluating any script tag with the data-initialize attribute on it.

Template/Views

The getPaymentOption/setPaymentOption is integrated within the Generic.Ecom.Checkout view-component. The payment forms are a separate module and customization.

createOrder

Creates the order before processing payment. Usually called from the payment option.

JS Event

you can manually call with

checkout.createOrder();

By default, simply creates the order based on what has already been set. You may customize to include custom body / headers if you wish. It returns a JSON object of the order, with minimum:

{
   orderFailed: boolean,
   message: string,
   orderGUID: string
   // Can be customized to include more

If the order is successfully created, it sets the orderGUID to the checkout and then dispatches the custom event payment which by default calls the checkout.payment if there is a valid orderGUID and the payment method has been set. The checkout.payment is added by the custom Payment form.

Successful payment should dispatch the custom event payment-result with checkout.getPaymentResultEvent(result: object) which can then call either displays an alert message or redirects to thank you through checkout.redirectToThankYouUrl(url: string). The getPaymentResultEvent should contains an object with minimum:

{
	detail: {
		paymentSuccessful: boolean,
		message: string
	}

The redirection URL is by default a data-thankyouurl attribute on the #checkout-cart element.

Clone this wiki locally