Form validation

The form validation script form_validate.js is designed to be an optional addition to the Core file. The script checks the fields forms with certain markup and disables submission of the form until the fields are valid.

Quick start

Your form should be based on the standard structure for forms in the university template and should validate.
Your form should have matching back end (cgi script based) validation. eg: a xx.required file for cgi-mailer

Add links to the script and style sheet in the head of your page.

<script language=”JavaScript” type=”text/javascript” src=”http://www.unimelb.edu.au/template-assets/07/js/form_validate.js”></script>
<link rel="stylesheet" type="text/css" href="http://www.unimelb.edu.au/template-assets/07/styles/contentform.css" media="all" />

Add classes of validate and contentform to the form tag of the form.

<form class=”contentform validate” method=”get” action=”“>...</form>

Add a class of required to each label or fieldset that contains inputs you want to mandate. For specific information on this step, refer to individual elements in the Library of form elements.
Add a span of class required-flag as a child of each required element. For specific information on this step, refer to individual elements in the Library of form elements.

Options

Validation classes

to validate as an email address add the class email to a <textarea> or <input> of type text
to validate as a number add the class number to a <textarea> or <input> of type text

Changing the default text

To change the default ‘valid’ and ‘invalid’ messages, add the following to the <head> of your xhtml document, immediately after

<script language="JavaScript" type="text/javascript" src="form_validate.js"></script>

for valid text (default: ‘OK’):

<script language="javascript" type="text/javascript">
  uM_form.validationText.valid_text = "Your valid text here";
</script>

for invalid text (default: ‘(required)’):

<script language="javascript" type="text/javascript">
  uM_form.validationText.invalid_text = "Your invalid text here";
</script>

to change the message which appears in the link next to disabled buttons (default: ‘This form needs to be reviewed’):

<script language="javascript" type="text/javascript">
  uM_form.validationText.disabled_button_text= "Your button text here";
</script>

xhtml classes used by this script

Class	Used on (element)	How added	Description
`validate`	`form`	Manually	indicates a form which should be validated
`required`	any element below a `form` but most logical on a field* or `fieldset`	Manually	an element to with one or more fields to be validated
`required-flag`	`span`	Manually	where the required warning text appears
`email`	`input`(text) or `textarea`	Manually	optional validation class, expects email (eg. somebody@somewhere.etc)
`number`	`input`(text) or `textarea`	Manually	optional validation class, expects a number
`no-parse`	`input`(text) or `textarea`	Automatically	added to fields with a validation class which do not validate
`valid`	required element, field*	Automatically	added to required elements and fields which are valid
`disabled-button`	`a`	Automatically	added to the label element of all inputs (type submit, button) and butttons (type submit, button) in the form. Note that the <`a`> element is also added automatically by the script

* input, select, textarea

How the form validation works

Summary

Each form on the page (with a validate class) validates separately. A form is valid if all of its required elements are valid. A required element is valid if all of its fields are valid. A field is valid if it has appropriate contents. Appropriate content means not being empty or validating according to certain rules. Such rules are defined separately (see validationSet) and require specific classes (eg. email) to be added to the field. When a field is valid, it acquires a valid class. When a required element is valid, it acquires a valid class and its required-flag span is updated (with text from validationText) to show that it is valid. When a form is valid, its submit button is enabled.

What the script does

For each form with the validate class, prepare adds an id, a label and a link (which points to the first invalid required field) to each submit button if required with addButtonLabel, disables the buttons (using changeButtonState), and adds the following event listeners for each the required fields:

‘change’ and ‘keyup’ events for <select>
‘click’ events for radio and checkbox groups
‘keyup’ and ‘blur’ events for all others

Thereafter, when one of the appropriate events occurs, the script will:

