For each field in the form you want to validate, specify the field validation type(s) like data-jsv-validators="[TYPE]"

Or apply multiple types like:

That's all you need to do (unless you want to customize)

Validation Types

require

Input value exists and is not all whitespace.

If require is not specified, other validators will only trigger if there's a value entered, by design. So always use require (with others, optionally) if you require some input in the field.

email

Inputted value is a properly-formatted email.

url

Inputted value is a properly-formatted URL.

number

Input is a number (decimals OK).

length

Character length of the inputted value must be within a range. Specify character lengths in data-jsv-min and data-jsv-max.

exact

There must be an exact number of characters entered. Specify in data-jsv-exact.

numberexact

Inputted value is a number this many characters long. Specify in data-jsv-exact.

numberrange

Inputted value is a number is between (or equals) data-jsv-min to data-jsv-max

contains

Input contains this string. Specify in data-jsv-contains. Case-insensitive.

zipcode

Inputted value is a properly-formatted US zip code (plus 4 optional, but validated if entered)

phone

Inputted value is a properly-formatted phone number. This is a fairly liberal validation and will accept international numbers.

creditcard

Inputted value is a properly-formatted credit card number using the Luhn Algorithm.

pattern

Validate input against a custom regular expression specified in data-jsv-pattern.

compare

Compare inputted value against the value of another field. Specify the name of the field to compare to in data-jsv-compare. Case sensitive.

dependent

Will not validate until fields specified in data-jsv-dependents (comma delimited if more than one) are validated first.

expireddate

Checks if year, month and day (optional) combined field values are in the past. The year field in the form is specified with data-jsv-expiredate="year", month, data-jsv-expiredate="month" and (optional) day data-jsv-expiredate="day". All get the expireddate validator.

Select Month
January
...


Select Year
2019
...

Field values should be numbers like "12" rather than names like "December" (therefore, best used with select boxes).

ajax

An AJAX GET request is made to the endpoint in data-jsv-ajax-endpoint. The field's name is used as the key, and the input as its value.

If the JSON response has the key specified in data-jsv-ajax-key and that matches data-jsv-ajax-value, the field validates.

type="text"
name="Login"
data-jsv-validators="ajax"
data-jsv-ajax-endpoint="/username_check"
data-jsv-ajax-key="usernameAvailable"
data-jsv-ajax-value="true"
/>
If data-jsv-ajax-value is left empty, the input is used to match.

requiremin

Used to validate radio buttons and checkboxes (multiple form elements with the same name). Validates that the minimum number specified in data-jsv-min-selected have been selected. All elements with the same name should have the requiremin validator and the same number in data-jsv-min-selected.

Agree to terms of service?
data-jsv-validators="requiremin"
data-jsv-min-selected="2"
type="checkbox"
name="terms"
value="1"
/>

Agree to more stuff?
data-jsv-validators="requiremin"
data-jsv-min-selected="2"
type="checkbox"
name="terms"
value="2"
/>

Customizing Validation Messages

You can customize the error message for each validator in the field itself. The format is:

data-jsv-field-error-[validator]="[custom error message]"

Example of a custom error messages for validators on a credit card field:

name="cardNumber"
type="text"
data-jsv-validators="require, creditcard"
data-jsv-field-error-require="Please enter a credit card number (no spaces)"
data-jsv-field-error-creditcard="Please check your credit card number"
/>

Looks like this on invalid input:

!enter image description here

Containers and Styling

JSV applies containers and styles automatically. There's nothing you need to do, the exception being radio buttons and some checkboxes (see below).

You can override the styles if you wish. Each form gets an error container with the class validate-form-error-message. Each input field is wrapped in a validation container with the class validate-input so that the it can be styled as valid or invalid. A sibling container with class validate-field-error-message immediately follows, where error messages appear. The CSS is included but can be overridden in your own stylesheet if desired.

!enter image description here

* Multiple form elements with the same name - like radio buttons or multi-value checkboxes - need to have the error message container and validation container (optional) added to the form manually.

Put this container where you want to target your error messages for the group of elements:

Then link each element of the group to the message target by adding the message target's ID to the element's data-jsv-message-target data attribute:

data-jsv-message-target="[YOUR ID NAME]"

Below is a full example of a multi-value checkbox with the error message and the optional validation container specified:

!enter image description here

Form Configuration

The following data attributes can be added to the tag

| Attribute | Description |
|--------------------------|---|
| data-jsv-form="true" (required) | Attaches JSV to the form |
| data-jsv-disable-icons="true\|false" | Toggles field validation icons for all elements of the form |
| data-jsv-disable-invalid="true\|false" | Toggles disabling of the element for valid and invalid form states |
| data-jsv-form-invalid-message="[MESSAGE]" | Message to show in the form-level error container upon submit of an invalid form |
| data-jsv-form-incomplete-tooltip="[MESSAGE]" | Message that appears in a tooltip when customer hovers the element of an invalid form |
| data-jsv-submit-handler="[JAVASCRIPT FUNCTION NAME]" | If you want to handle submit of the form with Javascript, the specified function will be called upon submit of a valid form. It's called with the arguments: event, form (the entire form element) and the string 'valid'. If no function is specified, the form submits normally. |
| data-jsv-form-invalid-callback="[JAVASCRIPT FUNCTION NAME]" | If specified, the function is called when a form is submitted but is not valid. Arguments: event, form (the entire form element) and the string 'invalid'. |
| data-jsv-form-valid-callback="[JAVASCRIPT FUNCTION NAME]"                                                                                                                                                                                                                                                                                          | If specified, the function is called when a form becomes valid. If used, be prepared for the possibility that it can be called many times. Also, this is not to be used as a submit handler. Arguments: event, form (the entire form element) and the string 'valid'.                                                                                                                                                                                          |

