Flex defines two sets of formatters: Spark and MX. The Spark formatters rely on the classes in the flash.globalization package. The flash.globalization classes use the locale data provided by the operating system. Therefore, Spark formatters provide behavior that is consistent with the operating system and have access to all the locales that are supported by the operating system.

MX formatters use the Flex ResourceManager to access locale-specific data from properties files that are included in the Flex SDK. The MX formatters provide the same behavior across operating systems, but are limited to the locales provided by the Flex SDK or by the application developer.

The following table lists the Spark and MX formatting classes. When possible, it's best that you use the Spark formatters in your application:

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

1. Declare a formatter in an <fx:Declarations> tag in your MXML code, specifying the appropriate formatting properties. You define formatters in an <fx:Declarations> tag because they are not visual components.

   You can also create formatters in ActionScript for use in an application.

2. Call the formatter's format() method, and specify the value to be formatted as a parameter to the format() method. The format() method returns a String containing the formatted value.

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

<?xml version="1.0"?> 
<!-- formatters\Formatter2TextFields.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx"> 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
 
    <fx:Declarations> 
        <!-- Declare a PhoneFormatter and define formatting parameters.--> 
        <mx:PhoneFormatter id="phoneDisplay" 
            areaCode="415" 
            formatString="###-####" /> 
    </fx:Declarations> 
 
    <!-- Declare the input control.--> 
    <s:Label text="Enter 7 digit phone number (########):"/> 
    <s:TextInput id="myTI"/> 
    
    <!-- Declare the control to display the formatted data.--> 
    <s:TextArea text="{phoneDisplay.format(myTI.text)}"/> 
</s:Application>

In this example, you use the MX PhoneFormatter class to display the formatted phone number in a TextArea control. The format() method is called as part of a data binding expression when the text property of the TextInput control changes.

<?xml version="1.0" encoding="utf-8"?> 
<!-- formatters\sparkformatters\SparkFormatterDateField.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx"> 
    <s:layout> 
        <s:VerticalLayout paddingTop="10" paddingLeft="5"/> 
    </s:layout> 
    
    <fx:Declarations> 
        <!-- Declare a Spark DateTimeFormatter and 
             define formatting parameters.--> 
        <s:DateTimeFormatter id="dateTimeFormatter"/> 
    </fx:Declarations> 
    
    <s:Label text="Enter date (mm/dd/yyyy):"/> 
    <s:TextInput id="dob" text=""/> 
    
    <s:Label text="Formatted date: "/> 
    <s:TextInput id="formattedDate" 
        text="" width="300" 
        editable="false"/> 
    
    <!-- Format and update the date.--> 
    <s:Button label="Format Input" 
        click="formattedDate.text=dateTimeFormatter.format(dob.text);"/> 
</s:Application>

You call the format() method to format a value. By default, if the format() method fails, it returns null. However, you can use the errorText property of the formatter to define a String to return, as the following example shows:

<?xml version="1.0" encoding="utf-8"?> 
<!-- formatters\sparkformatters\SparkFormatterError.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx"> 
    <s:layout> 
        <s:VerticalLayout paddingTop="10" paddingLeft="5"/> 
    </s:layout> 
    
    <fx:Declarations> 
        <!-- Declare a Spark DateTimeFormatter and 
        define formatting parameters.--> 
        <s:DateTimeFormatter id="dateTimeFormatter" 
            dateTimePattern="month: MM, day: DD, year: YYYY" 
            errorText="Invalid input value"/> 
    </fx:Declarations> 
    
    <s:Label text="Enter date (mm/dd/yyyy):"/> 
    <s:TextInput id="dob" text=""/> 
    
    <s:Label text="Formatted date: "/> 
    <s:TextInput id="formattedDate" 
        text="" width="300" 
        editable="false"/> 
    
    <!-- Format and update the date.--> 
    <s:Button label="Format Input" 
        click="formattedDate.text=dateTimeFormatter.format(dob.text);"/> 
</s:Application>

The Spark NumberFormatter class provides basic formatting options for numeric data, including decimal formatting, thousands separator formatting, and negative sign formatting.

