jquery-form-submit

An ajax form wrapper plugin to ease form submit event.

Dependencies

This project requires the following dependencies: jQuery & PNotify

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/jquery.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/pnotify.js"></script>

Installation

npm

$ npm i @masterei/query-form-submit

cdn

<script src="https://cdn.jsdelivr.net/npm/@masterei/jquery-form-submit/form-submit.min.js"></script>

Usage

Basic Usage

<form id="sample-form" method="POST" data-url="/post.php">
    <input type="text" name="sample_input">
</form>

<script>
    $(function(){
        $('form#sample-form').formSubmit();
    });
</script>

Note:

1. Server must return an object response with a message key value pair.

Eg. ['message' => 'Model has been successfully created.']

2. If no response data is being returned, the plugin will use its default messages.

Option Usage

$('form#sample-form').formSubmit({
    url: '/post.php',
    method: 'POST',
    data: new FormData($(this)),
    done: function (){
        // success callback
    },
    fail: function (){
        // failed callback
    },
    always: function (){
        // execute whether success or fail
    },
    ... etc.
}, 1500); 

// 1500 is the default page reload timeout in ms after a successfully request

Note: You can freely utilize all the ajax shipped configuration and callback functions.

Additional Events

beforeRequest: function (form){
    // triggered before ajax request is started, allows you to modify the form data
    // accept current element as an argument
    
    // Eg. form.find('input[name="sample_input"]').val('new value');
},
afterRequest: function (form){
    // triggered after request is completed, it executes whether success or fail
    // allows you to modify aftermath form data
}

Default Callbacks

done: function (response) {
    options.notify.success(response.message);

    // reload page on post request
    if(isMethodPost()){
        setTimeout(function () {
            window.location.reload();
        }, reload);
    }
},
fail: function (error) {
    options.notify.error(error);
},
always: function (xhr) {
    /**
     * Remove disabled property only if an error occurred
     * in a post request or if action is a patch or put
     */
    if((xhr.status !== undefined && isMethodPost())
        || (isMethodPatch() || isMethodPut())) {
        form.find('button[type="submit"]').prop('disabled', false);
    }
}

Automatic method spoofing for media type request

When dealing with restful api, HTML forms do not support PUT, PATCH, or DELETE actions. So, when defining these methods that are called from an HTML form, you will need to add a hidden _method field to the form.

The good news is, the plugin automatically inject this hidden field when it detects a form attribute enctype="multipart/form-data" included in the form.

Example:

<form id="sample-form" method="POST" data-url="/post.php" enctype="multipart/form-data">
    <input type="file" name="sample_file">
</form>

Tested Compatibility

Screenshot

Changelog

Please see CHANGELOG for more information on what has changed recently.

License

The Internet Systems Consortium License (ISC). Please see License File for more information.

Disclaimer

This plugin was created by the author to address code repetition when developing various projects for its clients. So, use at your own risk.