Field Configuration

The following attributes can be added to the form field elements (like ):

| Attribute | Description |
|--|--|
| data-jsv-validators="[VALIDATORS]" (required)| One, or a comma-separated list of the validations to add to this field. If multiple, they are evaluated left to right |
| data-jsv-field-error-[VALIDATOR]="[MESSAGE]" | Specify the error message for a particular validator on this field. See Customizing Validation Messages. |
| data-jsv-message-target="[ID]" | Specify a target for field invalid error messages. Required for use with radio buttons and multi-value checkboxes, but can also be used to override default automatic behavior on any field. Details |
| data-jsv-validation-target="[ID]" | Specify a target for field validation container. Recommended for use with radio buttons and multi-value checkboxes, but can also be used to override default automatic behavior on any field. Details |
| data-jsv-disable-icon="true\|false" | Toggles disabling of valid or invalid icon for this field only. |
| data-jsv-debounce="[MILLISECONDS]" | Wait for [MILLISECONDS] before triggering any validations on this field. |
| data-jsv-field-invalid-callback-[VALIDATOR]="[JAVASCRIPT FUNCTION NAME]" | If specified, the function is called when [VALIDATOR] is triggered but is invalid. Arguments: event, form, name, name of the last validation performed, The string 'invalid', the error message.|
| data-jsv-field-valid-callback-[VALIDATOR]="[JAVASCRIPT FUNCTION NAME]"                                                                                                                                                                                                                                                                                          | If specified, the function is called when [VALIDATOR] is triggered and returns valid. Arguments: event, form, name, name of the last validation performed, The string 'valid'.                                                                                                                                                                                                                                                                  |

App Configuration

Further configuration of JSV can be done by declaring a validateOptions object in the window (before JSV instantiates), with a 'cfg' key:

var window.validateOptions = {
cfg: { // config options }
};

Any configuration settings can be customized, though there are only a few that make sense to change:

| Config Key | Description |
|--|--|
| "useCss": true\|false | Toggles injection of the built-in CSS for UI valid/invalid states. If you want to add your own CSS to the window, set to false |
| "useTooltip": true\|false | Toggles enabling of a tooltip that appears over the

element when the form is in an invalid state. |
| "isValidColor": "[HEX COLOR]" | Customize the color for the field valid state. Default: #13bd3a (green) |
| "isInvalidColor": "[HEX COLOR]" | Customize the color for the field valid state. Default: #ff0000 (red) |
| "isValidIcon": "[UNICODE]" | Customize the field valid icon unicode character. Default: \\2713 (checkmark)|
| "isInvalidIcon": "[UNICODE]" | Customize the field invalid icon unicode character. Default: \\2716 (heavy multiplication X) |
| "fieldErrorFont": "[FONT DECLARATION]" | Use unified CSS font "shorthand" format. Default: normal 12px Helvetica, Arial, sans-serif |
| "formShowMessages": true\|false | If false, no form-level error messages will be shown when a form submit is attempted on an invalid form. |
| "safeStringInput": true\|false | If true, all inputted values are passed through a basic XSS sanitizer. |
| "safeEndpoints": true\|false | If true, endpoints can only be relative urls (i.e. no http:// allowed) |
| "ajaxTimeout": [MILLISECONDS] | Time out an AJAX request after [MILLISECONDS]. Default: 8000 |
| "debounceDefault": [MILLISECONDS]                                                                                                                                                                                                                                                                                           | Wait time before any validations are triggered. Allows user to type without being bothered by error messages. Default: 300.                                                                                                                                                                                                                                                                                          |

NOTE If modifying config settings other than the ones above: form and field-level configuration data attributes always takes precedence over config settings.

Custom Validators

You can write your own validators for JSV by declaring a validateOptions object in the window (before JSV instantiates), with a 'customValidators' key:

var window.validateOptions = {
cfg: { // any app config options (see previous section) },
customValidators: {
"[VALIDATOR NAME]": { // name of custom validator
"events": [], // experimental - array of events this validator should fire on, [] = default
"validator": function(field, value, validator) { // required
return new Promise(function(resolve, reject) { // required

// start custom validator code
if (true) {
resolve(); // required();
} else {
reject("[MESSAGE]"); // required, include message in reject
}
// end custom validator code

});
}
}
}
};

Validations are promises, so the custom validation must also be a promise with a resolve and reject. See the bottom of the demo form for a working example of a custom validator.

Callbacks

Callbacks to custom window functions can be configured for the following events:

- Field validator returns invalid
- Field validator returns valid
- Form becomes valid
- Form submit occurs, form is invalid
- Form submit occurs, form is valid

See form and field configuration to see how to specify callback functions, and how they are triggered. Also see examples of usage at the bottom of the demo form.

JSV listens for for and prevents the form submit event to perform a final validation. If the form is valid, it continues submit and the submission happens using the default method and action on the form

Use cases

AJAX form submit - To use AJAX to submit the form, you'll want to configure data-jsv-submit-handler="[FUNCTION]" on the element. When the form submit happens and the form is valid, the function specified in data-jsv-submit-handler is called with the arguments: event object, form object and the string 'valid'.

Username does not exist - Let's assume you're working on a user login form and you want to set up an AJAX validator to check that the username entered exists before the form is even submitted. A potential use for the "field invalid" callback on the ajax validator is: if the username does not exist, call a function that performs UI changes to direct the user to the sign-up form.

Testing

There is an E2E test suite that uses Jest and Puppeteer. To perform the tests on the demo form, you can run the following commands:

git clone https://github.com/tarponjargon/js-simple-validations.git
cd js-simple-validations
npm install
npm test

Acknowledgements

The idea behind JSV is to basically mimic some of the functionality of ember-cp-validations using vanilla JS.