The format() method accepts a number or a number formatted as a String value, and returns the formatted string. When a number formatted as a String value is passed to the format() method, the function first uses the Number() function to convert the String to a Number object.

<?xml version="1.0" encoding="utf-8"?> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx" minWidth="955" minHeight="600"> 
    <s:layout> 
        <s:VerticalLayout paddingTop="10" paddingLeft="5"/> 
    </s:layout> 
 
    <fx:Script> 
        <![CDATA[ 
            protected function button2_clickHandler(event:MouseEvent):void { 
                displayVal.text = PrepForDisplay.format(bigNumber.text); 
            } 
        ]]> 
    </fx:Script> 
 
    
    <fx:Declarations> 
        <!-- Declare and define parameters for the NumberFormatter.--> 
        <s:NumberFormatter id="PrepForDisplay" 
            fractionalDigits="3" 
            decimalSeparator="." 
            groupingSeparator="," 
            useGrouping="true" 
            negativeNumberFormat="0" 
            errorText="'{bigNumber.text}' is an invalid input value"/> 
    </fx:Declarations> 
    
    <!-- String to format.--> 
    <s:TextInput id="bigNumber" text="Enter number"/>  
    <s:Button label="Format Value" 
        click="button2_clickHandler(event);"/> 
    
    <!-- Display formatted value.--> 
    <s:Label id="displayVal"/> 
</s:Application>

The Spark CurrencyFormatter class provides the same features as the NumberFormatter class, plus a currency symbol. It also has additional properties to control the formatted result: currencySymbol, negativeCurrencyFormat, and positiveCurrencyFormat.

The format() method accepts a Number value or a number formatted as a String value and formats the resulting string. When a number formatted as a String value is passed to the format() method, the function first uses the Number() function to convert the String to a Number object.

The useCurrencySymbol property determines the currency symbol returned in the formatted String based on the locale style property. When the useCurrencySymbol property is set to true, the formatter returns the value of the currencySymbol property in the formatted String. When the useCurrencySymbol property is set to false, the formatter returns the value of the currencyISOCode property in the formatted String.

<?xml version="1.0" encoding="utf-8"?> 
<!-- formatters\sparkformatters\SparkCurrencyFormatter.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx"> 
    <s:layout> 
        <s:VerticalLayout paddingTop="10" paddingLeft="5"/> 
    </s:layout> 
    
    <fx:Script> 
        <![CDATA[ 
            protected function button1_clickHandler(event:MouseEvent):void { 
                displayVal.text = Price.format(currVal.text); 
            } 
        ]]> 
    </fx:Script> 
    
    <fx:Declarations> 
        <!-- Declare a CurrencyFormatter and define parameters.--> 
        <s:CurrencyFormatter id="Price" 
            currencySymbol="$" 
            useCurrencySymbol="true" 
            negativeCurrencyFormat="0" 
            positiveCurrencyFormat="0" 
            errorText="'{currVal.text}' is an invalid input value"/> 
    </fx:Declarations> 
    
    <!-- Enter currency value, then click the Button to format. --> 
    <s:TextInput id="currVal" text="Enter value"/> 
    <s:Button label="Format Value" 
        click="button1_clickHandler(event);"/> 
 
    <!-- Display formatted value.--> 
    <s:Label id="displayVal"/> 
    
</s:Application>

The Spark DateTimeFormatter class gives you a wide range of combinations for displaying date and time information. The format() method accepts a Date object, which it converts to a String based on a user-defined pattern.

The format() method can also accept a String-formatted date. If you pass a String, the formatter first converts it to a Date object by using the Date constructor. The hour value in the String must be between 0 and 23, inclusive. The minutes and seconds value must be between 0 and 59, inclusive. If the format() method is unable to parse the String into a Date object, it returns null.

The following examples show possible input strings to the format() method:

 "12/31/98" or "12-31-98" or "1998-12-31" or "12/31/1998" 
 "Friday, December 26, 2005 8:35 am" 
 "Jan. 23, 1989 11:32:25"

