Validation Controls

Validation controls, called validators, perform validation on user-entered data values when they are post back to the server. The validation is triggered by a postback control, such as a TButton, a TLinkButton or a TTextBox (under AutoPostBack mode) whose CausesValidation property is true.

Validation is always performed on server side. If EnableClientScript is true and the client browser supports JavaScript, validators may also perform client-side validation. Client-side validation will validate user input before it is sent to the server. The form data will not be submitted if any error is detected. This avoids the round-trip of information necessary for server-side validation.

Validators share a common set of properties, which are defined in the base class TBaseValidator class and listed as follows,

ControlToValidate specifies the input control to be validated. This property must be set to the ID path of an input control. An ID path is the dot-connected IDs of the controls reaching from the validator's naming container to the target control.
ErrorMessage specifies the error message to be displayed in case the corresponding validator fails.
Text is similar to ErrorMessage. If they are both present, Text takes precedence. This property is useful when used together with TValidationSummary.
ValidationGroup specifies which group the validator is in. The validator will perform validation only if the current postback is triggered by a control which is in the same group.
EnableClientScript specifies whether client-side validation should be performed. By default, it is enabled.
Display specifies how error messages are displayed. It takes one of the following three values:
- None - the error message will not be displayed even if the validator fails.
- Static - the space for displaying the error message is reserved. Therefore, showing up the error message will not change your existing page layout.
- Dynamic - the space for displaying the error message is NOT reserved. Therefore, showing up the error message will shift the layout of your page around (usually down).
ControlCssClass - the CSS class that is applied to the control being validated in case the validation fails.
FocusOnError - set focus at the validating place if the validation fails. Defaults to false.
FocusElementID - the ID of the HTML element that will receive focus if validation fails and FocusOnError is true.

Prado Validation Controls

TRequiredFieldValidator

TRequiredFieldValidator ensures that the user enters some data in the specified input field. By default, TRequiredFieldValidator will check if the user input is empty or not. The validation fails if the input is empty. By setting InitialValue, the validator can check if the user input is different from InitialValue. If not, the validation fails.

TRegularExpressionValidator

TRegularExpressionValidator verifies the user input against a regular pattern. The validation fails if the input does not match the pattern. The regular expression can be specified by the RegularExpression property. Some commonly used regular expressions include:

At least 6 characters: [\w]{6,}
Japanese Phone Number: (0\d{1,4}-|$0\d{1,4}$ ?)?\d{1,4}-\d{4}
Japanese Postal Code: \d{3}(-(\d{4}|\d{2}))?
P.R.C. Phone Number: ($\d{3}$|\d{3}-)?\d{8}
P.R.C. Postal Code: \d{6}
P.R.C. Social Security Number: \d{18}|\d{15}
U.S. Phone Number: (($\d{3}$ ?)|(\d{3}-))?\d{3}-\d{4}
U.S. ZIP Code: \d{5}(-\d{4})?
U.S. Social Security Number: \d{3}-\d{2}-\d{4}

More regular expression patterns can be found on the Internet, e.g. http://regexlib.com/.

Note, TRegularExpressionValidator only checks for nonempty user input. Use a TRequiredFieldValidator to ensure the user input is not empty.

TEmailAddressValidator

TEmailAddressValidator verifies that the user input is a valid email address. The validator uses a regular expression to check if the input is in a valid email address format. If CheckMXRecord is true, the validator will also check whether the MX record indicated by the email address is valid, provided checkdnsrr() is available in the installed PHP.

Note, if the input being validated is empty, TEmailAddressValidator will not do validation. Use a TRequiredFieldValidator to ensure the value is not empty.

TCompareValidator

TCompareValidator compares the user input with a constant value specified by ValueToCompare, or another user input specified by ControlToCompare. The Operator property specifies how to compare the values, which includes Equal, NotEqual, GreaterThan, GreaterThanEqual, LessThan and LessThanEqual. Before comparison, the values being compared will be converted to the type specified by DataType listed as follows,

