by Adobe



22 March 2010

User level
Required products
All Flex Builder (Download trial)
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.
This article covers the following topics:

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:
<?xml version="1.0" encoding="utf-8"?> <!-- FormatterSimple.mxml --> <s:Application xmlns:fx="" xmlns:s="library://" xmlns:mx="library://" width="310" height="210" initialize="focusManager.setFocus(phoneInput);"> <fx:Declarations> <mx:PhoneFormatter id="phoneDisplay" formatString="(###) ###-####"/> </fx:Declarations> <!-- User interface --> <s:Panel title="Using a formatter"> <s:layout> <s:VerticalLayout paddingLeft="10" paddingRight="10" paddingTop="10" paddingBottom="10"/> </s:layout> <s:Label text="Enter a phone number, including{'\r'}the area code{'\r'}e.g., 2025558721:"/> <s:TextInput id="phoneInput" width="100%"/> <!-- Display the formatted phone number --> <s:Label text="{'Formatted: '+phoneDisplay.format(phoneInput.text)}"/> </s:Panel> </s:Application>

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:
<?xml version="1.0" encoding="utf-8"?> <!-- FormatterErrorHandling.mxml --> <s:Application xmlns:fx="" xmlns:s="library://" xmlns:mx="library://" width="400" height="140"> <fx: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; } ]]> </fx:Script> <fx:Declarations> <!-- Declare a formatter and specify formatting properties.--> <mx:DateFormatter id="myFormatter" formatString="MXXXMXMXMXMXM"/> </fx:Declarations> <!-- User interface --> <s:Panel title="Handling formatter errors"> <s:layout> <s:VerticalLayout paddingLeft="10" paddingRight="10" paddingTop="10" paddingBottom="10"/> </s:layout> <!-- Trigger the formatter while populating a string with data.--> <s:Label text="Your order shipped on: {'\r'}{formatWithError('May 23, 2005')}"/> </s:Panel> </s:Application>
Note: This application is not interactive; it demonstrates handling an error in a formatting string.

For more information