yyyy.MM.dd 'at' h:mm:ss

EEE, MMM d, yy

k:mm a

K:mm a

yyyy.MMMM.dd HH:mm:ss

<?xml version="1.0" encoding="utf-8"?> 
<!-- formatters\spark\SparkDateFormatter.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx" minWidth="955" minHeight="600"> 
    <s:layout> 
        <s:VerticalLayout paddingTop="10" paddingLeft="5"/> 
    </s:layout> 
    
    <fx:Script> 
        <![CDATA[ 
            // Define variable to hold the date.        
            [Bindable] 
            private var today:Date = new Date();        
        ]]> 
    </fx:Script> 
    
    <fx:Declarations> 
        <!-- Declare a DateFormatter and define parameters.--> 
        <s:DateTimeFormatter id="DateDisplay1" 
            dateTimePattern="MMMM d, yyyy"/> 
 
        <s:DateTimeFormatter id="DateDisplay2" 
            dateTimePattern="hh:mm a"/> 
 
        <s:DateTimeFormatter id="DateDisplay3" 
            dateTimePattern="hh:mm a, MMMM d, yyyy"/> 
 
        <s:DateTimeFormatter id="DateDisplay4" 
            dateTimePattern="yyyy.MMMM.dd HH:mm:ss"/> 
</fx:Declarations> 
    
    <!-- Display the date in a Label control.--> 
    <s:Label id="myTA1" text="{DateDisplay1.format(today)}"/> 
    <!-- Display the date in a Label control.--> 
    <s:Label id="myTA2" text="{DateDisplay2.format(today)}"/> 
    <!-- Display the date in a Label control.--> 
    <s:Label id="myTA3" text="{DateDisplay3.format(today)}"/> 
    <!-- Display the date in a Label control.--> 
    <s:Label id="myTA4" text="{DateDisplay4.format(today)}"/> 
</s:Application>

For most formatters, when an error occurs, the format() method returns an empty string is and a string describing the error is written to the formatter's error property. 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 an error handler function that returns an error message for a formatting error. The following example shows a simple error handler function:

<?xml version="1.0"?> 
<!-- formatters\FormatterSimpleErrorForDevApps.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx"> 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
 
    <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 is not valid."; 
                        } 
                        else { 
                            formatted = ": The formatString is not valid."; 
                        } 
                    } 
                } 
                return formatted; 
            } 
        ]]> 
    </fx:Script> 
 
    <fx:Declarations> 
        <!-- Declare a formatter and specify formatting properties.--> 
        <mx:DateFormatter id="myFormatter" 
            formatString="MXXXMXMXMXMXM"/> 
    </fx:Declarations> 
 
    <!-- Trigger the formatter while populating a string with data.--> 
    <s:TextInput id="myTI" 
        width="75%" 
        text="Your order shipped on {formatWithError('May 23, 2005')}"/> 
</s:Application>

In this example, you define a DateFormatter with an invalid format string. You then use the formatWithError() method to invoke the formatter in the TextInput control, rather than calling the Date formatter's format() method directly. In this example, if either the input string or the format string is invalid, the formatWithError() method returns an error message instead of a formatted String value.

The MX CurrencyFormatter class provides the same features as the NumberFormatter class, plus a currency symbol. It has two additional properties: currencySymbol and alignSymbol. (For more information about the NumberFormatter class, see Formatting numbers with an MX formatter.)

The CurrencyFormatter class provides basic formatting options for numeric data, including decimal formatting, thousands separator formatting, and negative sign formatting. The format() method accepts a Number value or a number formatted as a String value and formats the resulting string.

When a number formatted as a String is passed to the format() method, the function parses the string from left to right and attempts to extract the first sequence of numbers it encounters. The function parses the thousands separators and decimal separators along with their trailing numbers. The parser searches for a comma (,) for the thousands separator unless you set a different character in the thousandsSeparatorFrom property. The parser searches for a period (.) for the decimal separator unless you define a different character in the decimalSeparator property.

