Documentation

Installation

jsVal is contained within it's own .js file. Simply copy the jsval.js file to your source directory.
Include the jsval.js page in your HTML page:

<script language="javascript" src="jsval.js"></script>

The src= value can change if jsval.js is not located in the same directory

Usage

Call the validateStandard or validateCompleteForm from your html form like this:

<form name="reg" method="post" onSubmit="return validateStandard(this);">

There are two functions for form validation:


Both functions having the same parameter list:
Parameter Description
form The form object that should be validated (i.e. "this")
strErrorClass Optional: The style-class name of a css style definition that should be used for a field if it is invalid (see example 1). This parameter is optional.

Initialization

In order for jsVal to know which validation rules to apply, you must first initialize the validation process. This is done by setting properties on the form fields you wish to validate. You can use two kind of initialization methods

1. Through a JavaScript function

The best place to do this when the OnLoad event of your page fires. Let's look at a brief example (line #s are included for reference purposes only):
<html>
<head>
   <script language="javascript" src="jsval.js"></script>
   <script language="javascript" type="text/javascript">
   <!--
   1:  function initValidation()
   2:  {
   3:      var objForm = document.forms["testform"];
   4:      objForm.name.required = 1;
   5:      objForm.name.regexp = /^\w*$/;
   6:
   7:      objForm.password.required = 1;
   8:      objForm.password.minlength = 3;
   9:      objForm.password.maxlength = 8;
   10:  }
   --//>
   </script>
</head>
<body onLoad="initValidation();">
   <form name="testform" method="post" action="process.php" onSubmit="return validateStandard(this);">
        Name: <input type="text" name="name"><br />
        Password: >input type="password" name="password"><br />
        <input type="submit" value="Login">
   </form>
</body>
</html>

 

Breaking the initValidation down, we see the following:
  1. Get a reference to the form (line 1).
  2. Set the name and password fields are required (lines 4 and 7)
  3. The name field should only contain characters (this is done via a regular expression, don't worry, jsVal comes with several built-in!) (line 3).
  4. The password must atleast 3 characters but no more than 8 (lines 8 and 9).

 

2. Inline initialization

Instead of using an explizit init-function for setting all field properties you can use the inline init method for doing this (V.0.4.0 and higher).
Let's look at the preveous example using inline initialization (line #s are included for reference purposes only)
<html>
<head>
   <script language="javascript" src="jsval.js"></script>
</head>
<body>
   <form name="testform" method="post" action="process.php" onSubmit="return validateStandard(this);">
        Name: <input type="text" required="1" regexp="/^\w*$/" name="name"><br />
        Password: >input type="password" required="1" minlength="3" maxlength="8" name="password"><br />
        <input type="submit" value="Login">
   </form>
</body>
</html>

Properties

Following is a complete list of properties available. In addition, you can visit the examples page, and "View Source" in your browser to see other real exampels.
Property Possible values Description
required 1
0
Field is required
Field is optional
regexp /regex/
JSVAL_RX_EMAIL
JSVAL_RX_TEL
JSVAL_RX_ZIP
JSVAL_RX_MONEY
JSVAL_RX_CREDITCARD
JSVAL_RX_POSTALZIP
JSVAL_RX_PC
Free regular expresion (i.e. /^\w*$/)
Check for correct email adress
check for correct phone number
check for correct zip code
check for correct money amount
check for correct credit card number
check for correct postal zip code
check for correct postal code
minlength numeric defines the miniumum length of an input value
maxlength numeric defines the maximum length of an input value
minvalue numeric, float defines the miniumum value of an input field (must be numeric or float)
maxvalue numeric, float defines the maximum value of an input field (must be numeric or float)
err string user defined error message thats printed when field value is invalid
realname string user defined field name, that is used for error messages. If not defined the fields ID or name attribute is used.
equals string The name or id of a form field to which the value of this field must be equal. Usefull for password retype fields (see example 5)
callback string The name of the callback function that is called for validating this form field (see Callback section below for details)
 

Callback functions

If you need to do more complicated validations on a form field you can use callback functions. That means that a script part of your page is doing the validation instead of jsVal. For this you can define a callback function as a attribute of the form field

Example:
<input type="text" required="1" callback="mycallback" name="value">

A callback funtion needs to be defined with 3 parameters
Parameter Description
id The id of the form field that should be validated
name The name of the form field that should be validated
value The value of the form field that should be validated

The callback function needs to return a boolean value. true if the field is valid and false if not.
Example:
<html>
<head>
   <script language="javascript" src="jsval.js"></script>
   <script language="javascript">
        function mycallback(id, name, value) {
            if (value * 10 >= 200) {
               return true;
            }
            return false;
        }
   </script>
</head>
<body>
   <form name="testform" method="post" action="process.php" onSubmit="return validateStandard(this);">
        Name: <input type="text" required="1" callback="mycallback" name="testvalue"><br />
        <input type="submit" value="Login">
   </form>
</body>
</html>
 

Multilanguage support

The default error messages of jsVal are in english. To change them to your own language you are able to provide this messages in other languages.
For this you have to define a class jsVal_Language in your HTML page. See the following example (defining the error messages in german):
<html>
<head>
   <script language="javascript" src="jsval.js"></script>
   <script language="javascript">
        function jsVal_Language() {
            this.err_enter = "Bitte geben Sie für das Feld "%FIELDNAME%" einen gültigen Wert ein.";
            this.err_form = "Bitte geben Sie für die folgenden Felder gültige Werte ein:\n\n";
            this.err_select = "Bitte wählen Sie für das Feld "%FIELDNAME%" einen gültigen Wert aus.";
        }
   </script>
</head>
<body>
   <form name="testform" method="post" action="process.php" onSubmit="return validateStandard(this);">
        Name: <input type="text" required="1" regexp="/^\w*$/" name="name"><br />
        Password: >input type="password" required="1" minlength="3" maxlength="8" name="password"><br />
        <input type="submit" value="Login">
   </form>
</body>
</html>
You can insert the replacement-tag %FIELDNAME% into the translated strings. This variable will be replaced by the field name in the error message.