Ajax for Express Forms - Light Edition

Using Javascript Events & Callbacks

Ajax for Express triggers 2 JavaScript Events and lets you attach a callback to form submission.

For instance, say your form is divided into tabs, and you want to trigger the first tab to show the success message after the form is successfully submitted.

Let's see how to use both events and callbacks.

Events

There are 2 events available:

  1. ajax-form-loaded when the form is loaded and ready
  2. ajax-form-submitted when the form is submitted

Both events are triggered on the form DOM object itself.

For instance, you could listen to an event like this:

(function () {
    // let's grab the form block bID
    const knownBID = <?php echo $bID; ?>;
    // Let's use the bID to grab the form JQuery object
    var form = $("form[action*='submit/" + knownBID + "']");

    if (form.length) {
        // Listening to the ajax-form-loaded event
        form.on('ajax-form-loaded', function(evt) {
            // The evt object contains information listed below
        });
    }
})();

 

Both event objects include pieces of information that could be useful:

  • Event: ajax-form-loaded
    • Event.pluginObject => the plugin object itself, from which you can access the setForm() method as well as the settings for the current form.
  • Event: ajax-form-submitted
    • Event.success => Boolean
    • Event.action => 4 possible values:
      • an empty string (when Event.success is FALSE) meaning there was an error
      • "message" (Event.success is TRUE) when the form was sent successfully and we're showing a success message
      • "redirect" (Event.success is TRUE) when the form was sent successfully and we're redirecting to a success page
      • "confirmation" (Event.success is TRUE) when the form is waiting for a confirmation from the user before sending

Here's an example of using the ajax-form-submitted event to log a message:

(function() {
    const knownBID = <?php echo $bID; ?> ;
    var form = $("form[action*='submit/" + knownBID + "']");

    if (form.length) {
        form.on('ajax-form-submitted', function(evt) {
            var resultMsg = evt.success ? "success" : "failure";
            console.log("the operation was a " + resultMsg);

            switch (evt.action) {
                case "message":
                    console.log("showing you a success message");
                    break;
                case "redirect":
                    console.log("redirecting soon");
                    break;
                case "confirmation":
                    console.log("waiting for confirmation");
                    break;
                default:
                    break;
            }
        });
    }
})();

Callbacks

Occasionally you might want to trigger a callback after the form is submitted instead of relying on events. The function setForm() we've been using to reset our forms when using other scripts allows you to do just that.

The callback function will send you back 3 parameters:

  • the first parameter is a boolean that indicates if the operation was successful or not
  • the second parameter is a string that indicates which operation it was. It can have 1 of 4 values:
    • an empty string (when the first parameter is FALSE) meaning there was an error
    • "message" (the first parameter is TRUE) when the form was sent successfully and we're showing a success message
    • "redirect" (the first parameter is TRUE) when the form was sent successfully and we're redirecting to a success page
    • "confirmation" (the first parameter is TRUE) when the form is waiting for a confirmation from the user before sending
  • the third parameter is the form itself as a DOM object
The best way to set up the callback is to use the ajax-form-loaded event.

So here's an example showing how to use all this. You will notice, in this example, I only use one form with a known bID but you can also grab all the forms in a loop and do as we did when resetting forms.
 
(function() {
    var callback = function(success, action, formObject) {
        var resultMsg = success ? "success" : "failure";

        console.log("the operation was a " + resultMsg);

        switch (action) {
            case "message":
                console.log("showing you a success message");
                break;
            case "redirect":
                console.log("redirecting soon");
                break;
            case "confirmation":
                console.log("waiting for confirmation");
                break;
            default:
                break;
        }
    };

    const knownBID = <?php echo $bID; ?> ;
    var form = $("form[action*='submit/" + knownBID + "']");

    if (form.length) {
        form.on('ajax-form-loaded', function(evt) {
            // grabbing the plugin Object from the event
            var pluginObject = evt.pluginObject;
            if (pluginObject) {
                // using the plugin object to call the setForm() method
                pluginObject.setForm(false, callback);
            }
        });
    }
})();

You will notice that I set the first parameter in the setForm() function to FALSE since I am not providing a DOM object myself.