Sequence plugin

Stop performing remaining validators if there is a validator that the field does not pass

Usage

By default, when a field is being validated, all validators for a field will be executed. Let's take a look at a simple signing up form that its username field has to pass all of the following validator rules:


FormValidation.formValidation(document.getElementById('signupForm'), {
    fields: {
        username: {
            validators: {
                notEmpty: {
                    message: 'The username is required'
                },
                callback: {
                    message: 'This username is not allowed',
                    callback: function(input) {
                        // Do not accept the username starting with "admin"
                        return !input.value.startsWith('admin');
                    }
                },
                stringLength: {
                    min: 6,
                    max: 30,
                    message: 'The username must be more than 6 and less than 30 characters long'
                },
                regexp: {
                    regexp: /^[a-zA-Z0-9_]+$/,
                    message: 'The username can only consist of alphabetical, number and underscore'
                },
                remote: {
                    message: 'The username is already taken',
                    method: 'GET',
                    url: '/path/to/your/back-end/',
                },
            },
        },
    },
    plugins: {
        ...
    },
});

After each key stroke, all validators will perform their jobs. Some of them might be expensive tasks such as checking the validity in the server side via the remote validator.

It is better if the expensive validator is performed at the end when the field passes all other remaining validators. It reduces the number of server side requests (for example, it will not hit the database server to check if an username is taken). Also, our users don't have to wait for these validators to run and return the results. It brings a better user experience.

The Sequence plugin is handy for this requirement. It will stop performing a given validator if the field does not pass the previous validator.

The following piece of code is the starting point to use the Sequence plugin:




    


    
...
document.addEventListener('DOMContentLoaded', function(e) { FormValidation.formValidation( document.getElementById('demoForm'), { fields: { ... }, plugins: { sequence: new FormValidation.plugins.Sequence({ enabled: true, }), ... }, } ); });

The sample code above assumes that the FormValidation files are placed inside the vendors directory. You might need to change the path depending on where you place them on the server.

Options

Option Type Description
enabled Boolean or Object It can be
  • true (default value)
  • false
  • or an object indicating a given field will use the behaviour. For example:
    
    enabled: {
        username: true,
        // All the validators for password field 
        // will be performed as usual
        password: false,
    },
    
  • Basic example

    In the following form, all validators are performed in sequential order. A validator will not be executed if the field doesn't pass the previous validator.

    By putting the remote validator at the end, we only send a request to server to check if the username is taken if it passes all other validators.

    For testing purpose, the demo always answers that the username is already taken no matter what you input.

    Changelog

    • v1.1.0: First release. It means that the Sequence plugin requires FormValidation v1.1.0 or newer.