API

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.

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

• Adding dynamic field

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

Example

• Enabling the submit button all the time

enableFieldValidators

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

Examples

• Conditional validation
• Enable, disable validators
• Switching validators on the same field
• Toggling validators in a master page

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.

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.

getInvalidFields

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

Example

• Activating tab containing invalid field

getMessages

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

Example

• Showing messages in custom area

getOptions

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

getSubmitButton

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

Example

• Using multiple buttons

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.

Examples

• Wizard 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

Example

• Validating fields that depend on each other

removeField

removeField(field*): FormValidation — Remove given field

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

• Adding dynamic field

resetField

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

Example

• Clearing field when clicking the icon

resetForm

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

$(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);

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>

• Field value is changed programmatically
• Play with other plugins
• Terms and conditions agreement validation
• Validating fields that depend on each other
• Validating multiple inputs as one

updateMessage

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

Example

• Disabling date
• Showing custom message returned from server
• Updating validator options
• Validating international phone numbers

updateOption

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

Example

• Updating validator options

updateStatus

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

Example

• Asking fields to be unique
• Comparing times
• Disabling date
• Showing custom message returned from server
• Validating credit card expiration date
• Validating international phone numbers
• Validating percentage values

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.

Examples

• Wizard examples

validateField

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