FormValidation v0.8.1 is released, supports Bootstrap 4 alpha 3

API

Collection of public methods that help you do additional jobs

Usage

After initializing the form with the plugin using $(form).formValidation(options), there are two ways to call the plugin method:

// Get plugin instance
var formValidation = $(form).data('formValidation');

// and then call method
formValidation.methodName(parameters)

or:

$(form).formValidation(methodName, parameters);

The first way mostly returns the FormValidation instance, meanwhile the second one always returns the jQuery object representing the form.

So, it's possible to chain methods as below:

// The first way
$(form)
    .data('formValidation')
    .updateStatus('birthday', 'NOT_VALIDATED')
    .validateField('birthday');

// The second one
$(form)
    .formValidation('updateStatus', 'birthday', 'NOT_VALIDATED')
    .formValidation('validateField', 'birthday');

Below is the list of public methods provided by the plugin.

The methods use the same format as following:

methodName(requiredParameter*, optionalParameter, ...): Type of return value — The purpose of method

addField

addField(field*, options): FormValidation — Add a new field.

Parameter Type Description
field String|jQuery The field name or field element
options Object The field options.
If it is not defined, the options are merged by:
  • Options which are parsed from HTML attributes of field
  • The current options which are set when calling the plugin

If you want to do additional task after adding new field, then trigger the added.field.fv event:

$(document).ready(function() {
    $(form)
        .formValidation(options)
        .on('added.field.fv', function(e, data) {
            // $(e.target)  --> The form instance
            // $(e.target).data('formValidation')
            //              --> The FormValidation instance

            // data.field   --> The field name
            // data.element --> The new field element
            // data.options --> The new field options

            // Do something ...
        });
});
Example

defaultSubmit

defaultSubmit(): FormValidation — Submit the form using default submission.

It also does not perform any validations when submitting the form. It might be used when you want to submit the form right inside the custom submit handler.

destroy

destroy() — Destroy the plugin.

It will remove all error messages, feedback icons as well as turning off the events created by the plugin.

disableSubmitButtons

disableSubmitButtons(disabled): FormValidation — Disable or enable the submit buttons

Parameter Type Description
disabled Boolean Can be true or false
Example

enableFieldValidators

enableFieldValidators(field*, enabled*, validator): FormValidation — Enable, disable validators to given field

Parameter Type Description
field String The field name
enabled Boolean If true, enable field validators. If false, disable field validators
validator String The validator name. If it is not set, all field validators will be enabled or disabled
Examples

getDynamicOption

getDynamicOption(field*, option*): String — Returns the option value which can be set dynamically.

For example, the zipCode validator has country option that can be changed dynamically a select element.

Parameter Type Description
field String|jQuery The field name or element
option String The dynamic option

getFieldElements

getFieldElements(field): jQuery[] — Retrieve the field elements by given name.
Returns array of jQuery element representing the field, or null if the fields are not found.

Parameter Type Description
field String The field name

getInvalidFields

getInvalidFields(): jQuery[] — Returns the list of invalid fields.

Example

getMessages

getMessages(field, validator): String[] — Get the error messages.

Parameter Type Description
field String|jQuery The field name or field element
If the field is not defined, the method returns all error messages of all fields
validator String The name of validator
If the validator is not defined, the method returns error messages of all validators.
Example

getOptions

getOptions(field, validator, option): String|Object — Get the field options.

Parameter Type Description
field String|jQuery The field name or field element
If the field is not defined, the method returns the form options.
validator String The name of validator
If the validator is not defined, the method returns all field options.
option String The option name
If it is not defined, the method returns options of given validator

getSubmitButton

getSubmitButton(): jQuery — Returns a jQuery element presenting the clicked submit button. Returns null if the submit button isn't clicked.

Example

isValid

isValid(): Boolean — Check the form validity. It can take one of three values:

  • true if all fields are valid
  • false if there is one invalid field
  • null if there is at least one field which is not validated yet or being validated

Ensure that the validate() method is already called before calling this one.

isValidContainer

isValidContainer(container*): Boolean — It can take one of three values:

  • true if all fields belonging to the container are valid
  • false if all fields belonging to the container are already validated and there is at least one invalid field
  • null if the container consists of at least one field that isn't validated yet

Using with the validateContainer(container) method, these methods are useful when working with a wizard-like such as tabs, collapsible panels.

Parameter Type Description
container String|jQuery The container selector or container element
Examples

isValidField

isValidField(field*): Boolean — Check whether the field is valid or not. It can take one of three values:

  • true if the field passes all validators
  • false if the field doesn't pass any validator
  • null if there is at least one validator which isn't validated yet or being validated
Parameter Type Description
field String|jQuery The field name or field element
Example

removeField

removeField(field*): FormValidation — Remove given field

