Validating Your Forms

The qForms API ships with dozens of validation routines that are ready to use. The validation routines were designed to be easy to use and easy to create.

Using The Validation Library
In order to take advantage of the validation methods, you'll need to first make sure to load both the "validation" and "function" libraries with using the qFormAPI.include() method. You can do this two ways: by loading each individual library or loading all of the default extension libaries. In order to load the qForms API and the bare minimum libraries in order to get the validation methods to work, place the following code in between the <HEAD></HEAD> of your document.

<!--// load the qForm JavaScript API //-->
<SCRIPT SRC="/lib/qforms.js"></SCRIPT>
<!--// you do not need the code below if you plan on just
       using the core qForm API methods. //-->
<!--// [start] initialize all extension libraries  //-->
<SCRIPT LANGUAGE="JavaScript">
<!--//
// specify the path where the "/qforms/" subfolder is located
qFormAPI.setLibraryPath("/lib/");
// loads the validation & functions libraries
qFormAPI.include("validation");
qFormAPI.include("functions", null, "12");
//-->
</SCRIPT>
<!--// [ end ] initialize all extension libraries  //-->

The validation methods are extremely easy to use. There are two types of validation methods: "validate" methods and an "is" methods. The "validate" methods are used to initialize a validation rule on a form field. You initialize these methods at runtime and the rule is processed everytime the validate() method is called upon the form. The validate() method is called automatically when the form is submitted. For example, to validate that the field "Email" appears to be a valid e-mail, you'd do the following:

objForm.Email.validateEmail();

That's it! This creates a validation rule that will be enforced any time the user tries to submit the form.

The "is" methods can be called at any time to determine whether the specified field passes the validation rule. The "is" methods will return true if the validation rule passes, and it will return false if the validation rule fails. For example, if you wish to know at any current time whether the "Email" field contains a valid e-mail address, you'd do the following:

objForm.Email.isEmail();

This would return true if the validation rule passes, or false if the rule failed. It doesn't get much easier than that!

Requiring Fields

There is something important to note about validation rules, validation rules check the status of the field's "required" property. If a field is blank and the "required" property is false (the default value,) then the validation rule will not fail. In order to get the validation rule to fail, you need to set the "required" property to true. This allows you to apply rules to form fields, but not require a value—you may not want every field on a form to be required, but if the user does input data, you will want to make sure it appears to be valid. For example:

objForm.Email.required = true;
objForm.Email.validateEmail();

This would ensure that the user fills in a value for the "Email" field that appears to be a valid e-mail address before the form can be submitted. If the field is either blank or doesn't pass the validation rule, then an validation error will occur.

Tip: You can require or make multiple fields optional using the required() and optional() methods.

Forcing Field Validation
One of the unique features of the qForms API is its ability to attach events to form fields automatically. Because of this, we're you're able to force validation automatically when focus leaves a form field. In order to do this, you must set the field's "validate" property to true before calling the validate method. For example:

objForm.Email.required = true;
objForm.Email.validate = true;
objForm.Email.validateEmail();

This would require a value in the the "Email" field as well as run the validation rule to ensure the field appears to contain a valid e-mail address any time the user tries to remove focus from the field, or the user tries to submit the form.

Tip: You can forceValidation on multiple fields by using the forceValidation() method.

Creating Custom Validation
Knowing the importance of validating data, we also knew that creating custom validation methods would have to be quick and easy. The qForms API does this using two means: the validateExp() method and the _addValidator() function.

The validateExp() method is designed as a way to do simple validations. It's designed to allow you to quickly create rules such as: making sure a field is greater then zero. You could do that by using something like the following:

objForm.Qty.validateExp("parseInt(this.value) < 1");

This ensures that the "Qty" field contains a postive integer greater than zero. (If the condition returns true, than an error is thrown, otherwise no error occurs.)

For more complex validation rules, or to create your own validation libraries, you'll want to use the _addValidator() function. In order to use the _addValidator() function, you'll first need to know a few things about how to create validation functions.

Before using the _addValidator() function, you'll first need to create a function that contain the validation rules you wish to enforce. When creating these functions, there's two things to keep in mind.

First, you'll have access to a special variable called "this"—which is a direct pointer to the field that the validation rule was attached to. For those of you who've created a constructor before, this variable will look very familiar to you. So, to retrieve the value of the field that the rule was attached to, you'd use this.getValue().

The second thing you need to know is: validation rules have two special properties available to them, the "this.value" and the "this.error" properties. The this.value property will contain a copy of the value as returned by the this.getValue() method as soon as the validation method is invoked. The this.error property is used to fail a validation rule if it doesn't meet your specified conditions. In order to fail a validation rule, simply populate the this.error property with the error message that should appear to the user. If the this.error property is empty when the function ends, then validation rule will pass, and no error will be thrown. If the this.error property contains a string value, then the value will be displayed to the user and and the validation rule will fail.

Let's create a quick little function that will check to make sure the current field's value is an integer greater than zero.

function __isPositiveInt(){
  // check to make sure the current value is greater then zero
  if( parseInt(this.value) < 1 ){
    // here's the error message to display
    this.error = "The " + this.description + " field must";
    this.error += " contain an integer greater then zero.";
  }
}

The next thing we need to do is to register the our new function using the _addValidator() function. We do that using the following syntax:

_addValidator("isPositiveInt", __isPositiveInt);

The first parameter supplied is the name for our new validation method. From this, two new methods will be created: "validatePositiveInt()" and "isPositiveInt()". The second argument is the name of the function that was just created. This value should not be in quotes. Calling the isPositiveInt() method will return true if the field contains a positive integer value, and will return false if it doesn't. To attach the rule to a field, we'd simply do the following:

objForm.Qty.validatePositiveInt();

How easy was that? Take a look through the validation.js file to see how to create more complex validation rules.

Custom Error Messages
The _addValidator() function automatically appends a special argument to your function for specifying custom error messages. This is useful for displaying specific errors that better represent your form then the default error message, or simply for those times when the default error message just doesn't make sense.

Since this argument is created automatically for you, it's important to note that is appended to the end of any arguments of the original function. So, if the original function attached via the _addValidator() had zero arguments, the errorMsg argument would be the first argument in the validator methods. If the function had 3 arguments, then the errorMsg argument would be the forth argument. For example to add a custom validation error to the "Email" field, use the following:

objForm.Email.validateEmail("Please enter your e-mail address.");

Or, if the function requires or has optional arguments, your code might look like the following:

objForm.MonthBorn.validateRange(1, 12, "The month you were born in must be a valid integer between 1 and 12.");
Note: It's important to remember that providing a custom validation error message to a field will not affect the message that's displayed if the field is required.

[< Back] [Index] [Next >]