API
@-Formulas
JavaScript
LotusScript
Reg Exp
Web Design
Notes Client
XPages
 
Generic Form Validation
When you need to validate fields on a form, this is an easy way to accomplish this using Regular Expressions.

There are many web sites outlining how to use Regular Expressions and the syntax and everything, so I won't go into that here. I will describe how to make a generic, reusable, form validator using Regular Expressions.

Step 1

Create three page design elements. One will have the Trim String function, one will have the Get Field Value function, and one will have the function outlined in this document. The page design elements should be named trim.js, getFieldValue.js, and validateForm.js.

Step 2

After creating these design elements, you will need to include 3 external JavaScript functions on your form. This can be done in the HTML Head section of your form with the following formula:

DbName := @ReplaceSubstring(@Subset(@DbName; -1); @Char(92) : " "; "/" : "+");
@NewLine + "<script language=\"JavaScript\" src=\"/" + DbName + "/trim.js\"></script>" + @NewLine + "<script language=\"JavaScript\" src=\"/" + DbName + "/getFieldValue.js\"></script>" + @NewLine + "<script language=\"JavaScript\" src=\"/" + DbName + "/validateForm.js\"></script>" + @NewLine

Note: instead of specifying the full path to the JavaScript pages, you can use a BASE HREF and specify relative URL's to the pages, as outlined here.

Step 3

Next, you will need to populate some global arrays that define how the form should be validated.

There are three arrays that determine the check for required fields (fields that must have a value)
requiredFields = array of the fields that will be required. These are the internal field names.
requiredFieldMessages = array of the messages that will appear if any of the fields in the "requiredFields" array is absent.
requiredMatchingDefaultOK = array of true/false values that check to see if it's ok if the required field matches its default value. For example, you may have field help as a default value for the field. If that's the case, you may want the user to change the value from the default.

NOTE: The array requiredFields is the baseline for the number of entries.
Extra elements in either requiredFieldMessages or requiredMatchingDefaultOK are ignored.
Missing elements in requiredFieldMessages are replaced with a canned "field <fieldname> is required" message.
Missing elements in requiredMatchingDefaultOK are replaced with true (which means it's ok if the field matches the default value).

Step 4

There are five arrays that determine the check for the formatting of the fields (the field value has to be in a certain format or cannot be in a certain format).
formatFields = array of the fields that will be checked for format. These are the internal field names.
formatSuccesses = array of arrays. Each entry can be a single value or an array. The values are the regular expressions that must be met for the checking to proceed.
formatMatchAllSuccesses = array of true/false values. If an entry is true, then all of the corresponding values in the formatSuccesses array must be met for checking to proceed. If an entry is false, then just one of the corresponding values in the formatSuccesses array must be met for checking to proceed. If the corresponding value in formatSuccesses is a single value instead of an array (or an array of one entry), then it doesn't matter if this value is true or false.
In other words, let's say the first element in formatSuccesses is an array of 3 values. If the field value must match all three of these criteria, then put true as the first element in formatMatchAllSuccesses. If it only has to match one of those three (it can be in this format or this format or this format), then put false as the first element in formatMatchAllSuccesses.
formatFailures = array of arrays. Each entry can be a single value or an array. The values are the regular expressions that flag a failure in formatting.
formatMatchAllFailures = array of true/false values. If an entry is true, then all of the corresponding values in the formatFailures array must be met for checking to fail. If an entry is false, then just one of the corresponding values in the formatFailures array must be met for checking to fail. If the corresponding value in formatFailures is a single value instead of an array (or an array of one entry), then it doesn't matter if this value is true or false.
formatMessages = array of strings. Each entry is a string. These are the messages that are shown to the user if either the success entries or the failure entries flag an error.

NOTE: The array formatFields is the baseline for the number of entires.
Extra elements in any of the other "format" arrays are ignored.
Missing elements in formatSuccesses are replaced with ".*" - this would be a regular expression that would match anything.
Missing elements in formatFailures are replaced with "^[\b]" - this would be a regular expression that would attempt to match a backspace at the beginning of the word. In other words, it will be replaced with a regular expression that will never fail.
Missing elements in formatMatchAllSuccesses are replaced with false - this means that only one entry must match to proceed.
Missing elements in formatMatchAllFailures are replaced with false - this means that only one entry must match to fail.
Missing elements in formatMessages are replaced with a canned "field <fieldname> is not formatted correctly" message.

Step 5

To use the functions, during your submit make a call to isFormFormattedCorrectly and pass in a pointer to the form.

The function will return true if all the required fields are present and all the fields are formatted correctly. The function will display an error message to the user and return false if any required field is not present or if a field is not formatted correctly. The user will receive only one error message (the first one found) and not all required/formatting messages.

Example:

<FORM NAME="TestForm" onSubmit="return isFormFormattedCorrectly(document.forms['TestForm']);">

The next couple of pages contain the code for the validateForm.js page you are supposed to create.

Page 1 of 3