Updating single page checkout with AJAX requests

In a single-page checkout, all sections are located on the same page. Content supplied in one section of the checkout affects its other sections too, so the contents of each section should be updated whenever changes are made to other sections. For example, the delivery address affects the available shipping methods, so shipping methods should be updated whenever the postal code or destination country is changed.

Instead of updating the entire page whenever the customer makes any changes, the changes should be submitted as an AJAX request with JavaScript to the server and all sections dependent on the submitted data should be retrieved as a separate AJAX request.

The single-page checkout jQuery-plugin

To facilitate the update of single-page checkout sections, we have developed a jQuery plugin that monitors the data submitted to the form and updates the checkout's sections on the fly, depending on what section has been filled.

For the plugin to work, jQuery must be loaded and all sections required for a single-page checkout must be located within HTML elements whose id matches the tag name, for example:

<fieldset class=”TagWrapper” id=”CheckoutShippingAddress”>
    {CheckoutShippingAddress(
        mode: ’form’,
        ajax: ’true’
    )}
</fieldset>

If you don't want to make any changes to the plugin's settings, initialize it as follows:

$(’.TagWrapper’).mcfOnepageCheckout();

In the example, all tags of the checkout's form should be surrounded by, for example, the <div> or <fieldset> elements with the class name 'TagWrapper', whereby the checkout plugin examines the changes within the element and sends the section contained by that element to the server as needed.

The plugin sends information to servers in the following situations:

1. After the user has modified something in the form and the focus moves away from that section (for example, the customer information has been edited and the user moves to edit the shipping address or clicks outside the form)
2. When the user has not edited the form for a while
3. When the shipping country has been changed in customer information or deliveryaddress
4. When the shipping or payment method is changed

Once the data has been sent, the plugin automatically retrieves all sections that depend on the data and writes them to elements whose id is the name of the tag dependent on the data.

For example, when the customer updates the delivery address, the plugin looks for an element whose id is 'CheckoutShippingMethods', and rewrites the selection of shipping methods in that element.

Plugin settings

The checkout plugin contains a number of useful events and settings with which you can e.g. add to the theme a loading animation that is displayed when checkout sections are being updated.

Below you can see a simplified example of how a loading animation is implemented in the old default theme using the plugin:

$(’.TagWrapper’).mcfOnepageCheckout({
    // Run when fetching dependencies starts
    get_start: function(el) {
        // Adds an element for a loading animation
        el.append(’<div class=”CheckoutLoader”></div>’);
    },

    // Run when data is sent to the server
    post_start: function(el) {
        // Adds an element for a loading animation
        el.append(’<div class=”CheckoutLoader”></div>’);
    },

    // Run when a single data transmission is completed
    post_success: function(el) {
        // The loading animation is removed
        $(’.CheckoutLoader’, el).remove();
    },

    // Run when a single dependency is loaded
    get_success: function(el, response) {
        // The loading animation is removed
        $(’.CheckoutLoader’, el).remove();
    },

    // Run after all ajax requests have been completed
    complete: function(el) {}
});

In the events presented in the example, it's also easy to add e.g. other jQuery plugins to different checkout sections if such plugins have been used in the store's form.

See also more detailed information about the plugin settings.

Checkout notifications

It is also necessary to display notifications at checkout, e.g. when customer data is incomplete. You can print notifications at a single-page checkout in two ways:

<fieldset class=”TagWrapper” id=”CheckoutBillingAddress”>
    <div class=”Notification Error”>
        <p>Please fill in all the fields. We need your address and contact information for order delivery and related inquires.</p>
    </div>
    ...
</fieldset>

$.ajax({
    type: ’POST’,
    url: ’/checkout/’,
    data: {
        response_type: ’json’
    },
    cache: false,
    success: function(response) {}
});

The example works both when sending (POST) and retrieving (GET) checkout data. In such case, the server returns the following JSON object:

{
    ”content”:
        ”<input type=\”hidden\” name=\”response_tag\” value=\”CheckoutBillingAddress(mode:’form’,ajax:’true’,action:’customer_information’)\” />”,
    ”notifications”:
        ”<div class=\”Notification Error\”><p>Please fill in all the fields. We need your address and contact information for order delivery and related inquires.</p></div>”
}

The "content" section of the object contains markup that is usually retrieved directly as a response provided that it is retrieved without any notifications. The second section of the object is ”notifications” that contains the notification markup which can be easily separated and printed in a desired location.