affordable web development services
| About Us | Services | Download | Order | Support | Subscribe to News Feed Follow us on Twitter Join us on Facebook |
 

Tigra Form Validator v1.3 - Documentation

Table of Contents

Description

Tigra Form Validator is free JavaScript component performing client side form validation. With its rich feature set the script can be used with HTML forms of virtually any complexity. This component is a simple way to improve visitors' experience, robustness and resource efficiency of your web application.

Features

Compatibility Table

Tigra Form Validator works with any browser that supports generic DHTML.
Below is a table of the application compatibility:

Platform Browser
MS IE Netscape Mozilla Firefox Opera Safari
Windows 95/98/ME/2000/XP 4.0+ 4.08+ 0.9+ 6.0+ 3+
Mac OS 8/9/X 5.0+ 4.7+ 0.9+ 6.0+ 1.0+

Files

Tigra Form Validator distribution package contains the following files:

Where ? and * are wildcards for single character and substring respectively.

Adding Form Validator to HTML Page

First thing to be done to the document where Tigra Form Validator will be used than is attaching product core script to a header with appropriate tag:

<head>
  <!-- some header data -->
  <script language="javascript" src="validator.js"></script>
</head>

To validate fields of a HTML form Tigra Form Validator script has to create a JavaScript object instance for that form. Such a creation is done with a JavaScript line called "constructor call". So the number of constructor calls in a HTML document should be equal to a number of HTML forms the script is desired to serve.

Here is sample Tigra Form Validator constructor call:

<html>
<head>
  <!-- some header data -->
  <script language="javascript" src="validator.js"></script>
</head>
<body>
...
<!--A form for validation-->
<form name="a_form" onsubmit="return v.exec()">
...
</form>
...
<script language="JavaScript">
var o_fields = {
		...
		//A structure describing fields
		...
		},
o_config = {
		...
		//A structure describing validator configuration
		...
		}

//Constructor call
var v = new validator('a_form', o_fields, o_config)
...
</script>
</body>
</html>

The constructor is supplied with 3 parameters:

IndexDescriptionTypeIf requiredIn above sample
1 a string name of the form inputs to fields of which are to be validated by the script stringyes'a_form'
2 a JavaScript structure or a reference to a structure describing fields inputs of those are to be validated objectyeso_fields
3 a JavaScript structure or a reference to a structure describing validator settings objectnoo_config

The constructor is a function returning a reference to created object instance once being called. It is necessary to store that reference in a variable because it will be used than. In above sample such variable name is v.

Note that each constructor call has to be placed only after closing </form> tag of the corresponding form otherwise the form to work with will be not found by the script. Since that it is a good practice to place all validator constructor calls just before closing </body> tag.

Describing Fields

Form fields inputs of those you would wish to validate are described with Fields Describing Structure, a JavaScript structure that contains names and attributes of those fields. Each form field you need to validate corresponds to one record of the structure - a descriptor - named exactly as that field. A descriptor is made up of a key (descriptor name) - a string containing corresponding field name, a colon (:) and a structure of field attributes:

<field name> : {<structure of field attributes>}

All descriptors are enclosed in curly brackets ({}) and separated with commas (,).

Field Attributes

To tell validator script in which way an input of the field has to be validated each descriptor contains field attribute structure. The structure is a set of field attribute descriptors enclosed in curly brackets ({}) and separated with commas (,). Each field attribute descriptor consists of a name (string), colon (:) and value:

<field name> : {
  // structure of field attributes
  <attribute 1> : <value of attribute 1>,
  <attribute 2> : <value of attribute 1>,
  ....
  // any attributes here
  ....
  <attribute n> : <value of attribute n>
}

Below is a table of field attribute descriptors currently supported:

KeyDescriptionValues
accepteddefault
 
l Field label to refer the field in messages a string (required attribute)
r If the field is required boolean false
f Field format the input has to meet predefined format name (is not used)
t id of a HTML element to highlight if input is not valid a string (is not used)
m A name of another form field this field input must match. Useful for password copies a string (is not used)
mn The least number of characters the field can contain a positive integer number (is not used)
mx The most number of characters the field can contain a positive integer number (is not used)

Field Label Highlighting

Tigra Form Validator highlights labels of fields if ones have been filled with errors by just changing CSS classes to be applied to those labels.

The name of a class to be applied to highlight a label is always tfvHighlight.
The name of a class to be applied to unhighlight (normalize) a label is always tfvNormal.

So just declare both tfvHighlight and tfvNormal classes between <style></style> tags in the document header or in an external CSS file attached to the document.

Below are sample declarations for tfvHighlight and tfvNormal classes:

...
<style>
/* classes for validator */
  .tfvHighlight
    {color: #CEA639;}
  .tfvNormal
    {color: black;}
</style>
...

Field Format

Tigra Form Validator supports a feature of checking if form field input meets certain pattern (format). The script contains several predefined formats those can be refereed by the following names:

Format nameDescription
alpha A string of characters of Latin alphabet, a dot (.) and a hyphen (-)
alphanum Alphanumeric characters and an underline (_)
unsigned Unsigned integer number
integer An integer number
real A number with a decimal point
email E-mail address format
phone Phone number consisting of digits, spaces ( ), dots (.) and hyphens (-)
date Date value formatted as DD-MM-YYYY
time Time value formatted as HH:MM:SS

Sample Field Description Structure

Suppose there is a form named myForm containing 3 fields: first_name, last_name and email:


<form name="myForm">
  <input type="text" name="first_name"><br>
  <input type="text" name="last_name"><br>
  <input type="text" name="email">
</form>

We have to set up the validator to check if:

Here is sample Fields Describing structure for the case:

var myFields = {
  // first_name field description line (descriptor)
  'first_name' : {
    // the field is required
    'r' : true,
    // field format: alphabetic characters only
    'f' : 'alpha'
  }
  // last_name field description line (descriptor)
  'last_name' : {
    // the field is required
    'r' : true,
    // field format: alphabetic characters only
    'f' : 'alpha'
    'mn' : 3
  },
  // email field description line (descriptor)
  'email' : {
    // field format: predefined
    'f' : 'email',
    'mn' : 3
  }
}

Validator Settings

Tigra Form Validator behavior can be controlled by Validator Setting Structure, the third optional parameter of the constructor. Validator Setting Structure is a JavaScript structure consisting of records enclosed in curly brackets ({}) and separated with commas (,). Each record controls certain validator behavior aspect and contains a key (string name), a colon (:) and a value. Below is a table of keys currently supported by the structure and their meanings.

KeyDescriptionValues
accepteddefault
alert Defines if errors raised during script set up are displayed. It is useful to turn this option on when adding validator to the document Boolean false
to_disable A list of names of form fields to be blocked on successful submit. Useful to prevent multiple form posts before load Array of strings (is not used)

Here is a sample code for Validator Setting Structure:

o_config = {
  'to_disable' : ['Submit'],
  'alert' : 1
}

Terms and Conditions

Tigra Form Validator is FREE for any kind of applications. There is no license fee or royalty fee to be paid at any time for using the Tigra Menu
You may include the source code or modified source code within your own projects for either personal or commercial use but excluding the restrictions outlined below. The following restrictions apply to all parts of the component, including all source code, samples and documentation:

Links and References