Copyright (c) 2001, 2002, 2003, 2004, Paul Strack.
FormValidation.js. The document is
broken down into the following sections:
This library attempts to address these issues by standardizing and automating as much form validation process as possible. The library's functionality rests on two key objects:
validations: An object that holds validation information for the entire form.
formdata: An object with simple getter/setter methods for manipulating form data.
Common Validation Operations: The page developer
specifies the properties of the
(validation properties) to control how individual fields in
the form are validated. The validation properties are used during
onload event to initialize form and field
validation functions. For example, to mark a field as required, the
developer simply sets:
Validation Event Handlers: This library automatically
assigns validation functions to the appropriate event handlers of
onchange for text elements,
onchange/onblur for select lists,
for radio buttons and checkboxes and
onsubmit for the
form itself. The web developer does not need to assign any form
element event handlers.
Getting and Setting Field Values: The
formdata object's methods can be used to manipulate
field data. The
formdata object has
methods for every field. If a form has an "
field, it can be manipulated via
methods. Furthermore, the
parses the field value to a specified data type and the
setField() method formats the value as
appropriate when assigning it to the field. Typically, the
formdata object is used to write custom validation
To use this library's functions and objects, you must (a) import
.js file and (b) call the library's
initFormValidation() method during the page's
If the library is not located in the same directory as the form
itself, you must use the correct path to the library in the
src attribute. If the page needs additional
initialization during the page's
onload event, simply
call the library's
initFormValidation() method from
within the page's
Another alternative is to assign the
initFormValidation() method to the
onfocus event of every field:
If you use this
onfocus event technique, you must
make sure that it is applied to every form element, otherwise the
form will not be initialized if the user interacts with that
element first. This alternative may seem like a poor approach, but
it works well if the form elements are generated by some sort of
In order for the library to function correctly, the HTML form must obey the following rules:
nameattribute per group of radio buttons.
<select multiple>tags. (This needs to be addressed in the future).
The rule for unique element names may be broken under
specialized circumstances, if the repeated form elements are
arranged in groups of related fields. See the section on
for additional details.
This validation library supports simple declarations for the following common single-field validations:
All of these common validations must be assigned to the
validations object as validation properties.
Before this can be done, a new
Validator object for
the field must be created and assigned as a
validations object. It must be assigned to a property
whose name matches the field to be validated:
Validator object has been created for the
field, the validation properties for that field can be
assigned to it. A complete list of possible validation properties
is given below. Not every field will have every property:
Form elements groups which all have the same name (such as radio buttons) only need a single validation object and set of validation properties.
A field should only have the validation properties appropriate
to that field. For example, suppose a
userID field that is required and must be
between 6 and 10 characters in length. It would have the following
The field validation properties must be defined in the page
FormValidation.js library is
imported. The best place to define field validation properties is
either (a) immediately after each field or (b) in one big block at
the end of the HTML page.
The parameter for the
Validator constructor is the
human-readable label for the field, used for generating error
messages. The form's initialization copies validation properties
validations object to the corresponding form
elements. In addition, it creates and assigns a
property to the element whose value matches the parameter of the
The meaning of each validation properties is as follows:
label: The human-readable label for the field, used for generating error messages. If the field has any validation properties, it will also have a
labelproperty, whose value matches the parameter of the
readonly: Whether the field is read-only. If the user attempts to enter data into a read-only field, the cursor will move to the next field that is not read-only.
required: Whether the field is required. If the value for any required fields is blank, an error message will be generated when a form is submitted.
max, min: The upper and lower bounds for the numeric values of the field. The field may have just a
max, just a
minor both. The
minare themselves included in the range of allowed values. These values are only meaningful for numeric fields (including currency).
maxlength, minlength: The upper and lower bounds for the length of the text in the field. The field may have just a
maxlength, just a
minlengthor both. The
minlengthare included in the range of allowed lengths.
, scale: These properties relate to field data types for formatting and parsing, and are described in the detail in Field Data Types section.
compute: This property allows the assignment of custom validation functions to handle more complex computations and validations. It is described in the detail in Custom Validations section.
Field formatting and parsing may be specified through the
datatype validation properties The name
datatype" is used rather than "
attribute used to designate the type of a form input element
checkbox", etc.). Each data
type has formatting and parsing functions associated with, which
are used to manage field values. The appropriate formatting and
parsing functions are assigned as methods to the field based on the
datatype. For example, an
itemAmount field in an
use the "
Integer" data type to ensure that the field
only holds numeric values:
The form validation library has the following predefined data types:
"Integer": A positive integer value.
"SignedInteger": A signed integer value.
"Decimal": A positive decimal value.
"SignedDecimal": A signed decimal value.
"Currency": A positive currency amount (
"SignedCurrency": A currency value, allowing negative amounts.
"Phone": A phone number (
"SSN": A social security number (
"Postal": A postal code (
"Email": An email address (for example,
"Date": A date value (
parseType functions for the new type. Consult
the existing formatting and parsing functions for examples. Each
field will be assigned the formatting and parsing functions
appropriate to the field's
datatype. For example,
fields with a
datatype of "
be assigned the
Field formatting is called as part of both field and form validation. Field formatting appropriate to the data type occurs automatically, but not until after the user finishes entering the text and attempts to move to the next field in the form. If the contents of the field cannot be changed to the correct format, an error message alert is generated.
Field parsing is used when field values are needed in
calculations within other scripts on the page. Ordinarily, values
retrieved from a form field are strings. If a field holds a numeric
or date data type, the appropriate
parse method is
Date, etc.). If for some reason
parsing fails, the parse methods return a value of
NaN value is
returned for unparseable dates as well as numbers.
Finally, there is an additional validation property only used by decimal fields:
scale: The number of places after the decimal point. Currency fields automatically have a
For example, a decimal field with a scale of 3 will always be
#.###. Missing values are filled with 0's.
Excess values are rounded.
The library's form initialization assigns
setValue() methods to each
form element. These methods hide the differences between the data
manipulation mechanisms of different field types. The methods may
be called as follows:
The library also generates a global
that allows the developer to manipulate form field values using
setField() methods. For example, if a form has
address" field, it can be accessed via
formdata.setAddress(value) methods. The methods of the
formdata object are:
getField(): Returns the field's value, parsed if appropriate.
setField(value): Sets the field's value, formatting it if appropriate.
getFieldText(): Returns the field's text (select lists only).
computeField(): Calls the field's
computemethod for calculations and multi-field validations.
In each case,
Field is replaced by the
field's name, with the first letter capitalized. The last two
methods are only present if the field has a matching method of the
appropriate type (
Each method can be called through the global
object. For example, the following pairs of method calls are
The above method calls are only identical if the field is not
assigned a data type. If the field has a data type with a
parse method, then the
method will return the parsed value (such as a number or date),
field.getValue() method the returns
the actual field value as an unparsed string. If the field has a
data type with a
format method, than the
setField() method will format the field's value
while setting it, while the
As an example, consider the simple form:
It's HTML is:
It will have the following
getUserID(): Returns the
setUserID(): Sets the
getPassword(): Returns the
setPassword(): Sets the
getAccess(): Returns the
getAccessText(): Returns the
setAccess(): Sets the
formdata.setAccess("E") would select
the "Employee" option, and
return the current contents of the
userID field. The
formdata methods can be used when writing custom
No generic library can cover all possible field validations.
computations and validations, both for individual fields and for
the form as a whole. These custom validation methods are assigned
compute method of the field's validations
compute method will be called along with
the other validation methods when the element's event handler is
depending on the field type).
compute method should:
The method should return an empty string (
everything goes well or a string with an error message if the field
is invalid. Any error string should end in
that it display nicely within lists of errors. The
compute method can be defined with any name, but for
consistency should be in the form
If written correctly, the same custom
can be used for multiple fields:
When the form is submitted, it calls the
methods for every field in the form one last time before
submission. Under some circumstances, this may lead to extraneous
error messages. To avoid this problem, you may also define a global
compute method for the form itself. If the form has a
compute method, the
compute methods for
individual fields will not be called when the form is
To write more generic
compute methods, you can use
setValue() methods of
the field itself. Since the
compute method is assigned
as a method of the field, you can access these getter and setter
this.setValue(). Similarly, you can use other field
validation properties and methods like
parse(). If properly written, such
compute methods can be assigned to any field in any
compute methods can be used to update
other fields whose values need to change when the given field's
value changes. When writing such custom computations, it is
especially helpful that the
formdata object will return the parsed value
setField() methods will format the
field's value while setting it.
In the following example, the
computeTaxes() of the
total field will automatically update the
tax field. Every
compute method must
return a string value, so it should return an empty string if no
errors are possible.
When writing custom validations, be sure to consider the following:
computemethod is called after the
formatmethod, which mitigates (but does not eliminate) formatting issues.
formdata.setField()method does not automatically trigger its
computemethod. This is deliberate, to avoid endless loops.
The form may have elements with the same name (other than radio
buttons) under specialized circumstances. In particular, the
elements must be arranged in repeated sets of related elements.
Under these circumstances, the library will initialize a
formitems array. The entries in this array will have
get/setField methods for the form field
For example, consider this form:
It's HTML is:
The items in the
formitems array will have these
getItemName(): Returns the
setItemName(): Sets the
getCostPerItem(): Returns the
setCostPerItem(): Sets the
getAmount(): Returns the
setAmount(): Sets the
getItemsCost(): Returns the
setItemsCost(): Sets the
get/set methods with parse and format the
specified fields, as appropriate. Like radio buttons, the
validation properties for the repeated fields only need to be
assigned once. The validations for this form might look like:
A combination of the
formdata object and the
formitems arrays can be used to write the
computeTotals custom validation method.
In practice, this form would likely be dynamically generated
with a variable number of (possibly pre-populated) item fields. The
computeTotals() function accommodates these
Internationalization: This validation library is prepared
for internationalization. To localize the library to a non-US,
non-English region, create an extra validation library for the new
locale. The name for this localized library should follow the usual
internationalization naming conventions, such as
FormValidation_sp_ES.js for Spanish localized to Spain
FormValidation_en_GB.js for English localized to
Great Britain. The localized library should have localized
variations the following items in the core library:
The localized variants should have the exact same names as the original message string variables and formatting/parsing functions. To localize a given HTML page, import the locale-specific library after the core library:
The locale-specific error messages and functions will then
replace the US-English language messages and functions. This
localization should be relatively simple for dynamically generated
HTML pages, where the correct localization can be inserted into the
page based on the user's preferences. Note that the library's
internationalization only covers error messages generated by common
validations. Field labels, customized
validation methods and the page's content will have to be
internationalized and localized by the web developer.
Automatic script generation can speed development time as well as reducing errors and maintenance cost. The exact code necessary for such script generation depends on both the server-side process used for HTML generation (ASP, JSP, PHP) and the business object framework using to support the business logic.
Explorer, when the page focus is in any text element, hitting the
[Enter] key will submit the form. To circumvent the problems that
arise from the accidental submission of complex forms, many web
developers create HTML forms that have no input element of type
that fulfills the same function:
Unfortunately, such a button will circumvent the
onsubmit event of the form, skipping the library's
validate and submit the form:
This documentation includes a few additional references:
In addition, here are several example page's demonstrating the library's use:
This library is a good example of the Facade design pattern,
namely a single object (
formdata) that provides
simplified access to a host of other objects (all the objects
representing field elements). It makes extensive use of one of the
define new methods dynamically and assign them to objects. This
allows the library to inspect the characteristics of the form at
runtime and dynamically create the