programer.tips, another cool thing from @nghuuphuoc!

Developing

It's quite easy to develop new validator

Improve it on Github

Writing new validator

A validator has to follow the syntax:

(function($) {
    $.fn.bootstrapValidator.validators.validatorName = {
        /**
         * @param {BootstrapValidator} validator The validator plugin instance
         * @param {jQuery} $field The jQuery object represents the field element
         * @param {Object} options The validator options
         * @returns {Boolean}
         */
        validate: function(validator, $field, options) {
            // You can get the field value
            // var value = $field.val();
            //
            // Perform validating
            // ...
            //
            // return true if the field value is valid
            // otherwise return false
        }
    };
}(window.jQuery));

The validator must implement validate() method that returns true if the field is valid, or false otherwise.

validatorName is the validator name. Since the validators are distinct by the names, validatorName has to be different with built-in validators.

To apply the validator to particular field:

$(form).bootstrapValidator({
    fields: {
        fieldName: {
            // Replace validatorName with the name of validator
            // validatorOptions will be passed as third parameter of the
            // validate(validator, $field, options) method
            validatorName: validatorOptions
        }
    }
});
To see how built-in validators are developed, you can look at their sources located at the src/js/validator directory.

Dynamic message

If you want to set dynamic error message, the validator must return an object that consists of valid and message members:

(function($) {
    $.fn.bootstrapValidator.validators.validatorName = {
        validate: function(validator, $field, options) {
            // ... Do your logic checking
            if (...) {
                return {
                    valid: true,    // or false
                    message: 'The error message'
                }
            }

            return {
                valid: false,       // or true
                message: 'Other error message'
            }
        }
    };
}(window.jQuery));

Example

The following example illustrates how to develop a simple validator which validate a password. The validator will treat a password as valid, if it satisfies all the conditions below:

  • Must be more than 8 characters long
  • Must contain at least one upper case character
  • Must contain at least one lower case character
  • Must contain at least one digit

In fact, you can add more conditions to make a secure password.

(function($) {
    $.fn.bootstrapValidator.validators.password = {
        validate: function(validator, $field, options) {
            var value = $field.val();
            if (value === '') {
                return true;
            }

            // Check the password strength
            if (value.length < 8) {
                return false;
            }

            // The password doesn't contain any uppercase character
            if (value === value.toLowerCase()) {
                return false;
            }

            // The password doesn't contain any uppercase character
            if (value === value.toUpperCase()) {
                return false;
            }

            // The password doesn't contain any digit
            if (value.search(/[0-9]/) < 0) {
                return false;
            }

            return true;
        }
    };
}(window.jQuery));
<form id="passwordForm" class="form-horizontal">
    <div class="form-group">
        <label class="col-sm-3 control-label">Password</label>
        <div class="col-sm-5">
            <input type="password" class="form-control" name="pwd" />
        </div>
    </div>

    <div class="form-group">
        <div class="col-sm-5 col-sm-offset-3">
            <button type="submit" class="btn btn-default">Validate</button>
        </div>
    </div>
</form>
$(document).ready(function() {
    $.fn.bootstrapValidator.validators.password = {
        validate: function(validator, $field, options) {
            var value = $field.val();
            if (value === '') {
                return true;
            }

            if (value.length < 8) {
                return false;
            }
            if (value === value.toLowerCase()) {
                return false;
            }
            if (value === value.toUpperCase()) {
                return false;
            }
            if (value.search(/[0-9]/) < 0) {
                return false;
            }

            return true;
        }
    };

    $('#passwordForm').bootstrapValidator({
        feedbackIcons: {
            valid: 'glyphicon glyphicon-ok',
            invalid: 'glyphicon glyphicon-remove',
            validating: 'glyphicon glyphicon-refresh'
        },
        fields: {
            pwd: {
                validators: {
                    notEmpty: {
                        message: 'The password is required and cannot be empty'
                    },
                    password: {
                        message: 'The password is not valid'
                    }
                }
            }
        }
    });
});

Basically, the validator works fine. It returns false if the password doesn't satisfy any of conditions we define. The limitation here is that the user don't know which condition the password doesn't pass. It informs the same The password is not valid message in all cases.

Using dynamic message ability, it's easy to make the validator more friendly.

(function($) {
    $.fn.bootstrapValidator.validators.securePassword = {
        validate: function(validator, $field, options) {
            var value = $field.val();
            if (value === '') {
                return true;
            }

            // Check the password strength
            if (value.length < 8) {
                return {
                    valid: false,
                    message: 'The password must be more than 8 characters long'
                };
            }

            // The password doesn't contain any uppercase character
            if (value === value.toLowerCase()) {
                return {
                    valid: false,
                    message: 'The password must contain at least one upper case character'
                }
            }

            // The password doesn't contain any uppercase character
            if (value === value.toUpperCase()) {
                return {
                    valid: false,
                    message: 'The password must contain at least one lower case character'
                }
            }

            // The password doesn't contain any digit
            if (value.search(/[0-9]/) < 0) {
                return {
                    valid: false,
                    message: 'The password must contain at least one digit'
                }
            }

            return true;
        }
    };
}(window.jQuery));

Now, the form shows exactly condition that we want the password to satisfy.

<form id="securePasswordForm" class="form-horizontal">
    <div class="form-group">
        <label class="col-sm-3 control-label">Password</label>
        <div class="col-sm-5">
            <input type="password" class="form-control" name="pwd" />
        </div>
    </div>

    <div class="form-group">
        <div class="col-sm-5 col-sm-offset-3">
            <button type="submit" class="btn btn-default">Validate</button>
        </div>
    </div>
</form>
$(document).ready(function() {
    $.fn.bootstrapValidator.validators.securePassword = {
        validate: function(validator, $field, options) {
            var value = $field.val();
            if (value === '') {
                return true;
            }

            // Check the password strength
            if (value.length < 8) {
                return {
                    valid: false,
                    message: 'The password must be more than 8 characters long'
                };
            }

            // The password doesn't contain any uppercase character
            if (value === value.toLowerCase()) {
                return {
                    valid: false,
                    message: 'The password must contain at least one upper case character'
                }
            }

            // The password doesn't contain any uppercase character
            if (value === value.toUpperCase()) {
                return {
                    valid: false,
                    message: 'The password must contain at least one lower case character'
                }
            }

            // The password doesn't contain any digit
            if (value.search(/[0-9]/) < 0) {
                return {
                    valid: false,
                    message: 'The password must contain at least one digit'
                }
            }

            return true;
        }
    };

    $('#securePasswordForm').bootstrapValidator({
        feedbackIcons: {
            valid: 'glyphicon glyphicon-ok',
            invalid: 'glyphicon glyphicon-remove',
            validating: 'glyphicon glyphicon-refresh'
        },
        fields: {
            pwd: {
                validators: {
                    notEmpty: {
                        message: 'The password is required and cannot be empty'
                    },
                    securePassword: {
                        message: 'The password is not valid'
                    }
                }
            }
        }
    });
});

Building

BootstrapValidator uses grunt to simplify building process.

From the BootstrapValidator root directory, install dependencies:

$ npm install

Then, uses grunt to build:

$ grunt

If you want grunt to generate scripts whenever the original scripts (located in src) change, use the following command:

$ grunt watch

The generated scripts (including source and compressed versions) are placed inside the dist directory.

Contributing

If you develop new validator which might be useful for other one, please contribute it to the project.

It can be done via 3 steps:

  • Fork the project
  • Develop new validator, suggest new feature or fix a bug
  • Pull a new request

All pull requests are welcome .