<?xml version="1.0"?> 
<!-- formatters\MainCurrencyFormatter.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx"> 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
 
    <fx:Script> 
        <![CDATA[ 
            // Define variable to hold the price.        
            [Bindable] 
            private var todaysPrice:Number=4025; 
        ]]> 
    </fx:Script> 
 
    <fx:Declarations> 
        <!-- Declare a CurrencyFormatter and define parameters.--> 
        <mx:CurrencyFormatter id="Price" precision="2" 
            rounding="none" 
            decimalSeparatorTo="." 
            thousandsSeparatorTo="," 
            useThousandsSeparator="true" 
            useNegativeSign="true" 
            currencySymbol="$" 
            alignSymbol="left"/> 
    </fx:Declarations> 
 
    <!-- Trigger the formatter while populating a string with data.--> 
    <s:TextInput text="Today's price is {Price.format(todaysPrice)}." 
        width="200"/> 
</s:Application>

Invalid value

Invalid format

The MX DateFormatter class gives you a wide range of combinations for displaying date and time information. The format() method accepts a Date object, which it converts to a String based on a user-defined pattern. The format() method can also accept a String-formatted date, which it attempts to parse into a valid Date object prior to formatting.

The DateFormatter class has a parseDateString() method that accepts a date formatted as a String. The parseDateString() method examines sections of numbers and letters in the String to build a Date object. The parser is capable of interpreting long or abbreviated (three-character) month names, time, am and pm, and various representations of the date.

The hour value in the String must be between 0 and 23, inclusive. The minutes and seconds value must be between 0 and 59, inclusive. If the parseDateString() method is unable to parse the String into a Date object, it returns null.

The following examples show some of the ways strings can be parsed:

 "12/31/98" or "12-31-98" or "1998-12-31" or "12/31/1998" 
 "Friday, December 26, 2005 8:35 am" 
 "Jan. 23, 1989 11:32:25"

The DateFormatter class parses strings from left to right. A date value should appear before the time and must be included. The time value is optional. A time signature of 0:0:0 is the Date object's default for dates that are defined without a time. Time zone offsets are not parsed.

YYYY.MM.DD at HH:NN:SS

EEE, MMM D, 'YY

H:NN A

HH o'clock A

K:NN A

YYYYY.MMMM.DD. JJ:NN A

EEE, D MMM YYYY HH:NN:SS

<?xml version="1.0"?> 
<!-- formatters\MainDateFormatter.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx"> 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
 
    <fx:Script> 
        <![CDATA[ 
            // Define variable to hold the date.        
            [Bindable] 
            private var today:Date = new Date();        
        ]]> 
    </fx:Script> 
 
    <fx:Declarations> 
        <!-- Declare a DateFormatter and define parameters.--> 
        <mx:DateFormatter id="DateDisplay" 
            formatString="MMMM D, YYYY"/> 
    </fx:Declarations> 
 
    <!-- Display the date in a TextArea control.--> 
    <s:TextInput id="myTA" text="{DateDisplay.format(today)}"/> 
</s:Application>

Invalid value

Invalid format

The MX NumberFormatter class provides basic formatting options for numeric data, including decimal formatting, thousands separator formatting, and negative sign formatting. The format() method accepts a number or a number formatted as a String value, and formats the resulting string.

When a number formatted as a String value is passed to the format() method, the function parses the string from left to right and attempts to extract the first sequence of numbers it encounters. The function parses the thousands separators and decimal separators along with their trailing numbers. The parser searches for a comma (,) for the thousands separator unless you set a different character in the thousandsSeparatorFrom property. The parser searches for a period (.) for the decimal separator unless you define a different character in the decimalSeparator property.

The rounding and precision properties of the MX NumberFormatter class affect the formatting of the decimal in a number. If you use both rounding and precision properties, rounding is applied first, and then the decimal length is set by using the specified precision value. This lets you round a number and still have a trailing decimal; for example, 303.99 = 304.00.

