Form validation

Pattern Library uses the open source jQuery Validation Plugin for client-side form validation. Additional UX enhancements are included in coc.forms.js. These enhancements are based off the Web Experience Toolkit’s validation UX and include a summary alert banner and styled inline alerts.

Demo

Try to submit the button below. JavaScript will relay feedback if any fields are incorrectly filled in.

How to use

1. Load the 3 JavaScript files to your page and call one of the initialization lines:


<script src="js/jquery-2.2.4.min.js"></script>
<script src="js/jquery.validate.min.js"></script>
<script src="js/coc.forms.js"></script>
<script>
    $( document ).ready( function() {
        // Use the following line to initialize the validation AND
        // generate enhanced form controls (generates individual 'clear' and 'show password'
        // button controls for supported .form-control elements)
        COC.Form.init();
        // OR use the following line to initialize the validation ONLY
        COC.Form.initValidation();
    });
</script>

2. Add this data attribute to any forms you wish to apply validation: data-pl-frm-vld="true".


<!-- Example form with the data-attributes for validation AND enhanced form controls -->
<form class="form-width-md" data-pl-frm-vld="true" data-pl-frm-ctrl="true">
    ...
</form>

<!-- Example form with ONLY the data-attribute for validation -->
<form class="form-width-md" data-pl-frm-vld="true">
    ...
</form>

Supported validation rules

Below are some of the supported validation rules that can be applied to an input field.

Attribute	Code example	Description
`required aria-required="true"`	`<input type="text" class="form-control" required aria-required="true" ...>`	A value for the input is required.
`type="email"`	`<input type="email" class="form-control" ...>`	The input must be a properly formatted email address.
`data-rule-equalTo="#x"`	`<input id="password1" type="password" class="form-control" ...>` `<input id="password2" type="password" class="form-control" data-rule-equalTo="#password1" ...>`	The input must be exactly equal to the value of the input whose id equals "x". This attribute is particularly useful for confirming passwords upon an account creation.
`minlength="x"`	`<input type="text" minlength="1" class="form-control" ...>`	Minimum number of characters for the input
`maxlength="x"`	`<input type="text" maxlength="255" class="form-control" ...>`	Maximum number of characters for the input
`type="number"`	`<input type="number" class="form-control" ...>`	The input must be a number.
`type="number" min="x"`	`<input type="number" min="0" class="form-control" ...>`	Minimum numerical value for the input.
`type="number" max="x"`	`<input type="number" max="999999" class="form-control" ...>`	Maximum numerical value for the input.
`type="number" min="0" max="999999"`	`<input type="number" min="0" max="999999" class="form-control" ...>`	Minimum and maximum numerical value for the input.

Unable to use the validation plugin?

If your project will be using its own form validation plugins or custom scripts, keep the following validation functionality in mind:

Display an inline-alert below the input field if there is an error.
Generate an alert banner at the top of the form to list out and link to each form error.
For accessibility, if the user submits the form with errors, the alert banner should receive focus. This allows the user to see all of the form errors from a high-level.
Once an error has been fixed, remove the corresponding error messages.

Validation state examples

The following may be used as reference for how the validation feedback is structured and styled.

Example invalid state

Code


<form class="form-width-md">
    <section id="errors-validation-example" class="alert alert-danger" tabindex="-1">
        <h2>The form could not be submitted because 1 error was found.</h2>
        <ul>
            <li><a href="#{{ Input id }}"><span class="prefix">Error&nbsp;1: </span>{{ Label }} - {{ Validation message (e.g. Please enter a valid email address.) }}</a></li>
        </ul>
    </section>

    <div class="form-group">
        <label for="{{ Input id }}">{{ Label }} <span class="label-required">(required)</span></label>
        <input id="{{ Input id }}" name="{{ Input name }}" type="email" class="form-control error" value="{{ Value }}" aria-describedby="{{ Validation message id }}">
        <span id="{{ Validation message id }}" class="form-vld-msg error">
            <span class="prefix">Error&nbsp;1: </span>{{ Validation message (e.g. Please enter a valid email address.) }}
        </span>
    </div>
</form>

Example success state

In most cases, the success state does not need to be displayed. Example usage could include confirmation that:

an email address or username is unique to the database
a street address is valid

Note: The validation plugin does not relay success feedback. To showcase the success validation, custom adjustments to the JavaScript will be required.

Code


<form class="form-width-md">
    <div class="form-group">
        <label for="{{ Input id }}">{{ Label }} <span class="label-required">(required)</span>
        </label>
        <input id="{{ Input id }}" name="{{ Input name }}" type="email" class="form-control valid" value="{{ Value }}" aria-describedby="{{ Validation message id }}">
        <span id="{{ Validation message id }}" class="form-vld-msg valid">{{ Validation message (e.g. Valid) }}</span>
    </div>
</form>