HowToUseCairngormValidation

How to Use the Cairngorm Validation Library

Summary

The Cairngorm Validation library is designed to simplify validation of user input and other data. Instead of declaring validators individually in MXML and coordinating them manually, a group of validators can be defined using the ValidatorGroup component. The validity of the whole group can then be determined as one. Validator groups can be nested and detached from the view and applied to other layers of an application, such as a domain model. Additional components are provided for observing validation rules and updating view components to highlight validation errors.

Grouping of Validators

Standard Flex validators of the mx.validators package can be grouped with the ValidatorGroup component in MXML:

<validators:ValidatorGroup id="validatorGroup">
    <validators:validators>

        <mx:StringValidator id="firstnameValidator"
                            source="{ firstnameInput }"
                            required="true"
                            minLength="3"
                            property="text"
                            triggerEvent="change"/>

        <mx:StringValidator id="lastnameValidator"
                            source="{ lastnameInput }"
                            required="true"
                            minLength="2"
                            property="text"
                            triggerEvent="change"/>

    </validators:validators>

</validators:ValidatorGroup>

or ActionScript

var validatorGroup:ValidatorGroup=new ValidatorGroup();

var firstnameValidator:StringValidator=new StringValidator();
firstnameValidator.required=true;
firstnameValidator.source=firstnameInput;
firstnameValidator.property="text";

var lastnameValidator:StringValidator=new StringValidator();
lastnameValidator.required=true;
lastnameValidator.source=lastnameInput;
lastnameValidator.property="text";

validatorGroup.addValidator(firstnameValidator);
validatorGroup.addValidator(lastnameValidator);

Control Visual Validation

Notice the connection of the Validator to the TextInput controls via the source property of StringValidator. This connection allows Flex controls to react visually (i.e. via a red border and error tip) once a validator is triggered. ValidatorGroup allows to controls when this visual validation should appear.

The validate method returns the validation result of the group and optionally forces the visual validation on connected Flex controls.

Usually, when a user enters an input form, the form controls should not be immediately displayed in an invalid state but wait until the user enters invalid input. In some situations (i.e. after a user logout) a form needs to reset its state to this "first enter" state where input controls do not visually show they are invalid. The reset method of ValidatorGroup allows an easier mechanism to implement this feature than manipulating each form control manually.

Add/Remove, Enable/Disable, and Nested Validators

ValidatorGroup also offers the ability to disable validations using the enableValidator method and allows to add or remove validators or other ValidatorGroup objects at runtime using the addValidator and removeValidator methods. ValidatorGroups can also be arbitrarily nested such as the below example shows:

<validators:ValidatorGroup id="validatorGroup">
    <validators:validators>

        <mx:StringValidator id="firstnameValidator"
                            source="{ firstnameInput }"
                            required="true"
                            minLength="3"
                            property="text"
                            triggerEvent="change"/>

        <mx:StringValidator id="lastnameValidator"
                            source="{ lastnameInput }"
                            required="true"
                            minLength="2"
                            property="text"
                            triggerEvent="change"/>

    </validators:validators>

    <validators:groups>

        <validators:ValidatorGroup id="subValidatorGroup">
            <validators:validators>
                <mx:StringValidator id="addressValidator"
                                    source="{ addressInput }"
                                    required="true"
                                    minLength="5"
                                    property="text"
                                    triggerEvent="change"/>
            </validators:validators>
        </validators:ValidatorGroup>

    </validators:groups>

</validators:ValidatorGroup>

Domain Validation

In many cases the responsibility of client side validation relates more to the client side domain layer instead of particular view components. The Contact object of the ModularExtendedAPI project (see this tutorial for more information) encapsulates the knowledge that a Contact can only be valid when it contains 3 characters of the first and last name. Encapsulating this knowledge in a domain object ensures that every view component displaying contacts can reuse this behaviour. Even though ValidatorGroup is not declared in the view, it is convenient to declare concrete validators (using Flex SDK validation utilities) in MXML. Note that MXML is just a syntax and does not only need to be used in the presentation layer. Below is the Contact object and it's validator instantiation:

public var validatorGroup:ContactValidators=new ContactValidators();

public function Contact()
{
    validatorGroup.model=this;
    validatorGroup.initialized(this, "contactValidators");
    validatorGroup.validate(true);
}

and the ContactValidators object of Contact :

<validators:ValidatorGroup xmlns:validators="com.adobe.cairngorm.validation.*"
                           xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Script>
        <![CDATA[
            [Bindable]
            public var model:Contact;
        ]]>
    </mx:Script>

    <validators:validators>

        <mx:StringValidator id="firstnameValidator"
                            required="true"
                            minLength="3"
                            source="{ model }"
                            property="firstName"
                            triggerEvent="propertyChange"/>

        <mx:StringValidator id="lastnameValidator"
                            required="true"
                            minLength="2"
                            source="{ model }"
                            property="lastName"
                            triggerEvent="propertyChange"/>

    </validators:validators>

</validators:ValidatorGroup>

In order to connect the domain validation behaviour with specific view controls, the ValidatorGroupSubscriber of the Validation library is used. This connects the validation of the Contact domain to TextInput controls of that a particular view component.

<validation:ValidatorGroupSubscriber>
    <validation:ValidatorSubscriber validator="{ contact.validatorGroup.firstnameValidator }"
                                    listener="{ firstNameInput }"/>
    <validation:ValidatorSubscriber validator="{ contact.validatorGroup.lastnameValidator }"
                                    listener="{ lastNameInput }"/>
</validation:ValidatorGroupSubscriber>
### Cairngorm 3 - [ Home ][1] - [ Guidelines ][3] - [ Tools ][4] - [ Libraries Downloads ][2]
### Cairngorm 2 - [ Home ][5] - [ Framework Downloads ][6] - [ Eclipse Plugin ][7]
### Project - [ Source ][8] - [ Bug Database ][9] - [ Submitting a Patch ][10] - [ Developer Documentation ][11] - [ Forums ][12] - [ License ][13]