Form validation

Looking for WET v3.1?

As of September 23, 2014, version 3.1 of the Web Experience Toolkit is no longer supported. The source code and documentation have been moved to the wet-boew-legacy repository.

Questions or comments?

Purpose

This component provides generic validation and error message handling for Web forms.

Use when

Working example

How to implement

  1. Add class="wb-frmvld" to a div element surrounding the form element 
    <div class="wb-frmvld">
	<form action="#" method="get" id="validation-example">
	...
	</form>
  2. Optional: Wrap each form field name with <span class="field-name">...</span>. This specifies the prefix to use for the error message summary. 
    <label for="fname1">
	<span class="field-name">First Name</span> <strong>(required)</strong>
</label>
  3. Add required="required" to each mandatory form field 
    <input id="fname1" name="fname1" type="text" required="required" />
  4. Optional: For input fields, add one of the configuration options for specialized validation.

Configuration options

Option Description How to configure Values
hdLvl Heading level for error summary. Add "hdLvl": "headingLevel" to the data-wb-frmvld attribute where headingLevel is the heading level. Use the following JavaScript code instead to configure all instances of the plugin: window[ "wb-frmvld" ] = {"hdLvl": "headingLevel"};.
h2 (default):
Heading level 2
h3:
Heading level 3
h4:
Heading level 4
h5:
Heading level 5
h6:
Heading level 6
ignore Selector identifying the fields to ignore. Add "ignore": "selector" to the data-wb-frmvld attribute where selector is a valid jQuery selector. Use the following JavaScript code instead to configure all instances of the plugin: window[ "wb-frmvld" ] = {"ignore": ".ignore"};.
:hidden (default):
All hidden fields
.ignore:
All fields with the ignore class
Empty string ("")
None of the fields

Specialized validation

Add specialized validation to an input field by applying the following options.

Option Validtion type
data-rule-alphanumeric="true" Alphanumeric
type="date" Date
type="date" data-rule-dateISO="true" Date (ISO)
type="number" Digits only
data-rule-lettersonly="true" Letters only
data-rule-letterswithbasicpunc="true" Letters and basic punctuation only (allowed punctuation: [.])
data-rule-maxlength="x" Maximum length of x
max="x" Maximum number x
data-rule-minlength="x" Minimum length of x
min="x" Minimum number x
type="email" Email
data-rule-rangelength="[x,y]" Range length x to y
type="tel" data-rule-phoneUS="true" Telephone number (US)
type="time" Time
type="url" URL (IPv4)
type="url" data-rule-ipv6="true" URL (IPv6)

See jQuery Validation Plugin - Documentation for more details.

Events

Document the public events that can be used by implementers or developers.

Event Trigger What it does
wb-init.wb-frmvld Triggered manually (e.g., $( ".wb-frmvld" ).trigger( "wb-init.wb-frmvld" );). Used to manually initialize the form validation. Note: The Form validation plugin will be initialized automatically unless the form elements are added after the page has already loaded.
wb-ready.wb-frmvld (v4.0.5+) Triggered automatically after form validation initializes. Used to identify the element where form validation has initialized (target of the event) 
$( document ).on( "wb-ready.wb-frmvld", ".wb-frmvld", function( event ) {
});
$( ".wb-frmvld" ).on( "wb-ready.wb-frmvld", function( event ) {
});
wb-ready.wb (v4.0.5+) Triggered automatically when WET has finished loading and executing. Used to identify when all WET plugins and polyfills have finished loading and executing. 
$( document ).on( "wb-ready.wb", function( event ) {
});

See jQuery Validation Plugin - Documentation for details about events specific to jQuery Validation.

Source code

Form validation source code on GitHub

Date modified: