@shopmacher/validate
v1.5.0
Published
Extensible JavaScript form validation library
Downloads
17
Readme
sm-validate
Validate is an extensible client side validation library for form inputs. It provides a set of basic validators and the possibility to write your own.
Table of Contents
Installation
Run npm install -S @shopmacher/validate
to install the package from npm.
Alternatively, you can download the latest release from this repository.
To include the library, refer to the module definition you are using.
UMD
Include the validate.js
and validate.css
from the lib
directory
in your project. This makes Validate
available in the global scope.
AMD
Adjust your require.config.js
to include the following code:
packages: [{
name: '@shopmacher/validate',
location: 'node_modules/@shopmacher/validate/lib',
main: 'validate'
}]
Now you can use the slider in your project like this:
define('myModule', ['@shopmacher/validate'], function(Validate) {
// Access Validate object here
});
CommonJS
Require the slider via const Validate = require('@shopmacher/validate');
and use
the Validate
variable to access its methods.
ESM
Import the slider via import Validate from '@shopmacher/validate';
and access it
via the Validate
variable.
Usage
This section describes how to initialise and configure the validator.
Initialization
The library can either intialized via the class constructor for a single
input, or via a static method for all inputs that posses the attribute
data-validate="true"
.
Class constructor
const $input = document.querySelector('.my-input');
const validator = new Validator($input);
Static initialization
const validators = Validator.init();
In case of static initialization, the method returns an array of validators. This can later be used to validate forms on submit.
Validating forms
To validate inputs on form submit, you can attach the validators from the init method or the constructor to a form.
const $form = document.querySelector('#my-form');
const validators = Validator.init();
Validator.attachToForm($form, validators, {});
This will check all validators, when the form is submitted and prevent the submit, if one of the validators fails.
Additionally, the third argument of the attachToForm
method is an options
object that can be used to configure the behavior of the validation further.
It can have the following options:
preventSubmit
(boolean, default: false) - prevents the submitting of the form, even if it is valid
Configuration
To validate an input, the library provides a set of basic validators that are controlled via data-attributes. The following example would validate the input for a minimum length of 5 characters and output the result into an HTML element.
<input
data-validate="true"
data-validate-minlength="5"
data-validate-minlength-message="Please enter at least 5 chars"
data-validate-error-element="#validate-message" />
<div id="validate-message"></div>
The validation triggers when the user leaves the input field or does not type for 300 ms (default).
For a list of validations and configurations, please refer to the table below.
Attributes
Those are the data-attributes you can use to configure the validators.
All attributes are prefixed by data-validate-
. The messages that will
be emitted when the validator fails uses the -message
-suffix on the
attribute (as seen in the example above).
| Type | Attribute | Description | Values | Required |
|----------------|-----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------|----------|
| Initialization | validate | If this attribute is true
, the input is eligible for being validated. | boolean | yes |
| Validation | minlength | Minimum amount of characters required in the input | number | no |
| Validation | maxlength | Maximum amount of characters allowed in the input | number | no |
| Validation | empty-message | Message that is emitted, when the input is empty. This does not need the empty attribute. | any | no |
| Validation | type | Type of the inputs content. | "text" | "number" | "email" | no |
| Validation | regex | Content of input is validated via the provided regular expression. Example: ^\d+$
| string / RegExp | no |
| Validation | hidden | Validate fields that are not shown to the user (hidden fields). Default: true
| boolean | no |
| Configuration | invalid-message | Provides a generic message for failing validators. This can be used, if you do not want to provide separate messages for every validator. | any | no |
| Configuration | error-element | Provides an element selector to specify the element that the validation messages are rendered to. Example: #my-output-dev
. Internally, this is passed to querySelector. | string | no |
| Configuration | debounce | Time in ms that the validate event is debounced when the user types in an input field. Defaults to 300 ms. | number | no |
CSS classes
Whenever a validation failes, the CSS class sm-validate-error
is added
to the validated element. This allows you to take control over different styling
of invalid inputs.
Custom validators
In addition to using the predefined validators, you can provide your own.
Defining a validator
A validator is a JavaScript function that follows a predetermined
scheme. A validator to check, if the inputs value is the string Hello
would be implemented like this:
// ECMAScript 2015
const validator = {
attr: 'hello',
create: ($input, { value, message }) => ({
isValid: () => $input.value === 'Hello',
message
})
};
In order to perform validation based on asynchronous results, the isValid
method can return a Promise, as seen in the following example:
const validator = {
attr: 'hello',
create: ($input, { value, message }) => ({
isValid: () => new Promise(resolve => resolve(true)),
message
})
};
The property attr
defines, through which data-attribite the validator
will be accessible.
In case of the example above, the data-attribute data-validate-hello
can be attached to the input to use the validator.
The validation message that is emitted if the validator fails can be
defined through the use of the attribute data-validate-hello-message
.
The create
method returns the instance of the validator that the
library is going to use.
It receives the following parameters:
$input
- the input field the validator is called upon- An object consisting of:
value
- the value of the inputmessage
- the validation message (this is mainly used to pass it through)
The create
method ifself returns an object consisting of:
isValid
- a function that returns true, if the input is valid or a Promise resolving to truemessage
- the validation messagetriggerOnChange
- boolean (default: true) that determines, if the validator should validate on change of the inputtriggerOnSubmit
- boolean (default: true) that determines, if the validator should validate on form submit
Using a custom validator
Once defined, the custom validator(s) can be passed to either the static
init
function or the class constructor.
const validator = { /* your validator */ };
Validator.init([validator]);
// or
new Validator($element, [validator]);
Note that the validators need to be passed as an array, which means that you can pass as many as you want.
Todo
- [x] Implements basic validators
- [x] Provide methods to plug-in custom validators
- [x] Extend documentation to cover custom validators
- [ ] Write unit tests
Contributing
To contribute to this project, fork the repository and create your feature/hotfix branch with whatever you want to add.
Install the project dependencies using npm i
and start the
development server via npm start
. A webpack-dev-server will now
listen on port 8080.
When you are finished developing, make sure to add a documented pull request.
Please note: Pull requests for new features that are not typed via flowtype as well as not following the general code style used in this project will be rejected.
License
MIT