<?xml version="1.0"?> 
<!-- formatters\MainNumberFormatter.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx"> 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
 
    <fx:Script> 
        <![CDATA[ 
            // Define variable to hold the number.        
            [Bindable] 
            private var bigNumber:Number = 6000000000.65; 
        ]]> 
    </fx:Script> 
 
    <fx:Declarations> 
        <!-- Declare and define parameters for the NumberFormatter.--> 
        <mx:NumberFormatter id="PrepForDisplay" 
            precision="0" 
            rounding="up" 
            decimalSeparatorTo="." 
            thousandsSeparatorTo="," 
            useThousandsSeparator="true" 
            useNegativeSign="true"/> 
    </fx:Declarations> 
 
    <!-- Trigger the formatter while populating a string with data.--> 
    <s:TextInput text="{PrepForDisplay.format(bigNumber)}"/>  
</s:Application>

Invalid value

Invalid format

The PhoneFormatter class lets you format a phone number by adjusting the format of the area code and the subscriber code. You can also adjust the country code and configuration for international formats. The value passed into the PhoneFormatter.format() method must be a Number object or a String object with only digits.

The PhoneFormatter formatString property accepts a formatted string as a definition of the format pattern. The following table shows common options for formatString values. The format() method for the PhoneFormatter accepts a sequence of numbers. The numbers correspond to the number of placeholder (#) symbols in the formatString value. The number of placeholder symbols in the formatString property and the number of digits in the format() method value must match.

###-####

(###) ### ####

###-###-####

#(###) ### ####

#-###-###-####

+###-###-###-####

In the preceding table, dashes (-) are used as separator elements where applicable. You can substitute period (.) characters or blank spaces for the dashes. You can change the default allowable character set as needed by using the validPatternChars property. You can change the default character that represents a numeric placeholder by using the numberSymbol property (for example, to change from # to $).

<?xml version="1.0"?> 
<!-- formatters\MainPhoneFormatter.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx"> 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
 
    <fx:Script> 
        <![CDATA[ 
            // Define variable to hold the phone number.        
            [Bindable] 
            private var newNumber:Number = 1234567; 
        ]]> 
    </fx:Script> 
 
    <fx:Declarations> 
        <!-- Declare a PhoneFormatter and define formatting parameters.--> 
        <mx:PhoneFormatter id="PhoneDisplay" 
            areaCode="415" 
            formatString="###-####"/> 
    </fx:Declarations> 
 
    <!-- Trigger the formatter while populating a string with data--> 
    <s:TextInput id="myTI" 
        initialize="myTI.text=PhoneDisplay.format(newNumber);"/> 
</s:Application>

Invalid value

Invalid format

The ZipCodeFormatter class lets you format five-digit or nine-digit United States ZIP codes and six-character Canadian postal codes. The ZipCodeFormatter class's formatString property accepts a formatted string as a definition of the format pattern. The formatString property is optional. If it is omitted, the default value of ##### is used.

The number of digits in the value to be formatted and the value of the formatString property must be five or nine for United States ZIP codes, and six for Canadian postal codes.

The following table shows common formatString values, input values, and output values:

#####

#####-####

### ###

For United States ZIP codes, if a nine-digit format is requested and a five-digit value is supplied, ‑0000 is appended to the value to make it compliant with the nine-digit format. Inversely, if a nine-digit value is supplied for a five-digit format, the number is truncated to five digits.

For Canadian postal codes, only a six-digit value is allowed for either the formatString or the input value.

<?xml version="1.0"?> 
<!-- formatters\MainZipFormatter.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx"> 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
 
    <fx:Script> 
        <![CDATA[ 
            // Define variable to hold the ZIP code.        
            [Bindable] 
            private var storedZipCode:Number=123456789; 
        ]]> 
    </fx:Script> 
 
    <fx:Declarations> 
        <!-- Declare a ZipCodeFormatter and define parameters.--> 
        <mx:ZipCodeFormatter id="ZipCodeDisplay" 
            formatString="#####-####"/> 
    </fx:Declarations> 
 
    <!-- Trigger the formatter while populating a string with data.--> 
    <s:TextInput text="{ZipCodeDisplay.format(storedZipCode)}"/> 
</s:Application>

Invalid value

Invalid format