Download

Download bValidator from here (currently v1.0.5)

Or install with Bower:

$ bower install bvalidator

Or install with npm:

$ npm install bvalidator

Git repository: https://github.com/bmauser/bvalidator.git

Include JavaScript

To use bValidator you need to include jQuery, jquery.bvalidator.min.js and .js and .css files for the theme you want to use.

<script src="jquery.min.js"></script>
<script src="jquery.bvalidator.min.js"></script>

// for choosen theme
<script src="themes/presenters/default.min.js"></script>
<script src="themes/gray/gray.js"></script>

Include CSS for the theme

<link href="themes/gray/gray.css" rel="stylesheet" />

HTML

The page should contain inputs you want to validate:

<form data-bvalidator-validate>
    Email: <input type="text" data-bvalidator="required,email"/>
    Url: <input type="text" data-bvalidator="url"/>
</form>

Add data-bvalidator-validate attribute to the <form> you want to validate to bind bValidator to the form.
To each you want to validate, add data-bvalidator attribute with validation functions to invoke for the field.

With JavaScript

You can also bind bValidator to the form with JavaScript (in that case data-bvalidator-validate attribute is not needed on the <form>). You can use jQuery's $(document).ready to execute the script as soon as the web page has been loaded:

<script type="text/javascript">
    $(document).ready(function () {
        $('form').bValidator();
    });
</script>

Upgrade form version 0.x

bValidator 1.x is not backward compatible with version 0.x. Basic features are similar to those in 0.x, but I have introduced a lot of changes into 1.x without backward compatibility in mind. Please read this docs before upgrade.

bValidator first checks default options. You can change default options like this:

<script type="text/javascript">
    bValidator.defaultOptions.singleError = true;
    bValidator.defaultOptions.useTheme = 'red';
</script>

You can also set options by passing an object with options to the constructor function:

<script type="text/javascript">

    var options = {
        singleError: true,
        useTheme:    'orange'
    };

    $('#myform').bValidator(options);

</script>

bValidator also checks for options set by data-bvalidator-option- attribute on the <form> element. For example, for singleError use the data-bvalidator-option-single-error attribute name:

<form data-bvalidator-option-single-error="true" data-bvalidator-validate>
    <input type="text" data-bvalidator="number,required"/>
</form>

Also see theme options.

bValidator can retrieve validation messages from:

• validation function
• data-bvalidator-msg attribute
• data-bvalidator-msg-functionName attribute
• configuration object (options)
  
• server response (example)

See examples.

You can use {0}, {1}, {2}, {3}, ... tags in the validation message and they will be replaced with validation function parameters in [].

You can change default messages or add new ones by changing default options:

<script type="text/javascript">
    bValidator.defaultOptions.messages.en.email = 'Invalid email';
    bValidator.defaultOptions.messages.en.mycheck = 'Correct this';        
</script>

or pass messages as options to validator constructor:

<script type="text/javascript">

    var options = {
        lang: 'hr',
        messages: {
            hr: {
                'default':    'Ispravite ovu vrijednost.',
                'equalto':    'Unesite ponovno istu vrijednost.',
                'differs':    'Unesite različitu vrijednost.',
                // ....
            }
        }
    };
    
    $('#myform').bValidator(options);

</script>

All default messages in English are listed in jquery.bvalidator.js file. For some other languages, there are .js files in lang folder.

If you create a translation file, please make a pull request on GitHub and I will merge it into the project.

Validation functions (validators) are functions that check the value and return true if the value is valid.

Modifying functions (modifiers) are functions that change the value of the field before validation, for example, to trim whitespace. Modifiers return a modified value.

Validations which will be invoked for an input are listed by default in data-bvalidator attribute. Modifiers are listed in data-bvalidator-modifier attribute.

Some functions can have parameters which are stated in square brackets [] and delimited with :, for example: mycheck[param1:param2:param3].

<input type="text" data-bvalidator="maxlength[10]" data-bvalidator-modifier="trim" />
<input type="text" data-bvalidator="max[10],email,required" />

Here are listed all built-in validation functions, but you can easily add your own.

Modifying functions

Custom modifiers can be added in the same way as custom validation functions (see example).

When you make an instance of bValidator you can call some functions on that instance. You can get reference to a validator instance using jQuery data function:

<script type="text/javascript">

    $('#myform').bValidator();
    
    // check if form is valid
    if($('#myform').data('bValidator').isValid()){
        // do somenthing
    }

</script>

.data('bValidator') returns reference to the first instance of bValidator. You can have more instances of bValidator on the same form (see example) and all references are returned by .data('bValidators') (note the 's' here).

