AJAX Requests (JavaScript API)

#Introduction

Snowboard provides core AJAX functionality via the Request Snowboard plugin. The Request plugin provides powerful flexibility and reusability in making AJAX Requests with the Backend functionality in Winter. It can be loaded by adding the following tag into your CMS Theme's page or layout:

{% snowboard request %}

And called using the following code in your JavaScript:

Snowboard.request('#element', 'onAjax', {});

The base Request plugin uses the Fetch API provided in most modern browsers to execute AJAX requests from the frontend to the backend in Winter.

NOTE: If you would like to replace any part of the functionality of the base Request plugin then you can write a custom Snowboard Plugin that extends and overrides the base Request plugin to customize it as desired.

The request method takes three parameters:

#Request workflow

AJAX requests made through the Request class go through the following process:

• The request is initialized and validated with the given element and options.
• If browserValidate is enabled and the AJAX request is done with a form, browser-side validation occurs. If this fails, the request is cancelled.
• If confirm is specified, a confirmation is presented to the user. If they cancel, the request is cancelled.
• The data provided to the Request, along with any form data if applicable, will be compiled.
• The AJAX request is sent to the Backend context using the given handler.
• A response is received from the Backend context and processed, from here, one of three things happen:
  • If the response is successful, then any partials that are instructed to be updated will be updated at this point.
  • If the response is unsuccessful due to a validation error, then a validation message will be shown and the failing fields will be highlighted.
  • If the response is unsuccessful due to any other error, then an error message will be shown.
• The request is then complete.

#Available options

All options below are optional.

The following callbacks may also be specified in the options parameter. All callbacks expect a function to be provided. The this keyword inside all callbacks will be assigned the Request instance that represents the current AJAX request.

Finally, the following option parameters define override functionality for various actions that the Request instance may take during the processing of a response. As with the callback methods, these must be provided as a function.

#Global events

The Request class fires several global events which can be used by plugins to augment or override the functionality of the Request class. Snowboard plugins can be configured to listen to, and act upon, these events by using the listen() method to direct the event to a method with the plugin class.

class HandleFlash extends Snowboard.Singleton
{
    /**
     * Defines listeners for global events.
     *
     * @returns {Object}
     */
    listens() {
        return {
            // when the "ajaxFlashMessages" event is called, run the "doFlashMessage" method in this class
            ajaxFlashMessages: 'doFlashMessages',
        };
    }

    doFlashMessages(messages) {
        Object.entries(messages).forEach((entry) => {
            const [cssClass, message] = entry;

            showFlash(message, cssClass);
        });
    }
}

Some events are called as Promise events, which means that your listener must itself return a Promise this is either resolved or rejected.

class ConfirmEverything extends Snowboard.Singleton
{
    /**
     * Defines listeners for global events.
     *
     * @returns {Object}
     */
    listens() {
        return {
            // when the "ajaxConfirmMessage" event is called, run the "confirm" method in this class
            ajaxConfirmMessage: 'confirm',
        };
    }

    // Confirm all confirmation messages
    confirm() {
        return Promise.resolve(true);
    }
}

The following events are called during the Request process:

#Element events

In addition to global events, local events are fired on elements that trigger an AJAX request. These events are treated as DOM events and thus can be listened to by normal DOM event listeners or your framework of choice. The Request class will inject properties in the event depending on the type of event and the event.request property will always be the Request instance.

const element = document.getElementById('my-button');
element.addEventListener('ajaxAlways', (event) => {
    console.log(event.request); // The Request instance
    console.log(event.responseData); // The raw response data as an object
    console.log(event.responseError); // An error object if the response failed
});

In most cases, you can cancel the event, and thus the Request, by adding event.preventDefault() to your callback.

const element = document.getElementById('my-button');
element.addEventListener('ajaxSetup', (event) => {
    // Never process a request for this element
    event.preventDefault();
});

The following events are called during the Request process directly on the element that triggered the request:

#Usage examples

Make a simple request to an AJAX handler without specifying a triggering element.

Snowboard.request(null, 'onAjax');

Request a confirmation before submitting a form, and redirect them to a success page.

Snowboard.request('form', 'onSubmit', {
    confirm: 'Are you sure you wish to submit this data?',
    redirect: '/form/success',
});

Run a calculation handler and inject some data from the page, then update the total.

Snowboard.request('#calculate', 'onCalculate', {
    data: {
        firstValue: document.getElementById('first-value').value,
        secondValue: document.getElementById('second-value').value,
    },
    update: {
        totalResult: '.total-result'
    },
});

Run a calculation handler and show a success message when calculated.

Snowboard.request('#calculate', 'onCalculate', {
    data: {
        firstValue: document.getElementById('first-value').value,
        secondValue: document.getElementById('second-value').value,
    },
    success: (data) => {
        const total = data.total;
        alert('The answer is ' + total);
    },
});

Prompt a user to confirm a redirect.

Snowboard.request('form', 'onSubmit', {
    handleRedirectResponse: (url) => {
        if (confirm('Are you sure you wish to go to this URL: ' + url)) {
            window.location.assign(url);
        } else {
            alert('Redirect cancelled');
        }
    },
});

Track when an element is updated from an AJAX request.

const element = document.getElementById('updated-element');
element.addEventListener('ajaxUpdate', (event) => {
    console.log('The "updated-element" event was updated with the following content:', event.content);
});

Disable file uploads globally from AJAX requests by modifying the Request instance.

// In your own Snowboard plugin
class DisableFileUploads extends Snowboard.Singleton
{
    listens() {
        return {
            ajaxSetup: 'stopFileUploads',
        };
    }

    stopFileUploads(request) {
        request.options.files = false;
    }
}

#Extending or replacing the Request class

As part of making Snowboard an extensible and flexible platform, developers have the option to extend, or replace entirely, the base Request class. This allows developers to use their own preferred platforms and frameworks for executing the AJAX functionality, partial updates, and much more.

For example, if a developer wanted to use the Axios library to execute AJAX requests, as opposed to the in-built Fetch API, one could do this by creating their own Snowboard plugin and extending the Request class, replacing the doAjax() method in their own class:

const axios = require('axios');

class AxiosRequest extends Request
{
    doAjax() {
        // Allow plugins to cancel the AJAX request before sending
        if (this.snowboard.globalEvent('ajaxBeforeSend', this) === false) {
            return Promise.resolve({
                cancelled: true,
            });
        }

        const ajaxPromise = axios({
            method: 'post',
            url: this.url,
            headers: this.headers,
            data: this.data,
        });

        this.snowboard.globalEvent('ajaxStart', ajaxPromise, this);

        if (this.element) {
            const event = new Event('ajaxPromise');
            event.promise = ajaxPromise;
            this.element.dispatchEvent(event);
        }

        return ajaxPromise;
    }
}

You could then either replace the request plugin with this class, or alias it as something else:

Snowboard.removePlugin('request');
Snowboard.addPlugin('request', AxiosRequest);

// Or run it as an alias
Snowboard.addPlugin('axios', AxiosRequest);
// And call it thusly
Snowboard.axios('#my-element', 'onSubmit');

For more information on the best practices with setting up a Snowboard plugin, view the Plugin Development documentation.