1. Home
2. Developer Connection
3. Flex Developer Center
4. Flex Quick Start

Flex Quick Starts: Handling data

Table of contents

• Defining data models
• Using data binding
• Validating data
• Formatting data
• Accessing XML data
• Loading external data with HTTPService

Formatting data

Adobe Flex formatters are components that you use to format data into strings. Formatters perform a one-way conversion of raw data to a formatted string. They are usually triggered just before data is displayed in a text field. Flex includes standard formatters that let you format currency, dates, numbers, phone numbers, and ZIP codes.

All Flex formatters are subclasses of the mx.formatters.Formatter class. The Formatter class declares a format() method that takes a value and returns a String value.

For most formatters, when an error occurs, an empty string is returned and a string that describes the error is written to the formatter's error property. The error property is inherited from the Formatter class.

• Creating and using a formatter
• Handling formatter errors
• Using formatters in item renderers

Creating and using a formatter

The following steps describe the general process for using a formatter:

1. Declare a formatter in your MXML code, specifying the appropriate formatting properties.
2. Call the formatter's format() method within the curly braces ({ }) syntax for binding data, and specify the value to be formatted as a parameter to the format() method.

The following example formats a 10-digit phone number that a user inputs in an application using the TextInput control:

Example

<?xml version="1.0" encoding="utf-8"?>
<mx:Application 
    xmlns:mx="http://www.adobe.com/2006/mxml"
    viewSourceURL="src/FormatterSimple/index.html"
    width="310" height="210"
    initialize="focusManager.setFocus(phoneInput);"
>

    <mx:PhoneFormatter id="phoneDisplay"
        formatString="(###) ###-####" 
    />

    <!-- User interface -->

    <mx:Panel
        title="Using a formatter in an item renderer"
        paddingLeft="10" paddingRight="10" paddingBottom="10" paddingTop="10"
    >
        <mx:Text text="Enter a phone number, including{'\r'}the area code{'\r'}e.g., 2025558721:"/>
        <mx:TextInput id="phoneInput" width="100%"/>    
           
           <!-- Display the formatted phone number -->
           <mx:Text text="{'Formatted: '+phoneDisplay.format(phoneInput.text)}"/>    
    </mx:Panel>        
</mx:Application>

Result

This content requires Flash

Download the free Flash Player now!

To view the full source, right-click the Flex application and select View Source from the context menu.

Back to top

Handling formatter errors

The protocol for formatters when detecting an error is to return an empty string, and to write a string that describes the error condition to the error property of the formatter. You can check for an empty string in the return value of the format() method, and if found, access the error property to determine the cause of the error.

Alternatively, you can write a function that returns an error message for a formatting error. The following example shows a simple error handler function:

Example

<?xml version="1.0" encoding="utf-8"?>
<mx:Application 
    xmlns:mx="http://www.adobe.com/2006/mxml"
    viewSourceURL="src/FormatterErrorHandling/index.html"
    width="400" height="140"
>
    <mx:Script>
        <![CDATA[    
            private function formatWithError(value:Object):String 
            {
                var formatted:String = myFormatter.format(value);
                if (formatted == "") 
                {
                    if (myFormatter.error != null ) 
                    {
                        if (myFormatter.error == "Invalid value") 
                        {
                            formatted = "The value used in the format function";
                            formatted += " is not a valid value.";
                        }
                        else 
                        {
                            formatted = "The formatString provided is not";
                            formatted += " a valid formatString.";                         
                        }
                    }
                }
                return formatted;
            }
        ]]>
    </mx:Script>
    <!-- Declare a formatter and specify formatting properties.-->
    <mx:DateFormatter 
        id="myFormatter" 
        formatString="MXXXMXMXMXMXM"
    />
    <!-- User interface -->
    <mx:Panel
        title="Handling formatter errors"
        paddingLeft="10" paddingRight="10" paddingBottom="10" paddingTop="10"
    >
        <!-- Trigger the formatter while populating a string with data.-->
        <mx:Text 
            text="Your order shipped on: {'\r'}{formatWithError('May 23, 2005')}"
        />
    </mx:Panel>        
</mx:Application>

Result

Note: This application is not interactive; it demonstrates handling an error in a formatting string.

This content requires Flash

Download the free Flash Player now!

To view the full source, right-click the Flex application and select View Source from the context menu.

Back to top

Using formatters in item renderers

You can use a formatter inside an item renderer to apply formatting to items in controls such as the List and DataGrid. The following example defines a List control that has an in-line item renderer. The item renderer contains a currency formatter component and a label control. The label control has its text property bound to the current data item for the current row in the List control and uses the currency formatter to format this data in Great Britain Pounds.

Example

<?xml version="1.0" encoding="utf-8"?>
<mx:Application 
    xmlns:mx="http://www.adobe.com/2006/mxml"
    viewSourceURL="src/FormatterItemRenderer/index.html"
    width="340" height="340"
    initialize="focusManager.setFocus(priceInput);"
    defaultButton="{submitButton}"
>
    <mx:Boolean id="formIsValid"/>
    <mx:ArrayCollection id="prices"/>
    <mx:NumberValidator
        id="numberValidator"
        source="{priceInput}"
        property="text"
        allowNegative="false"
        domain="int"
    />
    <mx:Panel
        title="Using a formatter in an item renderer"
        paddingLeft="10" paddingRight="10" paddingBottom="10" paddingTop="10"
    >
        <mx:List 
            id="priceList" 
            rowCount="5" width="100%"
            dataProvider="{prices}"
        >
            <mx:itemRenderer>
                <mx:Component>
                    <mx:VBox>
                        <mx:CurrencyFormatter
                            id="gbpFormat"
                            alignSymbol="left" 
                            currencySymbol="£"
                        /> 
                        <mx:Label 
                            text="{gbpFormat.format(data)}" 
                        />                                    
                    </mx:VBox>
                </mx:Component>
            </mx:itemRenderer>
        </mx:List>
        <mx:Label text="Enter a number below and click the button:"/>
        <mx:TextInput 
            id="priceInput" 
            width="100%"
            change="formIsValid=numberValidator.validate().type == 'valid'"
        />        
        <mx:ControlBar horizontalAlign="center">
            <mx:Button 
                id="submitButton"
                label="Add to list"
                enabled="{formIsValid}"
                click="prices.addItem(priceInput.text);"
            />
        </mx:ControlBar>
    </mx:Panel>        
</mx:Application>

Result

This content requires Flash

Download the free Flash Player now!

To view the full source, right-click the Flex application and select View Source from the context menu.

Back to top

For more information

• Validation and formatting in the Flex 3 Getting Started Experience
• Formatting data in the Adobe Flex 3 Help

About the author