This is a helper library for validating forms in a browser with help of validate.js. Of course, you can validate forms just with validate.js, but you do not need to write much JS code to do similar things with this library. All you need is to add regular HTML5 validation attributes (like 'required', 'min', 'max') and give correct 'type' attribute to your 'input' elements. Everything else is done by this library.
Run:
npm i --save zw-form-validator
If you love TypeScript, you can use it out-of-box, type definition files are already included in the package.
First, you need to import the library into your module.
const v = require('zw-form-validator');
In all examples below, it is assumed that you have imported the module into constant named v
.
For each form that needs to be validated, a FormValidator object should be created. You can do it either manually:
let validator = new v.FormValidator(document.getElementById('form'));
Or take advantage of static member function that automatically creates FormValidator instances for all elements that have a specific class.
By default, it creates validators for elements with class js-validate
.
FormValidator.init();
The first argument to this function is a class name, the second one is options that validator objects should take. FormValidator constructor takes an options object as an argument.
You can use regular HTML attributes to create validation rules. This library understands them. Refer to MDN documentation or specification on information about these attributes. For example:
<form class="js-validate">
<label class="ib">
<input type="text" name="name" required />
</label>
<label class="ib">
<input type="number" name="age" min="18" required />
</label>
<button type="submit">Auth</button>
</form>
Additionally, you can use extra validators that are supported by validate.js but not supported by native in-browser validation.
Just add data-validate-equality
attribute to your element.
The value of the attribute should be equal to the name of an input whose value should equal to the value of the current element.
<input type="password" name="password" />
<input type="password" name="password_repeat" data-validate-equality="password" />
If your input can be only one of a list of predefined values, you can add data-validate-include
attribute and list all allowed values here.
The value of the attribute should be either a valid JSON (which is passed to validate.js inclusion
constraint) or a single value.
In the latter case, only this value will be allowed.
<input type="number" name="number" data-validate-include="[1, 5, 7]" />
If your input value should not have some values, add data-validate-exclude
attribute to it:
<input type="number" name="number" data-validate-exclude="[1, 4, 5]" />
Add the following attributes that match to corresponding validate.js validators:
data-validate-integer (onlyInteger)
data-validate-divisible (divisibleBy)
data-validate-odd (odd)
data-validate-even (even)
In addition to minlength
attribute supported by this library, you can use extra validations that check the length of the value:
data-validate-length-equal
data-validate-length-max
Set data-validate-url-schemes
to a list of schemes that should be allowed.
Set data-validate-url-allow-local
if you want validator to allow local URLs.
These attributes require type
attribute to be set to url
.
If you need more, you can register your own validators. First, you will need a function called 'constraint builder' that will take a constraint object (see validate.js docs for details) and transform it. If you target can be achieved with built-in validate.js features, it is all you need.
FormValidator.addConstraintBuilder('extra', (constraint, input, option, msg, validator) => {
if (constraint.url) {
constraint.url.allowLocal = true;
} else {
constraint.url = {
allowLocal: true
}
}
});
You can use this custom validator by adding an attribute to your input in the following form:
<input type="text" name="input" data-validate-extra="some value" />
This function will be called each time validator needs to rebuild constraints for each input that has the corresponding attribute.
The constraint builder function takes the following arguments:
constraint
is the constraint object (see validate.js docs) for an input you are building constraints for.
You should either update the properties of this object or return a new object that will replace the old one.
input
is the input you are building constraints for.
option
is the value of data-validate-...
attribute (some value
in our example).
msg
is the message for this validation.
See next section for details.
validator
is the FormValidator object.
If you need to register your own validate.js validator, you can pass a function as the third argument to addConstraintBuilder
function.
This function will be registered as a custom validator for validate.js, and its name will be equal to the value of the first argument.
You can change default messages that validator adds to the elements by passing it as options to the constructor:
FormValidator.init('js-validate', {
messages: {
required: 'You should not skip this input!',
email: 'Input email here!'
}
});
See documentation or source code for the full list of supported keys. You can change error message for a specific input too:
<input type="email" name="name" required data-msg-required="You should not skip this input!" data-msg-email="Input email here!" />
It works even with custom constraint builders or validators:
<input type="text" name="input" data-validate-extra data-msg-extra="The value does not pass extra check!" />
Install typedoc:
npm i -g typedoc
typedoc index.ts --out ./docs
Now open docs/index.html
file.