Jel. FormValidator

Provides unobtrusive client-side validation behaviour to an HTML form, via recognition of special CSS class strings (validation classes) attached to each field. Includes customisation options for how to display the validation errors (results), how to change the display of “culprit” fields and their labels (through css classes) and also the option to display these errors adjacent to each field in “inline” containers (on field blur). Error messages are automatically generated through use of internationalizable error template strings, but can also be entirely customized if the automatic messages are insufficient. See below for terminology used within this documentation.

Terminology

culprit	A culprit field is a field that has been deemed not valid when validating the form it belongs to.
results	The results of the form validation refers to the information gathered about the culprits during that validation (if any, that is, if validation fails). Displaying the results usually refers to displaying the error messages that describe what is wrong with each culprit field to the person filling in the form.
validation class	the special CSS classes that are applied to form elements which describe rules for them to be valid. Many pretermined classes are available to use, or you can define your own custom validation classes (functions) and associated error templates (see below).
error template	a string template resource linked to each validation class that defines the error message to show when that validation rule fails. For custom validation classes, an equivalent error template needs to be defined also.
error message	the message for each culprit field describing why validation has failed. (this is the “filled-in” version of the error template for the validation class rule that has not been satisifed).
inline validation	if activated, individual fields will be validated on blur. If this validation fails, an inline error message (a variation of the standard error message, without the field label) will be placed inside the associated inline (see below)
inline	an optional container element defined for each field (typically adjacent to it in the DOM) that will be filled with any inline error messages generated during inline validation.

Validation Classes

The validation classes recognised by Jel.FormValidator are specified in the class attribute of each field in the form being validated. The range of supported classes is quite extensive and automate validation of many conditions that you previously would have written custom code for. Not only that, but all of the validation classes are able to build readable error messages that describe what went wrong to the user. They can be be placed into 4 major categories:

required	the special case of a field simply being required
length based	checks the character length of a field against a specified value, or lower and upper values
value based	checks the value of a field against a specified comparison value, or upper and lower value, or even another field value
pattern based	special cases such as email addresses

It’s also important to note that most of these validation classes are derived from the function names in the Jel.Validator class, and they call out to those functions to check fields.

The “required” validation class

To mark a form field as being required (that is, a value must be provided to be able to submit the form), simply add the class “required” to the class attribute of the field.

Length-based validation classes

Length based classes check that a field in the form matches a certain character length condition. These follow the format length-OPERATOR-COMPARE where:

OPERATOR	is the comparison operator being performed (see below)
COMPARE	the comparison length value, or lower and upper value if OPERATOR is “range”

Values for OPERATOR

eq	equality comparison (==)
neq	inequality comparison (!=)
lt	less than (<)
gt	greater than (>)
le	less than or equal to (<=)
ge	greater than or equal to (>=)
range	between lower and upper bound (in a...b)

Values for COMPARE

a	where a is an integer, if OPERATOR is not “range”
a:b	where a and b are integers representing lower and upper bounds if OPERATOR is range, and you want the bounds to be non-inclusive
a::b	as above if OPERATOR is range, and you want the bounds to be inclusive

Examples of length-based validation classes

length-gt-5 - field length must be greater than (gt) 5 characters
length-eq-5 - field length must be equal to (eq) 5 characters
length-range-5:10 - field length must be between 5 and 10 characters, non-inclusive (:)
length-range-5::10 - field length must be between 5 and 10 characters, inclusive (::)

Value-based classes

Value-based classes check a field’s data type and value compared to another value, or lower and upper values if the operator is a range. These values can either be constant, or can specified as the values of other fields in the form. These follow the format [TYPE-]OPERATOR-COMPARE-FORMAT where:

TYPE	is the data type that is expected in this field.
OPERATOR	is the comparison operator being performed.
COMPARE	is the value, upper and lower value, or even another field to be compared
FORMAT	is the date format when TYPE is “date” or “time”

Refer to the reference below for possible values of each of these attributes.

Values for TYPE

empty (not specified)	for strings, that is, no type check really occurs at all
int	for integers
float	for floating point numbers, that is, they have decimals
numeric	for int or float
date	for date strings. When specifying a date, the FORMAT must also be specified
time	synonym for “date”. This is more readable when you’re using a time format

Values for OPERATOR

The same as for length-based classes, with the extra exceptions:

(int\|float\|numeric)-positive	a positive number
(int\|float\|numeric)-negative	a negative number
date-future-FORMAT	a date string in the future in FORMAT
date-past-FORMAT	a date in the past in FORMAT
time-earlier-FORMAT	a time earlier than the current time time-later-FORMAT- a time later than the current time

Values for COMPARE (comparing constants)

The syntax for COMPARE follows the same rules as for length-based comparisons, but for different types, that is:

a	where a is an appropriate type (see below), for a single value comparison
a:b	where a, b are an appropriate type (see below), for “range” lower and upper bounds (non-inclusive)
a::b	where a, b are an appropriate type (see below), for “range” lower and upper bounds (inclusive)

Types are represented like so

TYPE is empty (string)	whatever string you want to compare
TYPE is int	an integer
TYPE is float	an integer, followed by lowercase “p” (for point), then another integer for decimal part. E.g. 3p14159
TYPE is date	a representation of a date in the format yyyymmdd (e.g. 20070403) for just a date, and yyyymmddThhmmss for date AND time. (e.g. 20070403T133000)
TYPE is time	a representation of a time in the format hhmmss (e.g. 133000)

Values for COMPARE (when comparing other fields)

If you want to compare the value of the field with another one in the same form, simply substitute the constant in the class string with the ID of the field(s) to compare, followed by the suffix in the “suffixCompareField” in Options hash of the constructor (by default this is “-field”).

Values for FORMAT (only appropriate for “date” and “time” types)

a dash-delimited version of a property identifier for the formatting constants in Jel.Date.FORMAT. E.g. date-future-uk (Jel.Date.FORMAT.UK), date-future-uk-12 (Jel.Date.FORMAT.UK_12)

Examples of value-based validation classes

int-ge-4                             - integer greater than or equal to 4
int-range-4:8                         - integer between 4 and 8, non-inclusive
float-range-4p5:20p1                  - floating point, between 4.5 and 20.1
neq-password                          - not equal to "password" case-sensitive
eq-password-field                     - equal to the value of the field with ID "password" (useful for confirm password)
gt-ci-a                               - greater than "a", case-insensitive
lt-b                                  - less than "b", case-sensitive
date-future-uk                        - UK formatted date (dd/mm/yyyy) in the future
date-ge-20000101-us                   - US formatted date (mm/dd/yyyy) sometime after the turn of the millenium (1st Jan 2000)
date-range-uk-20050201::20070301      - UK formatted date between 1st Feb 2005 and 1st Mar 2007, inclusive

Hopefully it’s clear from the rules above that they are a lot easier to construct than they are to explain!

Summary

Jel. FormValidator	Provides unobtrusive client-side validation behaviour to an HTML form, via recognition of special CSS class strings (validation classes) attached to each field.
Properties
form	The HTML form associated with this validator.
fieldLabels	A hash of field labels (the text, not the label elements themselves) indexed by the ID of the related control.
Functions
constructor	Class constructor.
registerErrorMessage	Registers a custom error message and custom inline error message for a given fieldId, and className (validation class).
disableFields	Prevents the specified fields from being regarded in form validation.
enableFields	Causes the specified fields to be regarded in form validation once again.
disableFieldByName	Prevents the fields with the specified name from being regarded in form validation.
enableFieldByName	Causes fields with the specified name to be regarded in form validation once again.
addFields	Registers the specified fields to be validated by the form validator.
removeFields	Removes the specified fields from the form validator.
displayCulprit	displays a given field as a validation culprit.
releaseCulprit	displays a given field as being valid, that is, NOT a validation culprit.
displayInline	displays an inline element for a validation culprit.
releaseInline	hides an inline element for a field that is likely no longer a validation culprit.
classedCulprit	checks if a given field is currently classed as a culprit (via CSS)
addCulprit	Marks the given field as a culprit field in the validation results.
submit	Attempts to submit the form associated with this validator, by running all validation, and submitting if successful.
validate	Validates the form associated with this validator, and sets up validation results.
displayCulprits	Displays all of the current culprit fields for the latest validation.
releaseCulprits	Shows all of the form fields as non-culprit.
showResults	Displays the results of the validation, based on options specified in the constructor method.
hideResults	Hides the results of the validation, and also any inlines associated with previous validations (if visible).
showResultsAlert	The method called to display the validation results as a JavaScript alert, if the options specify this (see constructor for more).
showResultsList	The method called to display the validation results inside a DOM container (controlled via the resultsContainer option in constructor).
hideResultsList	The method called to hide the DOM container that validation results are displayed in (controlled via the resultsContainer option in constructor).
formatFieldLabel	The default method for formatting a field label when displaying them in validation error messages or inline error messages.
formatDateFormat	The default method for formatting date format strings when displaying them in validation error messages or inline error messages.
validateField	Validates a single given field in the form associated with this validator, and sets up the results for just this field.
checkField	Checks if a given field is valid within the form associated with this validator.
isFieldEmpty	Checks if a given field is “empty” within the form. For textareas and text inputs, this is when the field value is the empty string.
getInline	Gets the inline error message container for a given field.

constructor

constructor: function( form,
options )

Class constructor.

Parameters

form	HTML Form Element, the form to apply form validation behaviour to
options	hash, a hash of options to configure the validator (see below)

Options available (specified in options hash)

