The data that a user enters in a user interface might or might not be appropriate to the application. In Flex, you use a validator to ensure the values in the fields of an object meet certain criteria. For example, you can use a validator to ensure that a user enters a valid phone number value, to ensure that a String value is longer than a set minimum length, or ensure that a ZIP code field contains the correct number of digits.

In typical client-server environments, data validation occurs on the server after data is submitted to it from the client. One advantage of using Flex validators is that they execute on the client, which lets you validate input data before transmitting it to the server. By using Flex validators, you eliminate the need to transmit data to and receive error messages back from the server, which improves the overall responsiveness of your application.

Flex includes a set of validators for common types of user input data, including the following:

• Validating credit card numbers
• Validating currency
• Validating dates
• Validating e-mail addresses
• Validating numbers
• Validating phone numbers
• Validating using regular expressions
• Validating social security numbers
• Validating strings
• Validating ZIP codes

You often use Flex validators with data models. For more information about data models, see Storing Data.

About validators

You define validators by using MXML or ActionScript. You declare a validator in MXML by using the <mx:Validator> tag or the tag for the appropriate validator type. For example, to declare the standard PhoneNumberValidator validator, you use the <mx:PhoneNumberValidator> tag, as the following example shows:

<?xml version="1.0"?>
<!-- validators\PNValidator.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <!-- Define the PhoneNumberValidator. -->
    <mx:PhoneNumberValidator id="pnV" 
        source="{phoneInput}" property="text"/>

    <!-- Define the TextInput control for entering the phone number. -->
    <mx:TextInput id="phoneInput"/>
    <mx:TextInput id="zipCodeInput"/>
</mx:Application>
The executing SWF file for the previous example is shown below:

In the previous example, you enter a value into the TextInput control for the phone number. When you remove focus from the TextInput control by selecting the TextInput control for the ZIP code, the validator executes.

You use the source property of the validator to specify an object, and the property property to specify a field of the object to validate. For more information on the source and property properties, see About the source and property properties.

Validator tags must always be immediate children of the root tag of an MXML file. In the previous example, the validator ensures that the user enters a valid phone number in the TextInput control. A valid phone number contains at least 10 digits, plus additional formatting characters. For more information, see Validating phone numbers.

You declare validators in ActionScript either in a script block within an MXML file, or in an ActionScript file, as the following example shows:

<?xml version="1.0"?>
<!-- validators\PNValidatorAS.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Script>
        <![CDATA[
            // Import PhoneNumberValidator.
            import mx.validators.PhoneNumberValidator;

            // Create the validator.
            private var v:PhoneNumberValidator = new PhoneNumberValidator();

            private function createValidator():void {
                // Configure the validator. 
                v.source = phoneInput;
                v.property = "text";
            }
        ]]>
    </mx:Script> 

    <!-- Define the TextInput control for entering the phone number. -->
    <mx:TextInput id="phoneInput" creationComplete="createValidator();"/>
    <mx:TextInput id="zipCodeInput"/>
</mx:Application>
The executing SWF file for the previous example is shown below:

About the source and property properties

Validators use the following two properties to specify the item to validate:

source Specifies the object containing the property to validate. Set this to an instance of a component or a data model. You use data binding syntax in MXML to specify the value for the source property. This property supports dot-delimited Strings for specifying nested properties.

property A String that specifies the name of the property of source that contains the value to validate.

You can set these properties in any of the following ways:

• In MXML when you use a validator tag.
• In ActionScript by assigning values to the properties.
• When you call the Validator.validate() method to invoke a validator programmatically. For more information, see Triggering validation programmatically.

You often specify a Flex user-interface control as the value of the source property, and a property of the control to validate as the value of the property property, as the following example shows:

<?xml version="1.0"?>
<!-- validators\ZCValidator.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:ZipCodeValidator id="zipV" 
        source="{myZip}" 
        property="text"/>
        
    <mx:TextInput id="phoneInput"/>
    <mx:TextInput id="myZip"/> 
</mx:Application>
The executing SWF file for the previous example is shown below:

In this example, you use the Flex ZipCodeValidator to validate the data entered in a TextInput control. The TextInput control stores the input data in its text property.

About triggering validation

You trigger validation either automatically in response to an event, or programmatically by an explicit call to the Validator.validate() method of a validator.

When you use events, you can cause the validator to execute automatically in response to a user action. For example, you can use the click event of a Button control to trigger validation on the fields of a form, or the valueCommit event of a TextInput control to trigger validation after a user enters information in the control. For more information, see Triggering validation by using events.

You can also trigger a validation programmatically. For example, you might have to inspect multiple, related input fields to perform a single validation. Or you might have to perform conditional validation based on a user input. For example, you may allow a user to select the currency used for payment, such as U.S. dollars or Euros. Therefore, you want to make sure that you invoke a validator configured for the specified currency. In this case, you can make an explicit call to the validate() method to trigger the correct validator for the input value. For more information, see Triggering validation programmatically.

About validating required fields

Flex validators can determine when a user enters an incorrect value into a user-interface control. In addition, all validators support the required property, which, if true, specifies that a missing or empty value in a user-interface control causes a validation error. The default value is true. Therefore, a validation error occurs by default if the user fails to enter any required data in a control associated with a validator. To disable this check, set the required property to false. For more information, see Validating required fields.

About validation errors

If a validation error occurs, by default Flex draws a red box around the component associated with the failure. If the user moves the mouse pointer over the component, Flex displays the error message associated with the error. You can customize the look of the component and the error message associated with the error. For more information on validation errors, see Working with validation errors.

About validation events

Validation is event driven. You can use events to trigger validation, programmatically create and configure validators in response to events, and listen for events dispatched by validators.

For example, when a validation operation completes, a validator dispatches a valid or invalid event, depending on the results of the validation. You can listen for these events, and then perform any additional processing that your application requires.

Alternatively, Flex components dispatch valid and invalid events, depending on the results of the validation. This lets you listen for the events being dispatched from the component being validated, rather than listening for events dispatched by the validator.

You are not required to listen for validation events. By default, Flex handles a failed validation by drawing a red box around the control that is associated with the source of the data binding. For a successful validation, Flex clears any indicator of a previous failure. For more information, see Working with validation events.

About custom validation

Although Flex supplies a number of predefined validators, you might find that you have to implement your own validation logic. The mx.validators.Validator class is an ActionScript class that you can extend to create a subclass that encapsulates your custom validation logic. For more information on creating custom validators, see Custom Validators.