check the field for validity with checkFieldValidity (which may call checkInputValidity). If a field is valid, it is given a valid class. In the case of checkbox or radio button groups, all of the fields in the group are given a valid class.
use parseValidity to check if the field has a class which matches one listed in the validationSet. If so, it checks the input text against the pattern. If the pattern does not match, the field is given a no-parse class and the error text is added to the required-flag span of the parent required element.
check the required element validity with checkRequiredValidity. If a required element is valid, it is given a valid class. If all of the required element’s fields are valid, the required-flag span is changed to the ‘correct’ text (default is a ‘OK’). If one or more fields are invalid, the ‘invalid’ text is displayed (default is ‘Required’).
check the validity of the form with checkValidForm. If all required fields are valid (that is, have the valid class), the form buttons will be enabled with changeButtonState and the link text removed with removeDisabledWarning. If not, the link will point to the first invalid required element.

Known limitations

Pasting from the menu in a text field does not trigger the validation script. However, changing focus will trigger the event. Pasting using a keyboard shortcut works fine.

Form validation variables

There are four variables defined by the validate_form.js script. They are:

validationSet

The validationSet variable contains information about different validation types to be used. Each sub-variable in validationSet describes a class name, regular expression pattern and an error message to be displayed if the pattern does not match the input. The re are currently two validation types:

email : inputs with email class must contain a valid email address (eg. somebody@somewhere.host)
number : inputs with this class must contain numbers, which can be whole numbers, floating point or negative

validationText

This variable defines the messages and/or images which should appear if the form validates, or otherwise:

valid_text : “OK”,
invalid_text : “Required”
disabled_button_text : “(This form needs to be reviewed)”

The information in the double quotes is the message which will appear on the web page in the required-flag span of each required element, or in the disabled_button link for disabled_button_text

id_counter

This is used to assign unique id attributes to submit buttons in the forms.

form_required_list

A list of required elements in the form

Functions

Core functions

The form validation functions rely on several core functions:

addButtonLabel

Usage: uM_form.changeButtonState(form_validate);

Parameters:

form_validate - a form element which has the validate class

Effect: All submit buttons and inputs acquire (if they did not already have) an id, a label and a span explaining that the button has been disabled

Returns: nothing

Hat-tip: Patrick Maslen

Processing:

finds buttons in form with getElementsByTagAndAttributes
for each button:
- checks for id and allocates one (using uM_form.generateId) if it does not exist
- checks for label and allocates one if it does not exist
- adds a span with disabled text to label(see Changing the default text (optional))

changeButtonState

Usage: uM_form.changeButtonState(form_validate, enable);

Parameters:

form_validate - a form element which has the validate class
enable - a boolean; set true to enable buttons, false to disable

Effect: Finds all of the <button> and <input> elements in the form with “submit” or “button” attributes, and disables them.

Returns: the enabled state of the buttons (true for enabled, false for disabled)

Hat-tip: Patrick Maslen

Processing:

finds buttons in form with getElementsByTagAndAttributes
disables/enables buttons based on enable parameter

checkFieldValidity

Usage: uM_form.checkFieldValidity(e);

Parameters: e - DOM event

Effect: Sets or removes valid class to/from a field based on the field type.

Returns: nothing

Hat-tip: Patrick Maslen

Processing:

finds field type and determines validity; calls uM_form.checkInputValidity if the field is of input type
sets valid class on the field if it is; removes the class otherwise
calls uM_form.checkRequiredValidity

checkInputValidity

Usage: uM_form.checkInputValidity(input_element);

Parameters: input_element - input element

Effect: Finds out whether an input is valid, based on type

Returns: boolean validity; true indicates that the input is valid, false otherwise.

Hat-tip: Patrick Maslen

Processing:

hidden, button, reset and submit inputs are ignored
radio inputs are valid if one radio input has been selected from the group
checkbox inputs are valid if at least one checkbox has been selected from the group
all other inputs (text) are valid if they are not empty

checkRequiredValidity

Usage: uM_form.checkRequiredValidity(required_element);

Parameters: required_element - element with the required class

Effect: Updates required-flag span with text from the validationText to reflect validity of the required element’s fields.

Returns: boolean validity; true indicates that the required element is valid, false otherwise.

Hat-tip: Patrick Maslen

Processing:

