Using formatters

Formatters in Adobe® Flex® are components that you use to format data into strings. Formatters perform a one-way conversion of raw data to a formatted string. You typically trigger a formatter just before displaying data in a text field. Flex includes standard formatters that let you format currency, dates, numbers, phone numbers, and ZIP codes.

Spark and MX formatters

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, Adobe recommends that you use the Spark formatters in your application:

Spark formatter

MX formatter

Description

CurrencyFormatter

CurrencyFormatter

Format a currency value.

DataTimeFormatter

DateTimeFormatter

Format a date and time value.

NumberFormatter

NumberFormatter

Format a numeric value.

 

PhoneFormatter

Format a phone number.

 

SwitchSymbolFormatter

Format a String by replacing placeholder characters in one String with numbers from a second String.

 

ZipCodeFormatter

Format a U.S. or Canadian postal code.

Formatter example

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>

The executing SWF file for the previous example is shown below:

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.

You can call the format() method from anywhere in your application, typically in response to an event. The following example declares a Spark DateTimeFormatter. The DateTimeFormatter uses the default locale-specific format for the input String. The application then writes a formatted date to the text property of a TextInput control in response to the click event of a Button control:
<?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>

The executing SWF file for the previous example is shown below: