This example defines a simple formatter class that converts any String to all uppercase or all lowercase letters depending on the value passed to the formatString property. By default, the formatter converts a String to all uppercase.

package myFormatters 
{ 
    // formatters/myFormatter/SimpleFormatter.as 
    import mx.formatters.Formatter 
    import mx.formatters.SwitchSymbolFormatter 
 
    public class SimpleFormatter extends Formatter 
    { 
        // Declare the variable to hold the pattern string. 
        public var myFormatString:String = "upper"; 
 
        // Constructor 
        public function SimpleFormatter() { 
            // Call base class constructor. 
            super(); 
        } 
 
        // Override format(). 
        override public function format(value:Object):String { 
            // 1. Validate value - must be a nonzero length string. 
            if( value.length == 0) 
                {   error="0 Length String"; 
                    return "" 
                } 
 
            // 2. If the value is valid, format the string. 
            switch (myFormatString) { 
                case "upper" : 
                    var upperString:String = value.toUpperCase(); 
                    return upperString; 
                    break; 
                case "lower" : 
                    var lowerString:String = value.toLowerCase(); 
                    return lowerString; 
                    break; 
                default :   
                    error="Invalid Format String"; 
                    return "" 
            } 
        } 
    } 
}

You can use this formatter in an application, as the following example shows:

<?xml version="1.0" ?> 
<!-- createcomps_formatters/FormatterSimple.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" 
    xmlns:MyComp="myFormatters.*"> 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
 
    <fx:Declarations> 
        <!-- Declare a formatter and specify formatting properties. --> 
        <MyComp:SimpleFormatter id="upperFormat" myFormatString="upper" /> 
    </fx:Declarations> 
 
    <!-- Trigger the formatter while populating a string with data. --> 
    <mx:TextInput id="myTI" /> 
    
    <mx:TextArea text="Your uppercase string is {upperFormat.format(myTI.text)}" /> 
</s:Application>

The namespace declaration in the <s:Application> tag specifies to use the MyComp prefix when referencing the formatter, and the location of the formatter's ActionScript file. That file is in the myFormatters subdirectory of the application, or in the default classpath of the application. For more information on deploying your formatters, see Component compilation.

For all formatter classes, except for the SwitchSymbolFormatter class, when an error occurs, the formatter returns an empty string and writes a string that describes the error condition to the formatter's error property. The error property is inherited from the Formatter superclass.

In your application, you can test for an empty string in the result returned by the formatter. If detected, you can check the error property to determine the cause of the error. For an example that handles a formatter error, see Formatting Data. For more information on the SwitchSymbolFormatter class, see Using the SwitchSymbolFormatter class.

By default, the SwitchSymbolFormatter class uses a number sign (#) as the placeholder character to indicate a number substitution within its format string. However, sometimes you might want to include a number sign in your actual format string. Then, you must use a different symbol to indicate a number substitution slot within the format string. You can select any character for this alternative symbol as long as it doesn't appear in the format string.

For example, to use the ampersand character (&) as the placeholder, you create an instance of the SwitchSymbolFormatter class, as the following example shows:

 var dataFormatter = new SwitchSymbolFormatter("&");

Unlike other formatters, the SwitchSymbolFormatter class does not write its error messages into an error property. Instead, it is your responsibility to test for error conditions and return an error message if appropriate.

The custom formatter component in the following example formats nine-digit Social Security numbers by using the SwitchSymbolFormatter class:

package myFormatters 
{ 
    // formatters/myFormatter/CustomSSFormatter.as 
    import mx.formatters.Formatter 
    import mx.formatters.SwitchSymbolFormatter 
 
    public class CustomSSFormatter extends Formatter 
    { 
        // Declare the variable to hold the pattern string. 
        public var formatString : String = "###-##-####"; 
 
        // Constructor 
        public function CustomSSFormatter() { 
            // Call base class constructor. 
            super(); 
        } 
 
        // Override format(). 
        override public function format( value:Object ):String { 
            // Validate input string value - must be a 9-digit number. 
            // You must explicitly check if the value is a number. 
            // The formatter does not do that for you. 
            if( !value  || value.toString().length != 9) 
                {   error="Invalid String Length"; 
                    return "" 
                } 
 
            // Validate format string. 
            // It must contain 9 number placeholders. 
            var numCharCnt:int = 0; 
            for( var i:int = 0; i<formatString.length; i++ ) 
                { 
                    if( formatString.charAt(i) == "#" ) 
                    {   numCharCnt++; 
                    } 
                } 
 
            if( numCharCnt != 9 ) 
            { 
                error="Invalid Format String"; 
                return "" 
            } 
 
            // If the formatString and value are valid, format the number. 
            var dataFormatter:SwitchSymbolFormatter = 
                new SwitchSymbolFormatter(); 
            return dataFormatter.formatValue( formatString, value ); 
        } 
    } 
}

The following example uses this custom formatter in an application:

<?xml version="1.0" encoding="UTF-8"?> 
<!-- createcomps_formatters/FormatterSS.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" 
    xmlns:MyComp="myFormatters.*"> 
    <fx:Declarations> 
        <!-- Declare a formatter and specify formatting properties. --> 
        <MyComp:CustomSSFormatter id="SSFormat" 
            formatString="SS: #-#-#-#-#-#-#-#-#"/> 
    </fx:Declarations> 
 
    <!-- Trigger the formatter while populating a string with data. --> 
    <mx:TextInput text="Your SS number is {SSFormat.format('123456789')}"/> 
</s:Application>