String - A string data type.
Integer - A 32-bit signed integer data type.
Float - A double-precision floating point number data type.
Date - A date data type. The date format can be specified by setting DateFormat property, which must be recognizable by TSimpleDateFormatter. If the property is not set, the GNU date syntax is assumed.

Note, if the input being validated is empty, TEmailAddressValidator will not do validation. Use a TRequiredFieldValidator to ensure the value is not empty.

N.B. If validating against a TDatePicker the DataType must be equal to "Date" and the DateFormat property of the validator must be equal to the DateFormat of the TDatePicker.

TDataTypeValidator

TDataTypeValidator verifies if the input data is of specific type indicated by DataType. The data types that can be checked against are the same as those in TCompareValidator.

N.B. If validating against a TDatePicker the DataType must be equal to "Date" and the DateFormat property of the validator must be equal to the DateFormat of the TDatePicker.

TRangeValidator

TRangeValidator verifies whether an input value is within a specified range. TRangeValidator uses three key properties to perform its validation. The MinValue and MaxValue properties specify the minimum and maximum values of the valid range. The DataType property specifies the data type of the value being validated. The value will be first converted into the specified type and then compare with the valid range. The data types that can be checked against are the same as those in TCompareValidator.

If StrictComparison property is set to true, then the ranges are compared as strictly less than the MaxValue and/or strictly greater than the MinValue.

N.B. If validating against a TDatePicker the DataType must be equal to "Date" and the DateFormat property of the validator must be equal to the DateFormat of the TDatePicker.

TCustomValidator

TCustomValidator performs user-defined validation (either server-side or client-side or both) on an input control.

To create a server-side validation function, provide a handler for the OnServerValidate event that performs the validation. The data string of the input control to validate can be accessed by the event parameter's Value property. The result of the validation should be stored in the IsValid property of the parameter.

To create a client-side validation function, add the client-side validation javascript function to the page template and assign its name to the ClientValidationFunction property. The function should have the following signature:

TValidationSummary

TValidationSummary displays a summary of validation errors inline on a Web page, in a message box, or both.

By default, a validation summary will collect ErrorMessage of all failed validators on the page. If ValidationGroup is not empty, only those validators who belong to the group will show their error messages in the summary.

The summary can be displayed as a list, a bulleted list, or a single paragraph based on the DisplayMode property. The messages shown can be prefixed with HeaderText. The summary can be displayed on the Web page or in a JavaScript message box, by setting the ShowSummary and ShowMessageBox properties, respectively. Note, the latter is only effective when EnableClientScript is true.

Interacting the Validators

Resetting or Clearing of Validators

Validators can be reset on the client-side using javascript by calling the Prado.Validation.reset(groupID) where groupID is the validator grouping name. If groupID is null, then validators without grouping are used.

Client and Server Side Conditional Validation

All validators contains the following events. The corresponding events for the client side is available as sub-properties of the ClientSide property of the validator.

The OnValidate event is raise before the validator validation functions are called.
The OnValidationSuccess event is raised after the validator has successfully validate the control.
The OnValidationError event is raised after the validator fails validation.

Note: For Prado versions earlier than 3.1 the property names were OnError and OnSuccess. For Prado version 3.1 or later they are OnValidationError and OnValidationSuccess, respectively.

The following example pop-up a message saying "hello" when the validator fails on the client-side. <com:TRequiredFieldValidator ... > <prop:ClientSide.OnValidationError> alert("hello"); </prop:ClientSide.OnValidationError> </com:TRequiredFieldValidator> The resulting client-side event callback function is of the following form. function onErrorHandler(sender, parameter) { alert("hello"); } Where sender is the current client-side validator and parameter is the control that invoked the validator.

Conditional Validation Example

The following example show the use of client-side and server side validator events. The example demonstrates conditional validation. Notice that, we need to write code for both the server side and client-side. Moreover, on the server side, we need to re-enable the conditional validator so that its javascript code are produced no matter what (otherwise, the client-side validator is not available).

$Id$