v0.5.3 is released on 2014.11.05!
What's included?
The BootstrapValidator package consists of the following files:
bootstrapvalidator/
├── dist
│ ├── css
│ │ ├── bootstrapValidator.css
│ │ └── bootstrapValidator.min.css
│ └── js
│ ├──language
│ │ ├── de_DE.js
│ │ ├── en_US.js
│ │ └── ...
│ ├── bootstrapValidator.js
│ └── bootstrapValidator.min.js
└── src
├── css
│ ├── bootstrapValidator.css
│ └── bootstrapValidator.min.css
└── js
├──language
│ ├── de_DE.js
│ ├── en_US.js
│ └── ...
├── validator
│ ├── base64.js
│ ├── between.js
│ ├── callback.js
│ └── ...
└── bootstrapValidator.jsThe src directory consists of the original source files. src/js/bootstrapValidator.js is not compressed and doesn't include any validators.
The dist directory consists of files which is combined and compressed. dist/js/bootstrapValidator(.min).js includes all validators. It should be used in the production site.
The language packages are placed inside both dist/js/language and src/js/language directories.
Language packages
BootstrapValidator has been translated into the following languages:
If you wonder how to use the language package, then this example is exactly for you
Translate to other language
It is very easy to translate default English package into your language. Follow the steps below:
- Fork the project
-
Create new language file in the language directory.
The file must be named as countrycode_LANGUAGECODE.js, where countrycode and LANGUAGECODE are the ISO 3166 country and language codes in lowercase and uppercase respectively.
The File Name column in the table above are some examples of valid language file name. - Translate the English language package into your language file created above
- Make a pull request
Usage
It takes only 3 steps to use the plugin:
Including library
Since the BootstrapValidator plugin requires jQuery and Bootstrap 3, you have to include the required CSS and JS files to your page:
<link rel="stylesheet" href="/path/to/bootstrap/css/bootstrap.css"/>
<link rel="stylesheet" href="/path/to/dist/css/bootstrapValidator.min.css"/>
<script type="text/javascript" src="/path/to/jquery/jquery-1.10.2.min.js"></script>
<script type="text/javascript" src="/path/to/bootstrap/js/bootstrap.min.js"></script>Next, requires the plugin javascript file:
<!-- Either use the compressed version (recommended in the production site) -->
<script type="text/javascript" src="/path/to/dist/js/bootstrapValidator.min.js"></script>
<!-- Or use the original one with all validators included -->
<script type="text/javascript" src="/path/to/dist/js/bootstrapValidator.js"></script>
<!-- Or use the plugin with required validators -->
<script type="text/javascript" src="/path/to/src/js/bootstrapValidator.js"></script>
<script type="text/javascript" src="/path/to/src/js/validator/...validator..."></script>If you want to use the default message translated in the language package, then finally include it:
<script type="text/javascript" src="/path/to/src/js/language/languagecode_COUNTRYCODE.js"></script>You don't need to require the English package because it is already included in the plugin. The package is available here just for translating into other languages.
Writing form
Since BootstrapValidator is designed to use with Bootstrap, your form must be structured using Bootstrap classes.
If your form is NOT structured by Bootstrap classes (the element containing field and associated label does NOT have form-group class), you will see the following error in the Console:
// Chrome
Uncaught RangeError: Maximum call stack size exceeded
// Firefox
Too much recursion error
If your form is complex and uses custom CSS class for each group instead of .form-group, use the group option
Name conflict
Do not use the properties of a form, such as submit, reset, length, method to set the name or id attribute of form, field elements. Name conflicts can cause the problem.
For example, you cannot submit the form after validating if use submit to name the Submit button:
<button type="submit" name="submit" class="btn btn-primary">Submit</button>DOMLint has a complete list of rules to check the markup for these kind of problems.
The plugin supports all possible kind of Bootstrap form, including:
Basic form
<form class="registerForm">
<div class="form-group">
<label>Username</label>
<input type="text" class="form-control" name="username" />
</div>
<div class="form-group">
<label>Email address</label>
<input type="text" class="form-control" name="email" />
</div>
</form>$(document).ready(function() {
$('.registerForm').bootstrapValidator({
message: 'This value is not valid',
feedbackIcons: {
valid: 'glyphicon glyphicon-ok',
invalid: 'glyphicon glyphicon-remove',
validating: 'glyphicon glyphicon-refresh'
},
fields: {
username: {
message: 'The username is not valid',
validators: {
notEmpty: {
message: 'The username is required and cannot be empty'
},
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'
}
}
},
email: {
validators: {
notEmpty: {
message: 'The email is required and cannot be empty'
},
emailAddress: {
message: 'The input is not a valid email address'
}
}
}
}
});
});Basic form without labels
<form class="registerForm">
<div class="form-group">
<input type="text" class="form-control" name="username" placeholder="Username" />
</div>
<div class="form-group">
<input type="text" class="form-control" name="email" placeholder="Email address" />
</div>
</form>Inline form
<form class="form-inline registerForm">
<div class="form-group">
<input type="text" class="form-control" name="username" placeholder="Username" />
</div>
<div class="form-group">
<input type="text" class="form-control" name="email" placeholder="Email address" />
</div>
</form>Horizontal form
<form class="form-horizontal registerForm">
<div class="form-group">
<label class="col-sm-3 control-label">Username</label>
<div class="col-sm-6">
<input type="text" class="form-control" name="username" />
</div>
</div>
<div class="form-group">
<label class="col-sm-3 control-label">Email address</label>
<div class="col-sm-6">
<input type="text" class="form-control" name="email" />
</div>
</div>
</form>It also supports multiple fields on the same row:
<form class="form-horizontal registerForm">
<div class="form-group">
<label class="col-sm-2 control-label">Account</label>
<div class="col-sm-4">
<input type="text" class="form-control" name="username" placeholder="Username" />
</div>
<div class="col-sm-4">
<input type="text" class="form-control" name="email" placeholder="Email address" />
</div>
</div>
</form>Calling plugin
Call the plugin to validate the form as following:
$(document).ready(function() {
$(formSelector).bootstrapValidator({
excluded: ...,
feedbackIcons: ...,
live: 'enabled',
message: 'This value is not valid',
submitButtons: 'button[type="submit"]',
trigger: null,
fields: ...
});
});For example, to validate the sample registration form above, the plugin might be called as:
$(document).ready(function() {
$('.registerForm').bootstrapValidator({
message: 'This value is not valid',
feedbackIcons: {
valid: 'glyphicon glyphicon-ok',
invalid: 'glyphicon glyphicon-remove',
validating: 'glyphicon glyphicon-refresh'
},
fields: {
username: {
message: 'The username is not valid',
validators: {
notEmpty: {
message: 'The username is required and cannot be empty'
},
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'
}
}
},
email: {
validators: {
notEmpty: {
message: 'The email is required and cannot be empty'
},
emailAddress: {
message: 'The input is not a valid email address'
}
}
}
}
});
});Look at the Settings page to see the meaning of plugin options.
Example
Below is a classical registration form covering all the steps you've just seen above:
<!doctype html>
<html>
<head>
<!-- Bootstrap CSS -->
<link rel="stylesheet" href="/vendor/bootstrap/css/bootstrap.css"/>
<!-- Include FontAwesome CSS if you want to use feedback icons provided by FontAwesome -->
<link rel="stylesheet" href="/vendor/font-awesome/css/font-awesome.min.css" />
<!-- BootstrapValidator CSS -->
<link rel="stylesheet" href="/vendor/bootstrapvalidator/dist/css/bootstrapValidator.min.css"/>
<!-- jQuery and Bootstrap JS -->
<script type="text/javascript" src="/vendor/jquery/jquery.min.js"></script>
<script type="text/javascript" src="/vendor/bootstrap/js/bootstrap.min.js"></script>
<!-- BootstrapValidator JS -->
<script type="text/javascript" src="/vendor/bootstrapvalidator/dist/js/bootstrapValidator.min.js"></script>
</head>
<body>
<div class="container">
<div class="row">
<div class="col-md-8 col-md-offset-2">
<div class="page-header">
<h2>Sign up</h2>
</div>
<form id="registrationForm" method="post" class="form-horizontal">
<div class="form-group">
<label class="col-sm-3 control-label">Username</label>
<div class="col-sm-5">
<input type="text" class="form-control" name="username" />
</div>
</div>
<div class="form-group">
<label class="col-sm-3 control-label">Email address</label>
<div class="col-sm-5">
<input type="text" class="form-control" name="email" />
</div>
</div>
<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="password" />
</div>
</div>
<div class="form-group">
<label class="col-sm-3 control-label">Gender</label>
<div class="col-sm-5">
<div class="radio">
<label>
<input type="radio" name="gender" value="male" /> Male
</label>
</div>
<div class="radio">
<label>
<input type="radio" name="gender" value="female" /> Female
</label>
</div>
<div class="radio">
<label>
<input type="radio" name="gender" value="other" /> Other
</label>
</div>
</div>
</div>
<div class="form-group">
<label class="col-sm-3 control-label">Date of birth</label>
<div class="col-sm-5">
<input type="text" class="form-control" name="birthday" placeholder="YYYY/MM/DD" />
</div>
</div>
<div class="form-group">
<div class="col-sm-9 col-sm-offset-3">
<!-- Do NOT use name="submit" or id="submit" for the Submit button -->
<button type="submit" class="btn btn-default">Sign up</button>
</div>
</div>
</form>
</div>
</div>
</div>
<script>
$(document).ready(function() {
$('#registrationForm').bootstrapValidator({
// To use feedback icons, ensure that you use Bootstrap v3.1.0 or later
feedbackIcons: {
valid: 'glyphicon glyphicon-ok',
invalid: 'glyphicon glyphicon-remove',
validating: 'glyphicon glyphicon-refresh'
},
fields: {
username: {
message: 'The username is not valid',
validators: {
notEmpty: {
message: 'The username is required and cannot be empty'
},
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 and number'
},
different: {
field: 'password',
message: 'The username and password cannot be the same as each other'
}
}
},
email: {
validators: {
notEmpty: {
message: 'The email address is required and cannot be empty'
},
emailAddress: {
message: 'The email address is not a valid'
}
}
},
password: {
validators: {
notEmpty: {
message: 'The password is required and cannot be empty'
},
different: {
field: 'username',
message: 'The password cannot be the same as username'
},
stringLength: {
min: 8,
message: 'The password must have at least 8 characters'
}
}
},
birthday: {
validators: {
notEmpty: {
message: 'The date of birth is required'
},
date: {
format: 'YYYY/MM/DD',
message: 'The date of birth is not valid'
}
}
},
gender: {
validators: {
notEmpty: {
message: 'The gender is required'
}
}
}
}
});
});
</script>
</body>
</html><!doctype html>
<html>
<head>
<!-- Bootstrap CSS -->
<link rel="stylesheet" href="/vendor/bootstrap/css/bootstrap.css"/>
<!-- Include FontAwesome CSS if you want to use feedback icons provided by FontAwesome -->
<link rel="stylesheet" href="/vendor/font-awesome/css/font-awesome.min.css" />
<!-- BootstrapValidator CSS -->
<link rel="stylesheet" href="/vendor/bootstrapvalidator/dist/css/bootstrapValidator.min.css"/>
<!-- jQuery and Bootstrap JS -->
<script type="text/javascript" src="/vendor/jquery/jquery.min.js"></script>
<script type="text/javascript" src="/vendor/bootstrap/js/bootstrap.min.js"></script>
<!-- BootstrapValidator JS -->
<script type="text/javascript" src="/vendor/bootstrapvalidator/dist/js/bootstrapValidator.min.js"></script>
</head>
<body>
<div class="container">
<div class="row">
<div class="col-md-8 col-md-offset-2">
<div class="page-header">
<h2>Sign up</h2>
</div>
<!-- To use feedback icons, ensure that you use Bootstrap v3.1.0 or later -->
<form id="registrationForm" method="post" class="form-horizontal"
data-bv-feedbackicons-valid="glyphicon glyphicon-ok"
data-bv-feedbackicons-invalid="glyphicon glyphicon-remove"
data-bv-feedbackicons-validating="glyphicon glyphicon-refresh">
<div class="form-group">
<label class="col-sm-3 control-label">Username</label>
<div class="col-sm-5">
<input type="text" class="form-control" name="username"
data-bv-notempty="true"
data-bv-notempty-message="The username is required and cannot be empty"
data-bv-stringlength="true"
data-bv-stringlength-min="6"
data-bv-stringlength-max="30"
data-bv-stringlength-message="The username must be more than 6 and less than 30 characters long"
data-bv-regexp="true"
data-bv-regexp-regexp="^[a-zA-Z0-9]+$"
data-bv-regexp-message="The username can only consist of alphabetical and number"
data-bv-different="true"
data-bv-different-field="password"
data-bv-different-message="The username and password cannot be the same as each other" />
</div>
</div>
<div class="form-group">
<label class="col-sm-3 control-label">Email address</label>
<div class="col-sm-5">
<input type="text" class="form-control" name="email"
data-bv-notempty="true"
data-bv-notempty-message="The email address is required and cannot be empty"
data-bv-emailaddress="true"
data-bv-emailaddress-message="The email address is not a valid" />
</div>
</div>
<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="password"
data-bv-notempty="true"
data-bv-notempty-message="The password is required and cannot be empty"
data-bv-stringlength="true"
data-bv-stringlength-min="8"
data-bv-stringlength-message="The password must have at least 8 characters"
data-bv-different="true"
data-bv-different-field="username"
data-bv-different-message="The password cannot be the same as username" />
</div>
</div>
<div class="form-group">
<label class="col-sm-3 control-label">Gender</label>
<div class="col-sm-5">
<div class="radio">
<label>
<input type="radio" name="gender" value="male"
data-bv-notempty="true"
data-bv-notempty-message="The gender is required" /> Male
</label>
</div>
<div class="radio">
<label>
<input type="radio" name="gender" value="female" /> Female
</label>
</div>
<div class="radio">
<label>
<input type="radio" name="gender" value="other" /> Other
</label>
</div>
</div>
</div>
<div class="form-group">
<label class="col-sm-3 control-label">Date of birth</label>
<div class="col-sm-5">
<input type="text" class="form-control" name="birthday" placeholder="YYYY/MM/DD"
data-bv-notempty="true"
data-bv-notempty-message="The date of birth is required"
data-bv-date="true"
data-bv-date-format="YYYY/MM/DD"
data-bv-date-message="The date of birth is not valid" />
</div>
</div>
<div class="form-group">
<div class="col-sm-9 col-sm-offset-3">
<!-- Do NOT use name="submit" or id="submit" for the Submit button -->
<button type="submit" class="btn btn-default">Sign up</button>
</div>
</div>
</form>
</div>
</div>
</div>
<script>
$(document).ready(function() {
$('#registrationForm').bootstrapValidator();
});
</script>
</body>
</html><!doctype html>
<html>
<head>
<!-- Bootstrap CSS -->
<link rel="stylesheet" href="//cdn.jsdelivr.net/bootstrap/3.2.0/css/bootstrap.min.css"/>
<!-- Include FontAwesome CSS if you want to use feedback icons provided by FontAwesome -->
<link rel="stylesheet" href="//cdn.jsdelivr.net/fontawesome/4.1.0/css/font-awesome.min.css" />
<!-- BootstrapValidator CSS -->
<link rel="stylesheet" href="//cdn.jsdelivr.net/jquery.bootstrapvalidator/0.5.0/css/bootstrapValidator.min.css"/>
<!-- jQuery and Bootstrap JS -->
<script type="text/javascript" src="//cdn.jsdelivr.net/jquery/1.11.1/jquery.min.js"></script>
<script type="text/javascript" src="//cdn.jsdelivr.net/bootstrap/3.2.0/js/bootstrap.min.js"></script>
<!-- BootstrapValidator JS -->
<script type="text/javascript" src="//cdn.jsdelivr.net/jquery.bootstrapvalidator/0.5.0/js/bootstrapValidator.min.js"></script>
</head>
<body>
<!-- Same as Programmatic or Declarative usage -->
</body>
</html>