Parameter Type Description
field String|jQuery The field name or field element

By triggering the removed.field.fv event, you can perform additional task after removing given field:

$(document).ready(function() {
    $(form)
        .formValidation(options)
        .on('removed.field.fv', function(e, data) {
            // $(e.target)  --> The form instance
            // $(e.target).data('formValidation')
            //              --> The FormValidation instance

            // data.field   --> The field name
            // data.element --> The new field element

            // Do something ...
        });
});
Example

resetField

resetField(field*, resetValue): FormValidation — Reset given field. It hides the error messages and feedback icons.

Parameter Type Description
field String|jQuery The field name or field element
resetValue Boolean If true, the method resets field value to empty or remove checked/selected attribute (for radio and checkbox).
Example

resetForm

resetForm(resetFormData): FormValidation — Reset form. It hides all error elements and feedback icons. All the fields are marked as not validated yet.

Parameter Type Description
resetFormData Boolean If true, the method resets the fields which have validator rules.
$(form).formValidation(options);
$(form).data('formValidation').resetForm();

revalidateField

revalidateField(field*): FormValidation — Revalidate given field.

It's used when you need to revalidate the field which its value is updated by other plugin.

By default, the plugin doesn't re-validate a field once it is already validated and marked as a valid one. When using with other plugins, the field value is changed and therefore need to be re-validated.

Behind the scenes, the method is equivalent to:

$(form).data('formValidation')
    .updateStatus(field, 'NOT_VALIDATED')
    .validateField(field);

// Or
$(form).formValidation('updateStatus', field, 'NOT_VALIDATED')
       .formValidation('validateField', field);
Parameter Type Description
field String|jQuery The field name or field element
Example

The following example describes how to re-validate a field which uses with Boostrap Datetime Picker:

<link href="/vendor/bootstrap-datetimepicker/css/bootstrap-datetimepicker.min.css" rel="stylesheet" />
<style type="text/css">
#datetimeForm .has-feedback .form-control-feedback {
    top: 0;
    right: -15px;
}
</style>

<script src="//oss.maxcdn.com/momentjs/2.8.2/moment.min.js"></script>
<script src="/vendor/bootstrap-datetimepicker/js/bootstrap-datetimepicker.min.js"></script>

<form id="datetimeForm" class="form-horizontal">
    <div class="form-group">
        <label class="col-xs-3 control-label">DateTime Picker</label>
        <div class="col-xs-5">
            <div class="input-group date" id="datetimePicker">
                <input type="text" class="form-control" name="datetimePicker" />
                <span class="input-group-addon">
                    <span class="glyphicon glyphicon-calendar"></span>
                </span>
            </div>
        </div>
    </div>
</form>

<script>
$(document).ready(function() {
    $('#datetimePicker').datetimepicker();

    $('#datetimeForm').formValidation({
        framework: 'bootstrap',
        icon: {
            valid: 'glyphicon glyphicon-ok',
            invalid: 'glyphicon glyphicon-remove',
            validating: 'glyphicon glyphicon-refresh'
        },
        fields: {
            datetimePicker: {
                validators: {
                    notEmpty: {
                        message: 'The date is required and cannot be empty'
                    },
                    date: {
                        format: 'MM/DD/YYYY h:m A'
                    }
                }
            }
        }
    });

    $('#datetimePicker')
        .on('dp.change dp.show', function (e) {
            // Revalidate the date when user change it
            $('#datetimeForm').formValidation('revalidateField', 'datetimePicker');
        });
});
</script>

updateMessage

updateMessage(field*, validator*, message*): FormValidation — Update the error message.

Parameter Type Description
field String|jQuery The field name or field element
validator String The validator name
message String The error message
Example

updateOption

updateOption(field*, validator*, option*, value*): FormValidation — Update the option of a specific validator.

Parameter Type Description
field String|jQuery The field name or field element
validator String The validator name
option String The option name
value String The option value
Example

updateStatus

updateStatus(field*, status*, validator): FormValidation — Update validator result for given field

Parameter Type Description
field String|jQuery The field name or field element
status String Can be NOT_VALIDATED, VALIDATING, INVALID or VALID
validator String The validator name. If null, the method updates validity result for all validators
Example

validate

validate(): FormValidation — Validate form manually. It is useful when you want to validate form by clicking a button or a link instead of a submit buttons.

$(form).formValidation(options).formValidation('validate');

// or
$(form).formValidation(options);
$(form).data('formValidation').validate();

validateContainer

validateContainer(container*): FormValidation — Validate given container.

Using with the isValidContainer(container) method, these methods are useful when working with a wizard-like such as tabs, collapsible panels.

Parameter Type Description
container String|jQuery The container selector or element
Examples

validateField

validateField(field*): FormValidation — Validate given field.

Parameter Type Description
field String|jQuery The field name or field element