A jQuery plugin for client-side validation of html forms.
Introduction
provejs-jquery is a client-side form validation plugin:
- Input validators are jQuery plugins.
- Input decorators are jQuery plugins.
- Validators share data with decorators via events.
- Validators can be:
- synchronous - return result immediately.
- asynchronous - return jquery deferred which returns result later.
- Delegated events to the form so the form DOM can be modified at anytime.
- Explict control over configuration options via dynamic booleanators.
- Modular design via a suite of jQuery utility plugins.
- Live and form submit validation.
- Stateful validations.
- Input sanitization.
- Meets accessibility standards Section 508 and WCAG 2.0 (A, AAA, AAAA).
- Open source MIT license.
Table Contents
Install
You can install provejs-jquery
in your project using npm
or directly downloading the distribution files.
npm install provejs-jquery --save-dev
After using using npm install you should include the distribution files in your project's build process.
Examples
Please see examples folder.
Prove Options
Prove Options
Prove accepts only a single options config.
form.prove({ debug: false, fields: { // see fields options below }, submit: { // see submit options below } });
debug
- Type: bool,
- Required: false,
- Default: false,
- Description: will print out debug info in the developer console.
fields
- Type: object,
- Required: true,
- Description: defines the field validations to be performed. See below for more details.
submit
- Type: object,
- Required: false,
- Description: defines the submit intercept handler options. See below for more details.
Field Options
form.prove({ fields: { field1: { debug: false, enabled: true, selector: '[name="field1"]', trigger: 'click change', stateful: true, sanitize: true, group: false, validators: { // see validator options } }, field2: { // ... }, field3: { // ... } } });
debug
- Type: bool
- Required: false,
- Default: false,
- Description: will print out some debug info in the developer console. Debug defaults to false.
enabled
- Type: booleanator,
- Required: false,
- Default: true,
- Descrption: will enable the field for validation. A value of ':visible' will only validate the input if the input if visible. A booleanator is something (bool, selector, sudo-selector, function) that evaluates to either true or false. So for example, you specify enabled: ':visible' and the field config will be enabled when the input is visible. Or perhaps, enable validation when the input is not empty by setting enabled to ':filled'.
selector
- Type: string,
- Required: false,
- Default: '[name="field"]',
- Description: jQuery selector which you can shift the context of the validation.
trigger
- Type: string or false,
- Required: false,
- Default: 'change keyup click blur',
- Description: The events on which you want to live validation to happen. A value of false will disable live validation. The default value for trigger changes on two conditions 1) input type and 2) if the input is already in the form DOM at the time
form.prove()
is called. In other words, if you are dynamically inserted your form inputs afterform.prove()
than you should specify the event trigger values. If you are not dynamically inserted form inputs than you can all prove to determine the live event triggers. See $.fn.proveTriggers() for details on the default triggers.
throttle
- Type: int,
- Required: false,
- Default: 0,
- Description: The number of milliseconds to throttle (aka debounce) live validation.
stateful
- Type: bool,
- Required: false,
- Default: true,
- Description: provejs-jquery is a stateful validator. You can disable stateful validation by setting stateful to false. Prove hashes the input value to determine if the input value has changed since last validation. Prove does this stateful validation without keeping a DOM reference to any inputs.
sanitize
- Type: bool or string,
- Required: false,
- Default: false,
- Description: provejs-jquery can sanitize your input values. provejs-jquery has a default sanitizer plugin ($.fn.sanitize) which replaces common MS Word unicode characters with their equivalent ASCII characters. You can replace the default sanitizer plugin with your own or specify a specific sanitizer for each input field using a string value which represents the plugin name.
group
- Type: bool,
- Required: false,
- Default: false for all but radio inputs,
- Description: should provejs-jquery validate the found inputs as a group or validate the found inputs indivdually.
Validator Options
Prove has a powerful set of validators. A validator is just a jquery plugin. See validators for more information.
form.prove({ fields: { field1: { validators: { proveRequired: { debug: true, // optional (bool), defaults to false enabled: true, //optional (booleanator), defaults to true message: 'Message to pass to the decorator.' }, provePattern: { regex: /^[my regex pattern]$/, message: 'Message to pass to the decorator' }, // ... } }, field2: { // ... }, field3: { // ... } } });
Each validator has it's own set of options but below is a set of the common options to all prove validators.
debug
- Type: bool,
- Required: false,
- Default: false,
- Description: Will enalbe the validator to print debug information in the developer console.
enabled
- Type: booleanator,
- Required: false,
- Default: true,
- Description: enable or disable validation depending on the value of the booleanator.
message
- Type: string,
- Required: true,
- Description: This string is passed into the validator which allows your custom validators to modifiy it. Utlimately, this string value is passed to the decorators via the event data.
Submit Options
provejs-jquery uses a submit intercept handler which ensures successful form validation before allowing the form to submit. The submit intercept handler is bound by default to form.on('click', ':submit', handler)
so really the intercept handler is really a click handler. The submit intercept handler accepts the following options:
form.prove({ fields: {}, submit: { selector: 'button:submit', validate: true, enabled: true, } })
Where:
debug
- Type: bool,
- Required: false,
- Default: false,
- Description: Will enalbe the submit intercept handler to print debug information in the developer console.
selector
- Type: - string,
- Required: - false,
- Default: - 'button:submit',
- Description: - jquery selector used to bind the submit intercept handler.
validate
- Type: - booleanator,
- Required: - false,
- Default: - true,
- Description: - determines if validation should happen when the intercept handler is invoked. If you want the form to submit without validation then set this to a value of false, 'button:submit:not('.skip-validation')' and add class 'skip-validation' (see booleanator) or your code could just call `form.submit()'.
enabled
- Type: - booleanator,
- Required: false,
- Default: true,
- Description: Enables the form to submit after it validates true.
Should you want to stop the normal form submission you will need to bind a handler to the form submit event:
form.submit(function(event){ event.preventDefault(); // stop form submit //do something else, like ajax submission of form });
Should you want to have a form with no submit button you will need to submit the form via ajax. You can do this by adding a form submit handler.
form.submit(function(e) { // stop form from submitting without validation e.preventDefault(); // validate entire form var url = '/your/server/path'; var dfd = form.validate(); var data = { field1: field1.val() }; // wait for validation to complete dfd.done(function(isValid){ if (isValid !== false) { // submit data via ajax $.post(url, data); // update ui here } }); });
Prove Validators
Input validation is handled by jQuery validator plugins.
Prove Decorators
Form decoration is handled by jQuery decorator plugins.
Prove Methods
The form will automatically be validated when the user clicks the submit button. However, you can programatically validate the form:
var dfd = form.validate(); dfd.done(function(isValid){ console.log('validation', isValid); });
Your code can also validate an input.
input.validate(); //returns chainable input reference
If you want to by pass validation and immediately submit the form:
form.submit();
Prove Events
Prove is a publisher of events. Events are triggered on either the input or the form to share data with the decorators.
- status.form.prove - triggered on the form
- status.input.prove - triggered on the input
Please see events for more details.
Destroy
You can remove the Prove plugin by either:
form.data('prove').destroy();
or
form.remove();
Booleanator
Many of the Prove options are booleanators. A booleanator is a dynamic configuration option which is evaluated by Prove immediately before it is used. It can be defined as either:
- Bool:
- Evaluation: uses the bool value.
- Values: true or false,
- jQuery DOM Selector:
- Evaluation: if the DOM selection returns any elements then it evaluates to true otherwise false.
- Context: the context of the DOM selection is the window.document.
- Examples: 'fieldset#section:visible', 'input[type="hidden"]:empty', '#other-checkbox:checked'
- jQuery DOM Pseudo-Selector:
- Evaluation: if the DOM selection returns any elements then it evaluates to true otherwise false.
- Context - the context of the DOM selection is the input.
- Examples: ':visible', ':empty'
- Javascript Function:
- Evaluation: function should return either true or false and accepts no inputs.
- Example: function(){ return window.myVar; }
To illustrate the power of a booleanator consider the following example where the user is required to enter EITHER a phone number or email address:
form.prove({ fields: { email: { validators: { proveRequired: { enabled: '[name="phone"]:blank', //<=== booleanator message: 'Please enter the contact email or phone number below.' }, provePattern: { regex: patterns.commons.email, message: 'Please enter a valid email address.' } } }, phone: { validators: { proveRequired: { enabled: '[name="email"]:blank', //<=== booleanator message: 'Please enter the contact phone or email address above.' }, provePattern: { regex: patterns.commons.phone, message: 'Please enter a valid phone number.' } } } } }); form.decorate('bootstrap');
Contributing
Setup
npm install grunt npm install grunt-eslint npm install grunt-contrib-concat npm install grunt-contrib-uglify
Lint
grunt lint
Build
grunt build
Roadmap
NPM
http://blog.npmjs.org/post/112712169830/making-your-jquery-plugin-work-better-with-npm
Mailcheck
https://github.com/mailcheck/mailcheck#usage-without-jquery
Unobtrusive Configuration
Perhaps support unobtrusive configuration via $.fn.proveConfig().
var options = form.proveConfig(); form.prove(options); // or if you dynamically insert an input, but for some reason did not already config the field input.proveConfig();
Unit Tests
Need unit tests.
- http://qunitjs.com/
- https://www.sitepoint.com/unit-test-javascript-mocha-chai/
- https://github.com/rstacruz/jsdom-global
- http://digitalbush.com/2011/03/29/testing-jquery-plugins-with-node-js-and-jasmine/
- https://gist.github.com/yairEO/d281bf017d203556f96c
- https://github.com/Verba/jquery-readyselector/blob/master/test/jquery.readyselector_spec.js
- https://sean.is/writing/client-side-testing-with-mocha-and-karma/
- http://codeutopia.net/h/subscribe/
- https://coderwall.com/p/qaebwq/running-mocha-tests-without-a-browser-not-even-phantomjs
FAQ
Create an FAQ of frequenty asked questions and answers.