callbacks	hash, a collection of optional callbacks to customise the behaviour of the form validator (see below)
validators	Hash, a collection of custom validators to use for this form, indexed by the camelized class names that they match (for example, a “user-name” class would be indexed “userName” in this hash)
errorTemplates	Hash, a collection of errorTemplates to use for any custom validators in validators (each validator requires an error template), indexed by the uppercase-underscore-delimited version of the class name (for example, a “user-name” class would be indexed “USER_NAME” in this hash)
culpritFieldClassName	String (default “culprit”), the class name to apply to fields that are responsible for the form not validating (termed ‘culprits’)
culpritLabelClassName	String (default “culprit”), the class name to apply to the labels of culprit fields
selectEmptyValue	String (default “”), the value of a select field that is regarded as empty (that is, not yet chosen)
validateInline	Boolean (default true), indicates whether single field validation should occur on each field’s onblur event, and be displayed in associated “inline” elements
suffixCompareField	String (default “-field”), the suffix used to describe field comparisons in validation classes
suffixInline	String (default “-inline”), the suffix added to a field ID to determine the ID of an “inline” container, used to display inline error messages for that field
resultsContainer	HTML Element, if specified, the form validator will build an XHTML error message inside this container, which consists of an intro paragraph, followed by an unordered list of all error messages)
resultsAlert	Boolean, if true the form validator will display a nicely formatted JavaScript alert box showing your errors. This will also occur by default automatically if no other display has been specified, that is if both options.callbacks.onShowResults and options.resultsContainer are not specified.

Callbacks available (specified in options.callbacks hash)

formatFieldLabel(label, field)	If specified, the string this function returns will be used as the field label when it is shown in error messages
formatDateFormat(format)	If specified, the string this function returns will be used as a date format when they are shown in error messages
onShowResults(results, validator)	If specified, will be called when displaying the results of a validation (only occurs is there are problems). Refer to showResultsAlert for information on the results parameter.
onValidate(validator)	If specified, this will be called after regular field validation has occurred, to allow you to perform any custom validation (return false if not the form is still not valid, true otherwise)
onSubmit(validator)	If specified, this function will be called once all validation is successful, but before the form is submitted. Return false to prevent form submission, and true to let it through. Preventing form submission (returning false) could be an approach for AJAX applications that hijack a standard form submit.

Example

var validator = new Jel.FormValidator
(
    $('contact-form'),
    {
         callbacks:
         {
              formatFieldLabel: function(label)
                                {
                                    return '<em>' + label.replace(/[:\*]/g, '') + '</em>';
                                },

              onSubmit: function(validator)
                        {
                            this.sendAjaxRequest(Form.serialize(validator.form));
                            return false;
                        }
         }
    }
);

validator.registerErrorMessage(
$('username'),
"length-ge-6",
"Username must be at least 6 characters long",
"must be at least 6 characters long"
);

validator.disableFields("billing-address", "billing-state", "billing-post-code", "billing-city", "billing-country");
// suppose you had a checkbox labelled "use shipping address" which disabled billing address fields
// which you wanted to disregard in validation

new Insertion.Top($("extra-credentials"), "<label for="alternate-username">Alternate Username:</label>" +
"<input id="alternate-username" anme="alternate-username" class="length-ge-7" />" +
"<div id="alternate-username-inline" class="inline"></div>");

validator.addFields($("alternate-username"));

if (parseInt($('percentage-male') + parseInt($('percentage-female'))) != 100)
validator.addCulprit($('percentage-male'), "Percentage Male and Female must total to 100 percent", "Must total to 100 percent");

Jel. FormValidator

Terminology

Validation Classes

The “required” validation class

Length-based validation classes

Values for OPERATOR

Values for COMPARE

Examples of length-based validation classes

Value-based classes

Values for TYPE

Values for OPERATOR

Values for COMPARE (comparing constants)

Types are represented like so

Values for COMPARE (when comparing other fields)

Values for FORMAT (only appropriate for “date” and “time” types)

Examples of value-based validation classes

Properties

form

fieldLabels

Functions

constructor

Parameters

Options available (specified in options hash)

Callbacks available (specified in options.callbacks hash)

Example

registerErrorMessage

Parameters

Example

disableFields

Parameters

Example

enableFields

Parameters

Example

disableFieldByName

Parameters

Example

enableFieldByName

Parameters

Example

addFields

Parameters

Reason for this method

Example

removeFields

Parameters

Example

displayCulprit

Parameters

Example

releaseCulprit

Parameters

Example

displayInline

Parameters

Example

releaseInline

Parameters

Example

classedCulprit

Parameters

addCulprit

Parameters

Example

submit

Example

validate

displayCulprits

releaseCulprits

showResults

Parameters

Results Hash

hideResults

Parameters

showResultsAlert

Parameters

showResultsList

Parameters

hideResultsList

Parameters