Finds all fields (input, textarea and select) which are children of the required element
Checks each for the presence of the valid class
If all are valid, updates the required-flag span with the valid_text and valid_image variables from validationText
If not all of the fields are valid, updates the required-flag span with the invalid_text and invalid_image variables from validationText
calls uM_form.checkValidForm

checkValidForm

Usage: uM_form.checkValidForm(form_validate);

Parameters: form_validate - form element with the validate class

Effect: enables or disables the form buttons, based on validity of its required fields

Returns: boolean validity; true indicates that the form is valid, false otherwise.

Hat-tip: Patrick Maslen

Processing:

Checks required fields of this form
If all are valid, enables all buttons using uM_form.changeButtonState and removes disabled warning with uM_form.removeDisabledWarning
Otherwise, disables all buttons using uM_form.changeButtonState and restores disabled warning with uM_form.removeDisabledWarning

findFirstInvalid

Usage: uM_form.findFirstInvalid(form_validate);

Parameters: form_validate - form element with the validate class

Effect: finds the first `required` element without the `valid` class

Returns: the first `required` element without the `valid` class, false if not found.

Hat-tip: Patrick Maslen

Processing:

Checks required fields of this form
If one is not valid, stops looking and returns it.

findParentForm

Usage: uM_form.findParentForm(current_node);

Parameters: current_node - the current DOM location

Effect: finds the nearest form with class validate

Returns: the closest form with class validate, or the body tag if not found

Hat-tip: Patrick Maslen

Processing:

searches up the DOM tree (using uM.hasClass until it finds a form with class validate, or the body tag

findParentRequired

Usage: uM_form.findParentRequired(current_node);

Parameters: current_node - the current DOM location

Effect: finds the nearest element with class required

Returns: the closest element with class required, or the body tag if not found

Hat-tip: Patrick Maslen

Processing:

searches up the DOM tree (using uM.hasClass) until it finds an element with class required, or the body tag

generateId

Usage: uM_form.generateId(identifier_string);

Parameters: identifier_string - a string to incorporate into the id; often the element name

Effect: creates a unique id

Returns: string id

Hat-tip: Patrick Maslen

Processing:

creates a unique id by combining “uM_form” with identifier_string and a number from id_counter

getFormButtons

Usage: uM_form.findParentRequired(form_validate);

Parameters: form_validate - form element with the validate class

Effect: finds the submit and button inputs and buttons associated with form_validate

Returns: a list of button and input nodes

Hat-tip: Patrick Maslen

Processing:

cycles through buttons and inputs of type=”submit” or type=”button” for the form.

prepare

Usage: uM.addLoadListener(uM_form.prepare);

Parameters: none

Effect: Finds each form with class validate in the document. Deactivates the buttons on each form. Adds event listeners to each form field which is a child of an element with a required class. Executed by default in validate_form.js.

Returns: nothing

Hat-tip: Patrick Maslen

Processing: For each form with the validate class in the document

Disables the buttons with changeButtonState
Finds the fields which are children of required elements (uses findParentRequired)
Assigns event listeners to the appropriate fields with uM.attachEventListener as follows:
- change and keyup events for select fields
- click events for inputs of type checkbox and radio
- keyup and blur events for other fields

parseValidity

Usage: uM.parseValidity(field);

Parameters: field - a text field in a required element

Effect: Adds a class of no-parse to each field of a class defined in uM_form.validationSet which does not validate according to that rules Returns: nothing

Hat-tip: Stuart Langridge

Processing:

checks the field to see if it has each class defined in uM_form.validationSet
if it does, checks the value of the field against the appropriate regular expression
if the regex check fails, the field is assigned a class of no-parse

removeDisabledWarning

Usage: uM_form.removeDisabledWarning(form_validate, enable);

Parameters:

form_validate - a form element which has the validate class
enable - a boolean; set true to remove text, false to add

Effect: Adds/removes the disabled text from the label of each button, depending on the state of enable

Returns: nothing

Hat-tip: Patrick Maslen

Processing:

modifies the text of the disabled-button link
removes href attribute from disabled-button link