Developer Network Home  Help 

YDN Flash Developer Center Astra Flash Components Using Form
Flash Developer Center

ASTRA Form

Form is a UI component used for the layout and alignment of form elements. Like the Flex Form Class, it contains multiple vertically positioned component items with label arrangement determined by width. Additionally, it supports data collection and validation implemented in a corresponding validation and data manager class.

Using Form in Flash CS3

Understanding Form class

The primary purpose of the Form Class is to provide convenient visual alignment and data handling for HTML-like input forms. There are two classes that can be used in conjunction with the Form class to build an input form. The FormItem class handles visual alignment of form elements and the FormDataManager class manages form data.

Layout Form

Similar to the Flex Form container, Astra Form is usually used with nested FormItems and allows you to set styles for configuring the appearance of your form.

Adding Items to a Form

As seen in Getting Started, the easiest way to add items to a Form is to use a data array and pass it into dataSource. First, you must set data manager(formDataManager) in Form to handle the collected data, and than set the data property to an array which will collect the names and sources of data that will be applied to a Form. Let's see the possible data source in the data array.

(For the properties below, see Validating and storing for details.)

The following code shows a use of dataSource method in Form :

Setting styles

As an extended property of UIcomponent, You can use setStyle to set style property. However, calling this method can result in decreased performance. Use it only when necessary. For more informaion, see defaultStyles at com.yahoo.astra.fl.containers.FormClasses.FormLayoutStyle class.


Validating and storing form data

Form is mainly dedicated to the layout and alignment of forms. However, you can also use FormDataManager to collect user input data and validate it before you submit the data to the server. Astra does not provide a separate validation class, but there are compatible validation classes available from Adobe. See the Validator section for details.

  • Using FormDataManager

    To use FormDataManager in a Form, initialize and assign it to the Form before assigning the data array to dataSource. The FormDataManager constructor takes a value parser class(IValueParser) which will be used to collect user input. If your Form uses any CS3 UIcomponents, use the FlValueParser optimized for it, unless you want to apply your own custom value parser implementing IvalueParser.

  • Using dataSource in FormDataManager
    To specify the data field to be stored, you can add the property below in the dataSource array.

    • id : String (required)
    • source : Object (required)
    • property : Object (default = null)
    • required : Boolean (default = false)
    • validator : Function (default = null)
    • validatorExtraParam : Object (default = null)
    • errorString : String(default = undefined)
    • targetObj : DisplayObject (default = null)
    • functionValidationPassed : Function (default = null)
    • functionValidationFail : Function (default = null)

    In addition, you can use FormDataManager as a standalone manager class dedicated to data collection and validation without attaching Form. FormDataManager collects attributes through the addItem or dataSource property. See the example below.


    • id

      Since a FormDataManager collects and saves data in the form of associative arrays, "id" will be used as a property of the array(e.g. collectedData["zip"] = "94089"). Any property that has no designated id will be ignored. If you have multiple "id"s on one FormItem, you will need multiple instances of the following properties as well.(e.g. "source","property", "required",...)


    • source, property

      "source" points to the actual user input form objects. "property" specifies the name of the property of the source. For instance, if you have a TextInput component named as "nameInput" contained in FormItem by the "items" property, you can collect data in it when the user triggers the data collection. In this case, "nameInput" will be the "source" and "property" will be "text" by nature of TextInput. However, if you defined UIcomponent or textField as a "source", you don't need to specify the "property" unless you are expecting a non-standard result (e, g. If the source is ComboBox, you don't have to specify its property, "data", as long as you want to retrieve data from it). See the ValueParser class and FlValueParser for full details.


    • required, validator

      The required property has two roles. It verifies the visual presentation of a required field as well as enforces validation of the designated field. Therefore, if you have a field you want to enforce that the user fills with valid information, you need to define both "required" and "validator". A FormItem that has a "validator" but not a "required" set to "true" will be stored into FormDataManager.collectedData no matter if it has passed validation or not.

      Validation in FormDataManager is the process of checking that all required form items have been filled in correctly before the data is processed to the server. (For example, if your form has a TextInput field for a phone number, you might want the required input the user specifies to have the correct type.) The validator is a function property with a validation class and targeted method as an object. To use validation in FormDataManager, you should initialize the proper validation class and pass the desired function in the validator property. The validator takes a value of type Function in which the first argument is a String type(e.g. public function isEmail(str:String):as3ValidationResult {...}). The user input value will be passed into the function for verification and will be stored via the returned result. The current version of FormDataManager, supports the flash-validators provided by Adobe. For more details, refer to the Google code site : http://code.google.com/p/flash-validators. To use flash-validators,first import and initialize the flash-validators then point to the function

      Another option for the validation is the mx.validators distributed in the Flex SDK. For convenient use of Flex validators, you can use the Astra MXValidationHelper class. Flex mx.validators provides a variety of validation types and detailed error messages. However, the use of the Flex MXvalidator will increase your overall file size by approximately 20K.


  • Data collection and Error handling
    • Adding a trigger

      Unlike Flex Form, you can not add trigger validation on each FormItem. Instead, you can add a global trigger event for all validation and data storage. The addTrigger function adds a listener on the displayObject's(first parameter) MouseEvent.CLICK event, and defines a handler function for validation success(second parameter) and failure(third parameter).

      Below is the same process as addTrigger in the FormDataManager. You can apply custom trigging action to call FormDataManager.collectData.


    • Data events

      Once the data validation function is triggered, FormDataManager creates two Flash objects: FormDataManager.collectedData and FormDataManager.failedData. The collected data form input fields will be added as a new key-value pair by creating a new property using the returned validation result. Values returned from validation will be collected in FormDataManager.collectedData (e.g. if an item that has "id" as "email" is passed the email validation, the value acquired from source will be stored in collectedData in FormDataManager as : FormDataManager.collectedData["email"] = "address@yahoo.com").If required input fails validation, the error string will be stored in failedData in FormDataManager(e.g. FormDataManager.failedData["email"] = "Missing an @ character in your email address."). This process continues for all of the items having "id" and "source" validated.

      If all of the required data passed the validation, FormDataManager will dispatch FormDataManagerEvent.DATACOLLECTION_SUCCESS, otherwise, it will dispatch FormDataManagerEvent.DATACOLLECTION_FAIL. If there are defined attributes of functionDataCollectionSuccess and functionDataCollectionFail in addTrigger function, these functions will be triggered by the events.


    • functionValidationPassed, functionValidationFail, eventTargetObj

      By default, a FormItem having required parameter registers FormDataManagerEvent listeners with type of FormDataManagerEvent.VALIDATION_PASSED and FormDataManagerEvent.VALIDATION_FAILED to eventTargetObj. You need to set functionValidationPassed and functionValidationFail to listener functions for these event types in the FormDataManager before set dataSource.

      As an option, you can set functionValidationPassed and functionValidationFail along with eventTargetObj for detailed result handling in each item.

      Any FormItem in a Form that is required with a validation will be assigned as an eventTargetObj by default.


    • showErrorMessageBox, showErrorMessageText

      For visual presentation of error information for data that failed validation, Form provides two methods: showErrorMessageText, and showErrorMessageBox. The showErrorMessageText property displays the returned error string under the targeted item. By setting showErrorMessageBox to true, each FormItems in Form will listen the validation events(FormDataManagerEvent.VALIDATION_PASSED, FormDataManagerEvent.VALIDATION_FAILED) and present a translucent gray box under the item that failed to validate. The default setting for the ErrorMessageBox is color: 0x666666 and alpha: 0.2.
      See       setStyle to set the property of the color and alpha of the gray box.

      err_handler

      Both as3DataValidation and MXValidators return error strings as the result of validation failure. However, for the results that have no error string defined in the validator, the default string, "Invalid input", is provided. You can change it to your custom message by setting errorString property.

      You can also specify errorString on each FormItem.


      • If showErrorMessageText is true and there is existing instructionText, the instructionText will be replaced by errorString.

    For additional information, please take a look at the Examples section for functional demonstrations and the ActionScript 3.0 Class Reference for full details on every property, method, and styles available to the Form component.