<script type="text/javascript">

    // first instance
    $('#myform').bValidator();
	
    // second instance with default options and named 'myinstance'
    $('#myform').bValidator(null, 'myinstance');
    
    // validates the form with the first instance named 'bvalidator'
    $('#myform').data("bValidators").bvalidator.validate();
    
    // validates the form with the second instance named 'myinstance'
    $('#myform').data("bValidators").myinstance.validate();

</script>

Instance names can be also set by data-bvalidator-validate attribute. Default instance name is bvalidator. Instance names are in lower case.

<script type="text/javascript">

    $('#myform').data('bValidator').getModifiers().myMod = function(value){
        // return changed value
        return 'newValue';
    }
</script>

Example of using an event triggered by bValidator:

<script type="text/javascript">

    $('#myForm').on('beforeFormValidation.bvalidator', function () {
        // do something...
    })

</script>

bValidator sets some values to the event object which you can access from within the event function:

<script type="text/javascript">

    $('#myForm').on('beforeFormValidation.bvalidator', function (event) {
        
        // bValidator instance
        event.bValidator.instance

        // validation result, true or false ('after' events only)
        event.bValidator.validationResult

        // array with error messages (afterFieldValidation only)
        event.bValidator.errorMessages

        //  <form> which is validated
        event.target
    })

</script>

Basic example

This is a basic example of using bValidator.

Custom messages

You can set a validation message for the field with data-bvalidator-msg attribute:

A message for a specific validation function can be set with data-bvalidator-msg-functionName attribute:

In the previous example validateTillInvalid option is used to show a message from one validation function at the time.

Messages can also be set through options. This example shows how to set a validation message with options passed to bValidator constructor:

Validation function can return a message. If the validation function returns a string, it will be used as validation message. See also custom validation functions examples.

See more about messages here.

Custom validation function

If you want to make your own validation function, create a function that returns true for successful validation and put the function name in data-bvalidator attribute:

You can pass parameters to your validation function. First argument to a validation function is the value of the input field and other arguments (if any) are values stated in square brackets [] after the function name in data-bvalidator attribute.

To submit the next form fill in both fields or leave them empty:

Password form:

If your validation function is not accessible from global scope, you can add the validation function to a validator instance by using getValidators API function:

<script type="text/javascript">

    $('#myform').data('bValidator').getValidators().myAction = function(value){
        // check the value and return true if valid
    }
</script>

Or you can add your validation function to all instances of bValidator by adding the function to bValidator.validators object:

<script type="text/javascript">

    bValidator.validators.myAction = function(value){
        // check the value and return true if valid
    }
    
</script>

Big form

Checkboxes and radio buttons

Checkboxes or radio buttons are grouped by giving the same name attribute to all elements in the group. data-bvalidator and data-bvalidator-msg attributes should be added to only one element in the group on which a validation message will be shown.

Dynamic form

Inputs can be added to the form after bValidator is initialized. Note that hidden form elements are not validated by default. If you need to hide or show some elements, put them into a container element and then show or hide that container. Validation messages will not follow show/hide actions if you apply them only on the input element which is validated. That also depends on the theme that is used.
If you use validateOn option, after adding a new input to the form, call bindValidateOn API function to bind validateOn event.

HTML5 form

bValidator works nicely with HTML5 input types. See enableHtml5Attr option for supported attributes. You can also use data-bvalidator attributes with HTML5 markup. See also examples for bs3form theme.

Validate any element

Container element doesn't have to be a <form>. You can trigger validation with JavaScript:

Any element can be validated like an <input>:

More instances

Enter letters and numbers in the field below:

You can have more instances of bValidator on the same form. In the example above, there are two bValidator instances on the form. One named bvalidator (name for the default instance) and another named hint . Names are stated in data-bvalidator-validate attribute. Each instance has its own options. In this example hint instance is configured not to submit the form, to use gray2 theme and to validate on keyup event. For hint instance options are set with data-hint- attributes in the same way as with data-bvalidator- attributes for the default instance.

Similar example but defined with JavaScript:

Just displaying messages

In this example no validation is done, only messages are displayed. Messages can be displayed on any element on the page, it doesn't have to be an input and it doesn't have to be inside the container element on which bValidator is bound.

Forcing validation result

Sometimes after bValidator is initialized you may want to disable validation for a <form> or an <input> or you want to force them invalid. You can do it by adding data-bvalidator-return attribute with value true or false. Put the attribute on the <form> if you want to force validation result for all inputs inside the form.

You can also force validation result for all fields inside the <form> with forceValidationResult option:

$('form').data('bValidator').getOptions().forceValidationResult = true;

Modifiers

Modifiers are functions which purpose is to change the input value before validation. For example, to strip trailing/leading whitespace. Modifiers are called before validation functions. Modifying function are listed in data-bvalidator-modifier attribute by default, the same as validation functions are listed data-bvalidator attribute. For some validation functions trim modifier is called by default (see autoModifiers option).

In this example, trim modifier is automatically called on the first field because email function is mentioned by default in autoModifiers option.
On the second field, custom modifier will delete all but digits.
The third field modifier will add 'http://' if you enter URL without it.
The fourth field has modifying function only, no validation at all. You can use only modifier on the field without data-bvalidator attribute and validation.

Note that the first argument of a modifying function is the value of the input. Other arguments (if any) are values stated in square brackets [] after the function name in data-bvalidator-modifier attribute (same as for custom validation functions). Modifying function should return a new value for the input field. If nothing (undefined) is returned, the input value will not be changed.

Server side validation

This field is validated on the server side with ajax function:

The data-bvalidator-option-ajax-url attribute on the <form> contains URL to which the request is sent. By default, bValidator will make asynchronous HTTP (Ajax) request sending values of the inputs that are validated. If the field is valid, the response from the server should be a string defined by ajaxValid option ("ok" by default). The server can also return a JSON string with results for each validated field.

In the next example both fields are validated on the client and also on the server:

Server validation won't be invoked if the value is invalid by some other validation function (email in this example) or if the value is not changed since the last check. JSON string returned from the server should be in format:

{"inputName1":"ok", "inputName2":"ok"}

For the fields that are valid, JSON property should have "ok" value by default. JSON properties for the fields that are not valid can have any other value or don't have to be included in the response. If all fields are valid only "ok" string can be returned from the server. Validation message for ajax function can be set by data-bvalidator-msg-ajax attribute (see more about messages).

Validator will make Ajax request only for the fields which need validation and expect response only for those fields. In this examples, all fields are always in JSON response, but that's because a static text file and not a real validation script is on the server side.

You can also return validation messages from the server. In the next example, all fields are validated on the server and all messages come from the server:

Set ajaxResponseMsg option to true to show messages from the server response. valempty function is used here instead of required, because required will show the validation message that the field is required and skip server validation. This way the field is always validated on the server side, even if empty.

Themes define the look of validation messages. To use a theme you need to include .css and .js files for the theme.

To set the theme for all fields in the form, set the theme name with data-bvalidator-theme attribute on the <form>:

<form data-bvalidator-theme="gray3" data-bvalidator-validate>
    <input type="text" data-bvalidator="alphanum,required"/>
</form>

That is the same as setting useTheme option with data-bvalidator-option-use-theme attribute.

To change the theme only for the specific input field, put data-bvalidator-theme attribute on the <input>:

<form data-bvalidator-validate>
    <input type="text" data-bvalidator="alphanum,required" data-bvalidator-theme="gray3"/>
</form>

With JavaScript, you can set the default theme by changing useTheme option. For example, you can set the default theme depending on the screen width and for small-screen devices choose more adapted theme:

<script type="text/javascript">

    if ($(window).width() < 760)
        bValidator.defaultOptions.useTheme = 'insert';
    else
        bValidator.defaultOptions.useTheme = 'gray';

</script>

Theme examples and options:

Options for themes can be set by data-bvalidator-theme-optionName attribute or by JavaScript.

You can set data-bvalidator-theme-optionName attribute on the <form> element to change the option for all the fields in the form:

<form data-bvalidator-theme-offset="-20,0" data-bvalidator-validate>
    <input type="text" data-bvalidator="alphanum,required"/>
</form>

If you put data-bvalidator-theme-optionName attribute on the <input>, the option will be set only for that field:

<form data-bvalidator-validate>
    <input type="text" data-bvalidator-theme-offset="-20,0" data-bvalidator="alphanum,required"/>
</form>

Theme options can also be set by changing default options:

<script type="text/javascript">
    bValidator.defaultOptions.themes.gray3.offset = '-20,0';
    bValidator.defaultOptions.themes.gray3.showClose = false;        
</script>

Or by passing object with options to bValidator constructor function:

<script type="text/javascript">

    var options = {
        themes: {
            'gray3': {
                 showClose: false
            }
        }
    };

    $('#myform').bValidator(options);

</script>

gray

Options for gray theme:

Files to include for gray theme:

<script src="themes/presenters/default.min.js"></script>
<script src="themes/gray/gray.js"></script>
<link href="themes/gray/gray.css" rel="stylesheet" />

bs3form

This theme uses Bootstrap's form validation styles and is designed for pages built with Bootstrap 3. For this theme to work correctly you have to make forms with Bootstrap markup. It is important to place form-group and control-label classes correctly. See Bootstrap documentation for details.

With horizontal forms use the helper class bvalidator-bs3form-msg to mark the element into which to append the validation message. By default, the message is appended to form-group element.

Next example is Inline form. showMessages option is set to false to not show the messages:

Options for bs3form theme:

Files to include for bs3form theme:

<script src="themes/presenters/bs3form.min.js"></script>
<script src="themes/bs3/bs3form/bs3form.js"></script>

bs3popover

This theme uses Bootstrap Popover plugin to show messages. You have to include bootstrap js and css for this theme to work.

Options for bs3popover theme:

Files to include for bs3popover theme:

<script src="themes/presenters/bs3popover-tooltip.min.js"></script>
<script src="themes/bs3/bs3popover/bs3popover.js"></script>
<link href="themes/bs3/bs3popover/bs3popover.css" rel="stylesheet" />

bs3tooltip

This theme is similar to bs3popover theme but it uses Tooltip plugin to display messages. You have to include bootstrap js and css for this theme to work.

Options for bs3tooltip theme:

Files to include for bs3tooltip theme:

<script src="themes/presenters/bs3popover-tooltip.min.js"></script>
<script src="themes/bs3/bs3tooltip/bs3tooltip.js"></script>
<link href="themes/bs3/bs3tooltip/bs3tooltip.css" rel="stylesheet" />

insert

This is a simple theme which just inserts a message before or after the input which is checked.

You can easily change message styles or template by setting options:

Options for insert theme:

Files to include for insert theme:

<script src="themes/presenters/insert.min.js"></script>
<script src="themes/insert/insert.js"></script>
<link href="themes/insert/insert.css" rel="stylesheet" />

group

This theme puts all validation messages into one container.

Options for group theme:

Files to include for group theme:

<script src="themes/presenters/group.min.js"></script>
<script src="themes/group/group.js"></script>
<link href="themes/group/group.css" rel="stylesheet" />

gray2

This theme has the same options as the gray theme, see the theme .js file for default values.

Files to include for gray2 theme:

<script src="themes/presenters/default.min.js"></script>
<script src="themes/gray2/gray2.js"></script>
<link href="themes/gray2/gray2.css" rel="stylesheet" />

gray3

This theme has the same options as the gray theme, see the theme .js file for default values.

Files to include for gray3 theme:

<script src="themes/presenters/default.min.js"></script>
<script src="themes/gray3/gray3.js"></script>
<link href="themes/gray3/gray3.css" rel="stylesheet" />

gray4

This theme has the same options as the gray theme, see the theme .js file for default values.

Files to include for gray4 theme:

<script src="themes/presenters/default.min.js"></script>
<script src="themes/gray4/gray4.js"></script>
<link href="themes/gray4/gray4.css" rel="stylesheet" />

orange

This theme has the same options as the gray theme, see the theme .js file for default values.

Files to include for orange theme:

<script src="themes/presenters/default.min.js"></script>
<script src="themes/orange/orange.js"></script>
<link href="themes/orange/orange.css" rel="stylesheet" />

postit

This theme has the same options as the gray theme, see the theme .js file for default values.

Files to include for postit theme:

<script src="themes/presenters/default.min.js"></script>
<script src="themes/postit/postit.js"></script>
<link href="themes/postit/postit.css" rel="stylesheet" />

red

This theme has the same options as the gray theme, see the theme .js file for default values.

Files to include for red theme:

<script src="themes/presenters/default.min.js"></script>
<script src="themes/red/red.js"></script>
<link href="themes/red/red.css" rel="stylesheet" />

bslikerc

This theme looks like Bootstrap popover with right placement, but it doesn't depend on Bootstrap as bs3popover theme does.

This theme has the same options as the gray theme, see the theme .js file for default values.

Files to include for bslikerc theme:

<script src="themes/presenters/default.min.js"></script>
<script src="themes/bslikerc/bslikerc.js"></script>
<link href="themes/bslikerc/bslikerc.css" rel="stylesheet" />

bslikert

This theme looks similar to Bootstrap popover, but it doesn't depend on Bootstrap as bs3popover theme does and has the same options as the gray theme. See the theme .js file for default options values.

Files to include for bslikert theme:

<script src="themes/presenters/default.min.js"></script>
<script src="themes/bslikert/bslikert.js"></script>
<link href="themes/bslikert/bslikert.css" rel="stylesheet" />