Form validations for Web and Web-Twig packages of the Spirit Design System.
yarn add @lmc-eu/spirit-form-validationsor
npm install --save @lmc-eu/spirit-form-validationsInclude the JavaScript file in your HTML <head> or just before the closing <body> tag.
<script src="dist/bundles/umd/spirit-form-validations.min.js"></script>Or
<script src="dist/bundles/esm/spirit-form-validations.js" type="module"></script>Now create a form:
<form id="form1">
<label for="email">Email</label>
<input type="email" id="email" required />
<button>Subscribe</button>
</form>… and validate it:
window.onload = () => {
const form = document.getElementById("form1");
// create the FormValidations instance
const formValidations = new FormValidations(form);
form.addEventListener('submit', function (event) {
event.preventDefault();
// check if the form is valid
const valid = formValidations.validate(); // returns true or false
});
};
Profit
The goal of this library is not to provide every possible type of validation and thus becoming a bloat. The goal is to provide most common types of validations and a neat way to add custom validators.
It automatically validates required, min, max, minlength, maxlength attributes and the value of type attributes like email, number and more…
The library is built on top of native validation attributes as replace for native browser validation, not a progressive enhancement.
Using the novalidate attribute the library is turning off the browser validations and does the heavy lifting itself.
FormValidations takes 3 parameters:
-
form - The form element
-
config - An object containing the configuration. Default is Spirit's configuration which is
const defaultConfig = {
formFieldSelector: '[data-spirit-validate]',
errorClass: 'has-danger',
successClass: 'has-success',
validationTextParentSelector: '[data-spirit-validate]',
validationTextTag: 'div',
validationTextClass: '',
dataElementMessage: 'validation-text',
};-
live - A boolean value indicating whether FormValidations should validate as you type, default is
true
| Name | Usage | Description |
|---|---|---|
| required |
required or data-spirit-required
|
Validates required fields |
type="email" or data-spirit-type="email"
|
Validates email | |
| number |
type="number" or data-spirit-type="number"
|
|
| integer | data-spirit-type="integer" |
|
| minlength |
minlength="10" or data-spirit-minlength="10"
|
|
| maxlength |
maxlength="10" or data-spirit-maxlength="10"
|
|
| min |
min="20" or data-spirit-min="20"
|
|
| max |
max="100" or data-spirit-max="100"
|
|
| pattern |
pattern="/[a-z]+$/i" or data-spirit-pattern="/[a-z]+$/i", \ must be escaped (replace with \\) |
|
| equals | data-spirit-equals="#field-selector" |
Check that two fields are equal |
FormValidations.addValidator(nameOrElem, handler, errorMessage, priority, halt);var formValidations = new FormValidations(document.getElementById('form1'));
var element = document.getElementById('email');
// A validator to check if the first letter is capitalized
FormValidations.addElementValidator(
element,
function (value) {
if (value.length && value[0] === value[0].toUpperCase()) {
return true;
}
return false;
},
'The first character must be capitalized',
2,
false,
);A validator to check if the input value is within a specified range.
name you can override those validators.
FormValidations.addValidator(
'my-range',
function (value, param1, param2) {
return parseInt(param1) <= value && value <= parseInt(param2);
},
'The value (${0}) must be between ${1} and ${2}',
5,
false,
);Now you can assign it to your inputs like this
<input type="text" class="form-control" data-spirit-my-range="10,30" /><input required data-spirit-required-message="My custom message" />Add an attribute like data-spirit-<ValidatorName>-message with the custom message as a value to show custom error messages.
You can add custom messages like this for as many validators as you need. Here ValidatorName means required, email, min, max etc.
FormValidations(form, config, live)
Constructor
| Parameter | Default | Required | Description |
|---|---|---|---|
| form | — | ✔ | The form element |
| config | See above | ✕ | The config object |
| live | true |
✕ | Whether FormValidations should validate as you type |
FormValidations.validate(inputs, silent)
Validate the form or field(s)
| Parameter | Default | Required | Description |
|---|---|---|---|
| inputs | — | ✕ | When not given, the entire form is validated. Inputs can either be one DOM element or a collection of DOM elements returned by document.getElement…, document.querySelector…
|
| silent | false |
✕ | Does not show error messages when silent is true
|
FormValidations.getErrors(input)
Get the errors of the form or a specific field
| Parameter | Default | Required | Description |
|---|---|---|---|
| input | — | ✕ | When input is given, it returns the errors of that input element, otherwise returns all errors of the form as an object, using input element as key and corresponding errors as value. validate() must be called before expecting this method to return correctly. |
FormValidations.setLocale(locale)
Set the current locale globally
| Parameter | Default | Required | Description |
|---|---|---|---|
locale |
— | ✔ | Error messages on new FormValidations forms will be displayed according to this locale |
FormValidations.addMessages(locale, messages)
Set the current locale globally
| Parameter | Default | Required | Description |
|---|---|---|---|
locale |
— | ✔ | The corresponding locale |
messages |
— | ✔ | Object containing validator names as keys and error texts as values |
FormValidations.addElementValidator(elem, fn, message, priority, halt)
Add a custom validator
| Parameter | Default | Required | Description |
|---|---|---|---|
element |
— | ✔ | The dom element where validator is applied to. |
halt |
false |
✕ | Whether to stop validation of the field after this validator is applied on the field. When true, after this validator finishes validating, the rest of the validators are ignored on the current field. |
message |
— | ✔ | The message to show when the validation fails. It supports simple templating. ${0} for the input's value, ${1} and so on are for the attribute values. For the above example, ${0} will get replaced by myValue, ${1} by 10, ${2} by 20, ${3} by dhaka. It can also be a function which should return the error string. The values and inputs are available as function arguments |
priority |
1 | ✕ | Priority of the validator function. The higher the value, the earlier it gets called when there are multiple validators on one field. |
validatorCallback |
— | ✔ | The function that validates the field. The value of the input field gets passed as the first parameter, and the attribute value (split using a comma) as the subsequent parameters. For example, for <input data-spirit-my-validator="10,20,dhaka" value="myValue"/>, the validator function gets called like validatorCallback("myValue", 10, 20, "dhaka"). Inside the function this refers to the input element |
FormValidations.addValidator(name, fn, message, priority, halt)
Add a global custom validator
| Parameter | Default | Required | Description |
|---|---|---|---|
name |
— | ✔ | A string, the name of the validator, you can then use data-spirit-<NAME> attribute in form fields to apply this validator |
.... |
— | — | Other parameters same as above |
FormValidations.reset()
Reset the errors in the form
FormValidations.destroy()
Destroy the pristine object