Jel.FormValidator

Powerful form validation that's easy to implement.
Examples forms, and advanced techniques.

Example Forms

The following examples demonstrate how to apply the Jel.FormValidator to three XHTML forms in different ways. Each example comprises a sample form to interact with, followed by the JavaScript code used to apply the validator. For reference, the validation classes attached to each field are displayed in the title for each (mouse over each field to view).

If you haven't yet done so, it might be good to read Jel.FormValidator and XHTML to understand how to setup your forms to ensure the validator works correctly; most of the required setup steps are standard best-practices for XHTML forms, but there are some workarounds that JEL uses in special cases.

For each example, try hitting "submit" before filling anything in, and then observe the behaviour as you correct errors, try to submit again, and so on.

---

Example 1: Default Behaviours

A validator is created on the following form with no customisation at all, using a simple one-line constructor call. The default way to present the results of form validation is to show an alert box.

Title: *

Please Select Mr Mrs Miss Ms Dr

Given Name: *

Family Name: *

Date of Birth: *

Gender: *

Male Female

The Code

this.validatorEg1 = new Jel.FormValidator($('form-eg-1'));

Features to observe

• Try entering an invalid date in the Date of Birth field. The text in the alert box is formatted in as clear a manner as possible, with text that left-aligns across wrapped lines. This is not exactly trivial to build yourself given the basic nature of JavaScript alert boxes.
• The first culprit in a failed validation is focused and selected (if selectable), making forms highly keyboard accessible.
• Inline validation is active by default - as you correct errors and then tab out of (blur) each field, the culprit status is removed, giving better feedback about successful entry.
• Inline validation does not mark required fields as culprits when they are empty, so that fields aren't marked invalid if you are simply tabbing through quickly. Displaying culprit status on empty required fields is left for the actual attempted submit instead.

---

Example 2: Results container, inline error messages, and field comparisons.

This example form introduces a container element for validation results, inline error messages, and an equality comparison between Password and Confirm Password. Note that inline error messages are actually active by default, but will only show up if there are DOM elements setup to contain them, which is the case here. The default way to do this is to provide each field with an element with the same ID as the field but suffixed with "-inline" (the suffix can be changed if desired, in the constructor options hash).

Title: *

Please Select Mr Mrs Miss Ms Dr

Given Name: *

Family Name: *

Date of Birth: *

Gender: *

Male Female

Password: *

Confirm Password: *

The Code

this.validatorEg2 = new Jel.FormValidator ( $('form-eg-2'), { resultsContainer: $('form-eg-2-results') } );

---

Example 3: Extending Jel.FormValidator

This advanced example illustrates how you can extend the FormValidator class itself to suit requirements specific to your site. Try to submit the form below with some required fields missing and notice the way that the container <div> around both the label and field is highlighted. This functionality is not directly supported by Jel.FormValidator; only fields and attached labels are marked as culprits automatically. This makes sense, given that everyone (hopefully) builds forms by marking up the fields inside, and attaching <label> elements to each via the for attribute, but not everyone will markup the container elements in the same way.

Inspired by techniques discussed in Justin Palmer's excellent article Avoiding Bloat in Widgets, Jel.FormValidator was structured to allow developers to extend its functionality through subclassing; classes in Jel are able to be subclassed because they extend the Base object in Dean Edwards Base library. See the code below for specific details on how this is achieved.

Title: *

Please Select Mr Mrs Miss Ms Dr

Given Name: *

Family Name: *

Date of Birth: *

Gender: *

Male Female

The Code

In this particular example, we create a Site.FormValidator by extending Jel.FormValidator, and overriding the methods displayCulprit, releaseCulprit, and constructor, as shown below. Note that each call to this.base is the mechanism for calling the super-class method, made possible by Dean Edwards' Base.

Site.FormValidator = Jel.FormValidator.extend ({ constructor: function(form, options) { // override base constructor so that all Site.FormValidator // objects use a results container with ID equal to the form's ID // suffixed with "-results" this.base ( form, { resultsContainer: $(form.id + '-results') } ); }, displayCulprit: function(field, isInline) { // call the base method, which marks the field and label as a culprit this.base(field, isInline); // find the container div of class "container-field" // and mark it as a culprit too var container = Element.findParent(field, "div.container-field"); if (container) { container.addClassName("culprit"); } }, releaseCulprit: function(field, isInline) { // call the base method, which removes culprit status from // the field and label this.base(field, isInline); // find the container div of class "container-field" and // remove its culprit status too var container = Element.findParent(field, "div.container-field"); if (container) { container.removeClassName("culprit"); } } });

Once this class is setup, we simply apply our new specialised class to the example form:

this.validatorEg3 = new Site.FormValidator($('form-eg-3'));

Return to manual index