Google Git
Sign in
apache / flex-site / HEAD / . / content / doc / flex / using / flx_formatters_fm.html
blob: d3d75690ba3d3888653333511e69575e0ced96bd [file] [log] [blame]
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html lang="en-us" xml:lang="en-us">
<head>
<meta name="DC.Type" content="topic"/>
<meta name="DC.Title" content="Formatting Data"/>
<meta name="DC.Format" content="XHTML"/>
<meta name="DC.Identifier" content="WS2db454920e96a9e51e63e3d11c0bf69084-7fef_verapache"/>
<title>Formatting Data</title>
</head>
<body id="WS2db454920e96a9e51e63e3d11c0bf69084-7fef_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7fef_verapache"><!-- --></a>
<div>
<p>Data formatters
are user-configurable objects that format raw data into a customized
string. You often use formatters with data binding to create a meaningful
display of the raw data bound to a component. This can save you time
by automating data formatting tasks and by letting you easily change
the formatting of fields within your applications.</p>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf648c2-7fff_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf648c2-7fff_verapache"><!-- --></a>
<h2 class="topictitle2">Using formatters</h2>
<div>
<p>Formatters in 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.</p>
</div>
<div class="nested2" id="WS8b1c39bd7e9fc3641aa8e82012c98cce36f-8000_verapache"><a name="WS8b1c39bd7e9fc3641aa8e82012c98cce36f-8000_verapache"><!-- --></a>
<h3 class="topictitle3">Spark and MX formatters</h3>
<div>
<p>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.</p>
<p>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.</p>
<p>The following table lists the Spark and MX formatting classes.
When possible, it's best that you use the Spark formatters in your
application: </p>
<div class="p">
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d218317e77">
<p>Spark formatter</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d218317e83">
<p>MX formatter</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d218317e89">
<p>Description</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e77 ">
<p>CurrencyFormatter</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e83 ">
<p>CurrencyFormatter</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e89 ">
<p>Format a currency value.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e77 ">
<p>DataTimeFormatter</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e83 ">
<p>DateTimeFormatter</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e89 ">
<p>Format a date and time value.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e77 ">
<p>NumberFormatter</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e83 ">
<p>NumberFormatter</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e89 ">
<p>Format a numeric value.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e77 ">
<p/>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e83 ">
<p>PhoneFormatter</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e89 ">
<p>Format a phone number.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e77 ">
<p/>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e83 ">
<p>SwitchSymbolFormatter</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e89 ">
<p>Format a String by replacing placeholder
characters in one String with numbers from a second String. </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e77 ">
<p/>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e83 ">
<p>ZipCodeFormatter</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e89 ">
<p>Format a U.S. or Canadian postal code. </p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
<div class="nested2" id="WS8b1c39bd7e9fc3641aa8e82012c98cce36f-7fff_verapache"><a name="WS8b1c39bd7e9fc3641aa8e82012c98cce36f-7fff_verapache"><!-- --></a>
<h3 class="topictitle3">Formatter example</h3>
<div>
<p>The following steps describe the general process for using
a formatter:</p>
<ol>
<li>
<p>Declare a formatter in an <samp class="codeph">&lt;fx:Declarations&gt;</samp> tag
in your MXML code, specifying the appropriate formatting properties.
You define formatters in an <samp class="codeph">&lt;fx:Declarations&gt;</samp> tag
because they are not visual components. </p>
<p>You can also create
formatters in ActionScript for use in an application.</p>
</li>
<li>
<p>Call the formatter's <samp class="codeph">format()</samp> method, and
specify the value to be formatted as a parameter to the <samp class="codeph">format()</samp> method.
The <samp class="codeph">format()</samp> method returns a String containing
the formatted value.</p>
</li>
</ol>
<p>The following example formats a phone number that a user inputs
in an application by using the TextInput control: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- formatters\Formatter2TextFields.mxml --&gt;
&lt;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"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Declarations&gt;
&lt;!-- Declare a PhoneFormatter and define formatting parameters.--&gt;
&lt;mx:PhoneFormatter id="phoneDisplay"
areaCode="415"
formatString="###-####" /&gt;
&lt;/fx:Declarations&gt;
&lt;!-- Declare the input control.--&gt;
&lt;s:Label text="Enter 7 digit phone number (########):"/&gt;
&lt;s:TextInput id="myTI"/&gt;
&lt;!-- Declare the control to display the formatted data.--&gt;
&lt;s:TextArea text="{phoneDisplay.format(myTI.text)}"/&gt;
&lt;/s:Application&gt;</pre>
<p>In this example, you use the MX <a href="https://flex.apache.org/asdoc/mx/formatters/PhoneFormatter.html" target="_blank">PhoneFormatter</a> class
to display the formatted phone number in a TextArea control. The <samp class="codeph">format()</samp> method
is called as part of a data binding expression when the <samp class="codeph">text</samp> property
of the TextInput control changes.</p>
<div class="p">You can call the <samp class="codeph">format()</samp> method from anywhere
in your application, typically in response to an event. The following
example declares a Spark <a href="https://flex.apache.org/asdoc/spark/formatters/DateTimeFormatter.html" target="_blank">DateTimeFormatter</a>.
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 <samp class="codeph">click</samp> event
of a Button control: <pre class="codeblock">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- formatters\sparkformatters\SparkFormatterDateField.mxml --&gt;
&lt;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"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout paddingTop="10" paddingLeft="5"/&gt;
&lt;/s:layout&gt;
&lt;fx:Declarations&gt;
&lt;!-- Declare a Spark DateTimeFormatter and
define formatting parameters.--&gt;
&lt;s:DateTimeFormatter id="dateTimeFormatter"/&gt;
&lt;/fx:Declarations&gt;
&lt;s:Label text="Enter date (mm/dd/yyyy):"/&gt;
&lt;s:TextInput id="dob" text=""/&gt;
&lt;s:Label text="Formatted date: "/&gt;
&lt;s:TextInput id="formattedDate"
text="" width="300"
editable="false"/&gt;
&lt;!-- Format and update the date.--&gt;
&lt;s:Button label="Format Input"
click="formattedDate.text=dateTimeFormatter.format(dob.text);"/&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
</div>
<div class="nested1" id="WS8b1c39bd7e9fc364-70b5c6d212c98ca85e2-8000_verapache"><a name="WS8b1c39bd7e9fc364-70b5c6d212c98ca85e2-8000_verapache"><!-- --></a>
<h2 class="topictitle2">Spark formatters</h2>
<div>
<div class="p">Flex includes the following Spark classes for formatting
dates, numbers and currencies:<ul>
<li>
<p>
<a href="https://flex.apache.org/asdoc/spark/formatters/CurrencyFormatter.html" target="_blank">spark.formatters.CurrencyFormatter</a>
</p>
</li>
<li>
<p>
<a href="https://flex.apache.org/asdoc/spark/formatters/NumberFormatter.html" target="_blank">spark.formatters.NumberFormatter</a>
</p>
</li>
<li>
<p>
<a href="https://flex.apache.org/asdoc/spark/formatters/DateTimeFormatter.html" target="_blank">spark.formatters.DateTimeFormatter</a>
</p>
</li>
</ul>
</div>
<p>The Spark formatters provide the following functionality:</p>
<div class="p">
<ul>
<li>
<p>Locale-specific formatting of dates, times, number,
and currency amounts.</p>
</li>
<li>
<p>Locale-specific parsing of numbers and currency amounts.</p>
</li>
<li>
<p>Locale-specific string comparison. For more information,
see <a href="flx_l10n_ln.html#WS19f279b149e7481c-2b2dfa9012bd01637f0-8000_verapache">Sorting
and matching</a>.</p>
</li>
<li>
<p>Locale-specific uppercase and lowercase string conversion.</p>
</li>
</ul>
</div>
<p>The Spark formatters use the <samp class="codeph">locale</samp> style property
to determine how to format data based on the locale. The <samp class="codeph">locale</samp> style
is an inheritable style that you can set for the entire application
or specifically for a particular formatter. </p>
<p>If a Spark formatter does not explicitly set the <samp class="codeph">locale</samp> style,
then it uses the value specified by the <samp class="codeph">locale</samp> style
of the application container. If you do not set the <samp class="codeph">locale</samp> style
property, the application uses the global default from the defaults.css
style sheet, which defaults to <samp class="codeph">en</samp>. For more information,
see <a href="flx_l10n_ln.html#WS19f279b149e7481c-99797f112bd080033f-8000_verapache">Setting the
locale</a>. </p>
<p>You can explicitly configure the formatter to use the default
locale by setting the <samp class="codeph">locale</samp> style to the constant
value <samp class="codeph">flash.globalization.LocaleID.DEFAULT</samp>. </p>
</div>
<div><div class="relinfo"><strong>Related information</strong><br/>
<div><a href="flx_l10n_ln.html#WS19f279b149e7481c-99797f112bd080033f-8000_verapache">Setting the locale</a></div>
<div><a href="flx_l10n_ln.html#WS19f279b149e7481c7370eb2d12bd013e888-7fff_verapache">Formatting dates, numbers, and currencies</a></div>
</div>
</div>
<div class="nested2" id="WS8b1c39bd7e9fc3647b214f0812c99234718-8000_verapache"><a name="WS8b1c39bd7e9fc3647b214f0812c99234718-8000_verapache"><!-- --></a>
<h3 class="topictitle3">Error handling in a Spark formatter</h3>
<div>
<p>You call the <samp class="codeph">format()</samp> method to format
a value. By default, if the <samp class="codeph">format()</samp> method fails,
it returns null. However, you can use the <samp class="codeph">errorText</samp> property
of the formatter to define a String to return, as the following
example shows:</p>
<div class="p">
<pre class="codeblock">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- formatters\sparkformatters\SparkFormatterError.mxml --&gt;
&lt;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"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout paddingTop="10" paddingLeft="5"/&gt;
&lt;/s:layout&gt;
&lt;fx:Declarations&gt;
&lt;!-- Declare a Spark DateTimeFormatter and
define formatting parameters.--&gt;
&lt;s:DateTimeFormatter id="dateTimeFormatter"
dateTimePattern="month: MM, day: DD, year: YYYY"
errorText="Invalid input value"/&gt;
&lt;/fx:Declarations&gt;
&lt;s:Label text="Enter date (mm/dd/yyyy):"/&gt;
&lt;s:TextInput id="dob" text=""/&gt;
&lt;s:Label text="Formatted date: "/&gt;
&lt;s:TextInput id="formattedDate"
text="" width="300"
editable="false"/&gt;
&lt;!-- Format and update the date.--&gt;
&lt;s:Button label="Format Input"
click="formattedDate.text=dateTimeFormatter.format(dob.text);"/&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
<div class="nested2" id="WS8b1c39bd7e9fc364-6f7c3c1312c990bc783-7ffe_verapache"><a name="WS8b1c39bd7e9fc364-6f7c3c1312c990bc783-7ffe_verapache"><!-- --></a>
<h3 class="topictitle3">Formatting numbers with a Spark
formatter</h3>
<div>
<p>The Spark <a href="https://flex.apache.org/asdoc/spark/formatters/NumberFormatter.html" target="_blank">NumberFormatter</a> class
provides basic formatting options for numeric data, including decimal
formatting, thousands separator formatting, and negative sign formatting. </p>
<p>The <samp class="codeph">format()</samp> 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 <samp class="codeph">format()</samp> method,
the function first uses the <samp class="codeph">Number()</samp> function to
convert the String to a Number object. </p>
<div class="p">The following example uses the NumberFormatter class in an MXML
file: <pre class="codeblock">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;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"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout paddingTop="10" paddingLeft="5"/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
protected function button2_clickHandler(event:MouseEvent):void {
displayVal.text = PrepForDisplay.format(bigNumber.text);
}
]]&gt;
&lt;/fx:Script&gt;
&lt;fx:Declarations&gt;
&lt;!-- Declare and define parameters for the NumberFormatter.--&gt;
&lt;s:NumberFormatter id="PrepForDisplay"
fractionalDigits="3"
decimalSeparator="."
groupingSeparator=","
useGrouping="true"
negativeNumberFormat="0"
errorText="'{bigNumber.text}' is an invalid input value"/&gt;
&lt;/fx:Declarations&gt;
&lt;!-- String to format.--&gt;
&lt;s:TextInput id="bigNumber" text="Enter number"/&gt;
&lt;s:Button label="Format Value"
click="button2_clickHandler(event);"/&gt;
&lt;!-- Display formatted value.--&gt;
&lt;s:Label id="displayVal"/&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
<div class="nested2" id="WS8b1c39bd7e9fc364-6f7c3c1312c990bc783-8000_verapache"><a name="WS8b1c39bd7e9fc364-6f7c3c1312c990bc783-8000_verapache"><!-- --></a>
<h3 class="topictitle3">Formatting currency with a Spark
formatter</h3>
<div>
<p>The
Spark <a href="https://flex.apache.org/asdoc/spark/formatters/CurrencyFormatter.html" target="_blank">CurrencyFormatter</a> class
provides the same features as the NumberFormatter class, plus a
currency symbol. It also has additional properties to control the
formatted result: <samp class="codeph">currencySymbol</samp>, <samp class="codeph">negativeCurrencyFormat</samp>,
and <samp class="codeph">positiveCurrencyFormat</samp>. </p>
<p>The <samp class="codeph">format()</samp> 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 <samp class="codeph">format()</samp> method,
the function first uses the <samp class="codeph">Number()</samp> function to
convert the String to a Number object. </p>
<p>The <samp class="codeph">useCurrencySymbol</samp> property determines the
currency symbol returned in the formatted String based on the <samp class="codeph">locale</samp> style
property. When the <samp class="codeph">useCurrencySymbol</samp> property is
set to <samp class="codeph">true</samp>, the formatter returns the value of
the <samp class="codeph">currencySymbol</samp> property in the formatted String.
When the <samp class="codeph">useCurrencySymbol</samp> property is set to <samp class="codeph">false</samp>,
the formatter returns the value of the <samp class="codeph">currencyISOCode</samp> property
in the formatted String.</p>
<div class="p">The following example uses the CurrencyFormatter class in an
MXML file: <pre class="codeblock">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- formatters\sparkformatters\SparkCurrencyFormatter.mxml --&gt;
&lt;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"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout paddingTop="10" paddingLeft="5"/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
protected function button1_clickHandler(event:MouseEvent):void {
displayVal.text = Price.format(currVal.text);
}
]]&gt;
&lt;/fx:Script&gt;
&lt;fx:Declarations&gt;
&lt;!-- Declare a CurrencyFormatter and define parameters.--&gt;
&lt;s:CurrencyFormatter id="Price"
currencySymbol="$"
useCurrencySymbol="true"
negativeCurrencyFormat="0"
positiveCurrencyFormat="0"
errorText="'{currVal.text}' is an invalid input value"/&gt;
&lt;/fx:Declarations&gt;
&lt;!-- Enter currency value, then click the Button to format. --&gt;
&lt;s:TextInput id="currVal" text="Enter value"/&gt;
&lt;s:Button label="Format Value"
click="button1_clickHandler(event);"/&gt;
&lt;!-- Display formatted value.--&gt;
&lt;s:Label id="displayVal"/&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
<div class="nested2" id="WS8b1c39bd7e9fc364-6f7c3c1312c990bc783-7fff_verapache"><a name="WS8b1c39bd7e9fc364-6f7c3c1312c990bc783-7fff_verapache"><!-- --></a>
<h3 class="topictitle3">Formatting dates with a Spark formatter</h3>
<div>
<p>The Spark <a href="https://flex.apache.org/asdoc/mx/formatters/DateFormatter.html" target="_blank">DateTimeFormatter</a> class
gives you a wide range of combinations for displaying date and time
information. The <samp class="codeph">format()</samp> method accepts a Date object,
which it converts to a String based on a user-defined pattern. </p>
<p>The <samp class="codeph">format()</samp> 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 <samp class="codeph">format()</samp> method
is unable to parse the String into a Date object, it returns <samp class="codeph">null</samp>. </p>
<p>The following examples show possible input strings to the <samp class="codeph">format()</samp> method:</p>
<pre class="codeblock"> "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"</pre>
<div class="section"><h4 class="sectiontitle">Using pattern strings</h4>
<p>Use the <samp class="codeph">dateTimePattern</samp> property
of the <a href="https://flex.apache.org/asdoc/spark/formatters/DateTimeFormatter.html" target="_blank">DateTimeFormatter</a> class
to specify the string of pattern letters that determine the appropriate
formatting. You compose a pattern string by using specific letter
sequences. For example, "yyyy/MM". </p>
<div class="p">
<div class="note"><span class="notetitle">Note:</span> By omitting a pattern
string, the date is formatted using the default for the current
locale. By specifying a pattern string, you override the default
formatting. Information, such as month and day names, are still
displayed correctly for the locale, but the order of elements in
the formatted string is fixed by the specified pattern string.</div>
</div>
<p>You
can include text and punctuation in the pattern string. However
the characters from "a" to "z" and from "A" to "Z" are reserved
as syntax characters. Enclose these characters in single quotes
to include them in the formatted output string. To include a single
quote, use two single quotes. The two single quotes may appear inside
or outside a quoted portion of the pattern string. </p>
<p>When you
create a pattern string, you usually repeat pattern letters. The
number of repeated letters determines the presentation. For numeric
values, the number of pattern letters is the minimum number of digits;
shorter numbers are zero-padded to this amount. For example, the
four-letter pattern string "yyyy" corresponds to a four-digit year
value. </p>
<p>In cases where there is a corresponding mapping of
a text description—for example, the name of a month—the full form
is used if the number of pattern letters is four or more; otherwise,
a short or abbreviated form is used, if available. For example,
if you specify the pattern string "MMMM" for month, the formatter requires
the full month name, such as "December", instead of the abbreviated month
name, such as "Dec". </p>
<p>For time values, a single pattern letter
is interpreted as one or two digits. Two pattern letters are interpreted
as two digits. </p>
<p>The complete list of options to the pattern
string is defined by the <a href="https://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/globalization/DateTimeFormatter.html#setDateTimePattern()" target="_blank">setDateTimePattern()</a> method
of the <a href="https://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/globalization/DateTimeFormatter.html" target="_blank">flash.globalization.DateTimeFormatter</a> class. </p>
<p>The
following table shows sample pattern strings and the resulting presentation:</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d218317e726">
<p>Pattern</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d218317e732">
<p>Result</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e726 ">
<p>
<samp class="codeph">EEEE, MMMM dd, yyyy h:mm:ss a</samp> (default) </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e732 ">
<p>Wednesday, December 01, 2010 3:06:43 PM</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e726 ">
<div class="p">
<pre class="codeblock">yyyy.MM.dd 'at' h:mm:ss</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e732 ">
<p>2010.12.01 at 3:19:44</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e726 ">
<div class="p">
<pre class="codeblock">EEE, MMM d, yy</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e732 ">
<p>Wed, Dec 1, 10</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e726 ">
<p>
<samp class="codeph">kk 'o''clock' a</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e732 ">
<p>15 o'clock PM</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e726 ">
<div class="p">
<pre class="codeblock">k:mm a</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e732 ">
<p>12:08 PM</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e726 ">
<div class="p">
<pre class="codeblock">K:mm a</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e732 ">
<p>0:08 PM</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e726 ">
<div class="p">
<pre class="codeblock">yyyy.MMMM.dd HH:mm:ss</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e732 ">
<p>2005.July.04 12:08:34</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section"><h4 class="sectiontitle">Example: Using the Spark DateFormatter class</h4>
<div class="p">The
following example uses the <a href="https://flex.apache.org/asdoc/mx/formatters/DateFormatter.html" target="_blank">DateTimeFormatter</a> class
in an MXML file for formatting a Date object as a String: <pre class="codeblock">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- formatters\spark\SparkDateFormatter.mxml --&gt;
&lt;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"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout paddingTop="10" paddingLeft="5"/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
// Define variable to hold the date.
[Bindable]
private var today:Date = new Date();
]]&gt;
&lt;/fx:Script&gt;
&lt;fx:Declarations&gt;
&lt;!-- Declare a DateFormatter and define parameters.--&gt;
&lt;s:DateTimeFormatter id="DateDisplay1"
dateTimePattern="MMMM d, yyyy"/&gt;
&lt;s:DateTimeFormatter id="DateDisplay2"
dateTimePattern="hh:mm a"/&gt;
&lt;s:DateTimeFormatter id="DateDisplay3"
dateTimePattern="hh:mm a, MMMM d, yyyy"/&gt;
&lt;s:DateTimeFormatter id="DateDisplay4"
dateTimePattern="yyyy.MMMM.dd HH:mm:ss"/&gt;
&lt;/fx:Declarations&gt;
&lt;!-- Display the date in a Label control.--&gt;
&lt;s:Label id="myTA1" text="{DateDisplay1.format(today)}"/&gt;
&lt;!-- Display the date in a Label control.--&gt;
&lt;s:Label id="myTA2" text="{DateDisplay2.format(today)}"/&gt;
&lt;!-- Display the date in a Label control.--&gt;
&lt;s:Label id="myTA3" text="{DateDisplay3.format(today)}"/&gt;
&lt;!-- Display the date in a Label control.--&gt;
&lt;s:Label id="myTA4" text="{DateDisplay4.format(today)}"/&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
</div>
</div>
<div class="nested1" id="WS8b1c39bd7e9fc364-70b5c6d212c98ca85e2-7fff_verapache"><a name="WS8b1c39bd7e9fc364-70b5c6d212c98ca85e2-7fff_verapache"><!-- --></a>
<h2 class="topictitle2">MX formatters</h2>
<div>
<p>All formatters are subclasses of the <a href="https://flex.apache.org/asdoc/mx/formatters/Formatter.html" target="_blank">mx.formatters.Formatter</a> class.
The Formatter class declares a <a href="https://flex.apache.org/asdoc/mx/formatters/Formatter.html#format()" target="_blank">format()</a> method
that takes a value and returns a String value.</p>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf648c2-7ffe_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf648c2-7ffe_verapache"><!-- --></a>
<h3 class="topictitle3">Writing an error handler function
for an MX formatter</h3>
<div>
<p>For most formatters, when an error occurs, the <samp class="codeph">format()</samp> method
returns an empty string is and a string describing the error is
written to the formatter's <samp class="codeph">error</samp> property. You
can check for an empty string in the return value of the <samp class="codeph">format()</samp> method,
and if found, access the <samp class="codeph">error</samp> property to determine
the cause of the error. </p>
<p>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: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- formatters\FormatterSimpleErrorForDevApps.mxml --&gt;
&lt;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"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;
&lt;![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;
}
]]&gt;
&lt;/fx:Script&gt;
&lt;fx:Declarations&gt;
&lt;!-- Declare a formatter and specify formatting properties.--&gt;
&lt;mx:DateFormatter id="myFormatter"
formatString="MXXXMXMXMXMXM"/&gt;
&lt;/fx:Declarations&gt;
&lt;!-- Trigger the formatter while populating a string with data.--&gt;
&lt;s:TextInput id="myTI"
width="75%"
text="Your order shipped on {formatWithError('May 23, 2005')}"/&gt;
&lt;/s:Application&gt;</pre>
<p>In this example, you define a <a href="https://flex.apache.org/asdoc/mx/formatters/DateFormatter.html" target="_blank">DateFormatter</a> with
an invalid format string. You then use the <samp class="codeph">formatWithError()</samp> method
to invoke the formatter in the TextInput control, rather than calling
the Date formatter's <samp class="codeph">format()</samp> method directly.
In this example, if either the input string or the format string
is invalid, the <samp class="codeph">formatWithError()</samp> method returns
an error message instead of a formatted String value.</p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf648c2-7ffc_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf648c2-7ffc_verapache"><!-- --></a>
<h3 class="topictitle3">Formatting currency with an MX
formatter</h3>
<div>
<p>The
MX <a href="https://flex.apache.org/asdoc/mx/formatters/CurrencyFormatter.html" target="_blank">CurrencyFormatter</a> class
provides the same features as the NumberFormatter class, plus a
currency symbol. It has two additional properties: <samp class="codeph">currencySymbol</samp> and <samp class="codeph">alignSymbol</samp>.
(For more information about the NumberFormatter class, see <a href="flx_formatters_fm.html#WS2db454920e96a9e51e63e3d11c0bf69084-7ce2_verapache">Formatting
numbers with an MX formatter</a>.)</p>
<p>The CurrencyFormatter class provides basic formatting options
for numeric data, including decimal formatting, thousands separator
formatting, and negative sign formatting. The <samp class="codeph">format()</samp> method
accepts a Number value or a number formatted as a String value and
formats the resulting string.</p>
<p>When a number formatted as a String is passed to the <samp class="codeph">format()</samp> 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 <samp class="codeph">thousandsSeparatorFrom</samp> property. The parser
searches for a period (.) for the decimal separator unless you define
a different character in the <samp class="codeph">decimalSeparator</samp> property.</p>
<div class="note"><span class="notetitle">Note:</span> When a number is provided to the <samp class="codeph">format()</samp> method
as a String value, a negative sign is recognized if it is a dash
(-) immediately preceding the first number in the sequence. A dash,
space, and then a first number are not interpreted as a negative sign. </div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf648c2-7ffc_verapache__WS2db454920e96a9e51e63e3d11c0bf648c2-7ffb_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf648c2-7ffc_verapache__WS2db454920e96a9e51e63e3d11c0bf648c2-7ffb_verapache"><!-- --></a><h4 class="sectiontitle">Example:
Using the MX CurrencyFormatter class</h4>
<p>The following example
uses the CurrencyFormatter class in an MXML file:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- formatters\MainCurrencyFormatter.mxml --&gt;
&lt;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"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
// Define variable to hold the price.
[Bindable]
private var todaysPrice:Number=4025;
]]&gt;
&lt;/fx:Script&gt;
&lt;fx:Declarations&gt;
&lt;!-- Declare a CurrencyFormatter and define parameters.--&gt;
&lt;mx:CurrencyFormatter id="Price" precision="2"
rounding="none"
decimalSeparatorTo="."
thousandsSeparatorTo=","
useThousandsSeparator="true"
useNegativeSign="true"
currencySymbol="$"
alignSymbol="left"/&gt;
&lt;/fx:Declarations&gt;
&lt;!-- Trigger the formatter while populating a string with data.--&gt;
&lt;s:TextInput text="Today's price is {Price.format(todaysPrice)}."
width="200"/&gt;
&lt;/s:Application&gt;</pre>
<p>At run time, the following
text is displayed:</p>
<p>Today's price is $4,025.00.</p>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf648c2-7ffc_verapache__WS2db454920e96a9e51e63e3d11c0bf648c2-7ffa_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf648c2-7ffc_verapache__WS2db454920e96a9e51e63e3d11c0bf648c2-7ffa_verapache"><!-- --></a><h4 class="sectiontitle">Error
handling: MX CurrencyFormatter class</h4>
<p>If an error occurs,
Flex returns an empty string and saves a description of the error in
the <a href="https://flex.apache.org/asdoc/mx/formatters/Formatter.html#error" target="_blank">error</a> property.
An error points to a problem with the value being submitted or the
format string containing the user settings, as described in the following
table: </p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d218317e1075">
<p>Value of error property</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d218317e1081">
<p>When error occurs</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1075 ">
<div class="p">
<pre class="codeblock">Invalid value</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1081 ">
<p>An invalid numeric value is passed to the <samp class="codeph">format()</samp> method.
The value should be a valid number in the form of a Number or a
String.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1075 ">
<div class="p">
<pre class="codeblock">Invalid format</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1081 ">
<p>One or more of the parameters contain an
unusable setting.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf648c2-7ff9_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf648c2-7ff9_verapache"><!-- --></a>
<h3 class="topictitle3">Formatting dates with an MX formatter</h3>
<div>
<p>The MX <a href="https://flex.apache.org/asdoc/mx/formatters/DateFormatter.html" target="_blank">DateFormatter</a> class
gives you a wide range of combinations for displaying date and time
information. The <samp class="codeph">format()</samp> method accepts a Date object,
which it converts to a String based on a user-defined pattern. The <samp class="codeph">format()</samp> method
can also accept a String-formatted date, which it attempts to parse
into a valid Date object prior to formatting.</p>
<p>The DateFormatter class has a <samp class="codeph">parseDateString()</samp> method
that accepts a date formatted as a String. The <samp class="codeph">parseDateString()</samp> 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. </p>
<p>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 <samp class="codeph">parseDateString()</samp> method is unable to parse
the String into a Date object, it returns <samp class="codeph">null</samp>. </p>
<p>The following examples show some of the ways strings can be parsed:</p>
<pre class="codeblock"> "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"</pre>
<p>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. </p>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf648c2-7ff9_verapache__WS2db454920e96a9e51e63e3d11c0bf648c2-7ff8_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf648c2-7ff9_verapache__WS2db454920e96a9e51e63e3d11c0bf648c2-7ff8_verapache"><!-- --></a><h4 class="sectiontitle">Using
Pattern strings</h4>
<p>You provide the <a href="https://flex.apache.org/asdoc/mx/formatters/DateFormatter.html" target="_blank">DateFormatter</a> class
with a string of pattern letters, which it parses to determine the
appropriate formatting. You must understand how to compose the string
of pattern letters to control the formatting options and the format
of the string that is returned.</p>
<p>You compose a pattern string
by using specific uppercase letters: for example, YYYY/MM. The DateFormatter
pattern string can contain other text in addition to pattern letters.
To form a valid pattern string, you need only one pattern letter.</p>
<p>When
you create a pattern string, you usually repeat pattern letters.
The number of repeated letters determines the presentation. For
numeric values, the number of pattern letters is the minimum number
of digits; shorter numbers are zero-padded to this amount. For example,
the four-letter pattern string "YYYY" corresponds to a four-digit
year value.</p>
<p>In cases where there is a corresponding mapping
of a text description—for instance, the name of a month—the full
form is used if the number of pattern letters is four or more; otherwise,
a short or abbreviated form is used, if available. For example,
if you specify the pattern string "MMMM" for month, the formatter requires
the full month name, such as "December", instead of the abbreviated month
name, such as "Dec". </p>
<p>For time values, a single pattern letter
is interpreted as one or two digits. Two pattern letters are interpreted
as two digits.</p>
<p>The following table describes each of the available
pattern letters:</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d218317e1236">
<p>Pattern letter</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d218317e1242">
<p>Description</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1236 ">
<p>Y</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1242 ">
<p>Year. If the number of pattern letters is
two, the year is truncated to two digits; otherwise, it appears
as four digits. The year can be zero-padded, as the third example
shows in the following set of examples: </p>
<p>Examples:</p>
<p>YY
= 05</p>
<p>YYYY = 2005</p>
<p>YYYYY = 02005</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1236 ">
<p>M</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1242 ">
<p>Month in year. The format depends on the
following criteria:</p>
<div class="p">
<ul>
<li>
<p>If the number of pattern letters
is one, the format is interpreted as numeric in one or two digits. </p>
</li>
<li>
<p>If the number of pattern letters is two, the format is interpreted
as numeric in two digits. </p>
</li>
<li>
<p>If the number of pattern letters is three, the format is
interpreted as short text. </p>
</li>
<li>
<p>If the number of pattern letters is four, the format is interpreted
as full text. </p>
</li>
</ul>
</div>
<p>Examples:</p>
<p>M = 7</p>
<p>MM=
07</p>
<p>MMM=Jul</p>
<p>MMMM= July</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1236 ">
<p>D</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1242 ">
<p>Day in month. While a single-letter pattern
string for day is valid, you typically use a two-letter pattern
string.</p>
<p>Examples:</p>
<p>D=4</p>
<p>DD=04</p>
<p>DD=10</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1236 ">
<p>E</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1242 ">
<p>Day in week. The format depends on the following
criteria:</p>
<div class="p">
<ul>
<li>
<p>If the number of pattern letters is one,
the format is interpreted as numeric in one or two digits. </p>
</li>
<li>
<p>If the number of pattern letters is two, the format is interpreted
as numeric in two digits.</p>
</li>
<li>
<p>If the number of pattern letters is three, the format is
interpreted as short text. </p>
</li>
<li>
<p>If the number of pattern letters is four, the format is interpreted
as full text. </p>
</li>
</ul>
</div>
<p>Examples:</p>
<p>E = 1</p>
<p>EE
= 01</p>
<p>EEE = Mon</p>
<p>EEEE = Monday</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1236 ">
<p>A</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1242 ">
<p>am/pm indicator.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1236 ">
<p>J</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1242 ">
<p>Hour in day (0-23).</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1236 ">
<p>H</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1242 ">
<p>Hour in day (1-24).</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1236 ">
<p>K</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1242 ">
<p>Hour in am/pm (0-11).</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1236 ">
<p>L</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1242 ">
<p>Hour in am/pm (1-12).</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1236 ">
<p>N</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1242 ">
<p>Minute in hour. </p>
<p>Examples:</p>
<p>N
= 3</p>
<p>NN = 03</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1236 ">
<p>S</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1242 ">
<p>Second in minute. </p>
<p>Examples:</p>
<p>SS
= 30</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1236 ">
<p>Q</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1242 ">
<p>Millisecond in seconds.Example:s: QQ = 78QQQ
= 078</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1236 ">
<p>Other text</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1242 ">
<p>You can add other text into the pattern
string to further format the string. You can use punctuation, numbers,
and all lowercase letters. You should avoid uppercase letters because
they may be interpreted as pattern letters.</p>
<p>Example:</p>
<p>EEEE,
MMM. D, YYYY at L:NN A = Tuesday, Sept. 8, 2005 at 1:26 PM</p>
</td>
</tr>
</tbody>
</table>
</div>
<p>The following table shows sample pattern
strings and the resulting presentation:</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d218317e1604">
<p>Pattern</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d218317e1610">
<p>Result</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1604 ">
<div class="p">
<pre class="codeblock">YYYY.MM.DD at HH:NN:SS</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1610 ">
<p>2005.07.04 at 12:08:56</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1604 ">
<p>
<samp class="codeph">EEEE, MMM. D, YYYY at L:NN:QQQ A</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1610 ">
<p>Tuesday, Sept. 8, 2005 at 1:26:012 PM</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1604 ">
<div class="p">
<pre class="codeblock">EEE, MMM D, 'YY</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1610 ">
<p>Wed, Jul 4, '05</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1604 ">
<div class="p">
<pre class="codeblock">H:NN A</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1610 ">
<p>12:08 PM</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1604 ">
<div class="p">
<pre class="codeblock">HH o'clock A</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1610 ">
<p>12 o'clock PM</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1604 ">
<div class="p">
<pre class="codeblock">K:NN A</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1610 ">
<p>0:08 PM</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1604 ">
<div class="p">
<pre class="codeblock">YYYYY.MMMM.DD. JJ:NN A</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1610 ">
<p>02005.July.04. 12:08 PM</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1604 ">
<div class="p">
<pre class="codeblock">EEE, D MMM YYYY HH:NN:SS</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1610 ">
<p>Wed, 4 Jul 2005 12:08:56</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf648c2-7ff9_verapache__WS2db454920e96a9e51e63e3d11c0bf648c2-7ff7_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf648c2-7ff9_verapache__WS2db454920e96a9e51e63e3d11c0bf648c2-7ff7_verapache"><!-- --></a><h4 class="sectiontitle">Example:
Using the DateFormatter class</h4>
<p>The following example uses
the <a href="https://flex.apache.org/asdoc/mx/formatters/DateFormatter.html" target="_blank">DateFormatter</a> class
in an MXML file for formatting a Date object as a String:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- formatters\MainDateFormatter.mxml --&gt;
&lt;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"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
// Define variable to hold the date.
[Bindable]
private var today:Date = new Date();
]]&gt;
&lt;/fx:Script&gt;
&lt;fx:Declarations&gt;
&lt;!-- Declare a DateFormatter and define parameters.--&gt;
&lt;mx:DateFormatter id="DateDisplay"
formatString="MMMM D, YYYY"/&gt;
&lt;/fx:Declarations&gt;
&lt;!-- Display the date in a TextArea control.--&gt;
&lt;s:TextInput id="myTA" text="{DateDisplay.format(today)}"/&gt;
&lt;/s:Application&gt;</pre>
<p>At run time, the TextInput
control displays the current date. </p>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf648c2-7ff9_verapache__WS2db454920e96a9e51e63e3d11c0bf648c2-7ff6_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf648c2-7ff9_verapache__WS2db454920e96a9e51e63e3d11c0bf648c2-7ff6_verapache"><!-- --></a><h4 class="sectiontitle">Error
handling: DateFormatter class</h4>
<p>If an error occurs, Flex
returns an empty string and saves a description of the error in
the <a href="https://flex.apache.org/asdoc/mx/formatters/Formatter.html#error" target="_blank">error</a> property.
An error points to a problem with the value being submitted or the
format string containing the user settings, as described in the following
table:</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d218317e1812">
<p>Value of error property</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d218317e1818">
<p>When error occurs</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1812 ">
<div class="p">
<pre class="codeblock">Invalid value</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1818 ">
<p>A value that is not a Date object is passed
to the <samp class="codeph">format()</samp> method. (An empty argument is allowed.) </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1812 ">
<div class="p">
<pre class="codeblock">Invalid format</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e1818 ">
<div class="p">
<ul>
<li>
<p>The <samp class="codeph">formatString</samp> property
is set to empty ("").</p>
</li>
<li>
<p>There is less than one pattern letter in the <samp class="codeph">formatString</samp> property.</p>
</li>
</ul>
</div>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7ce2_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7ce2_verapache"><!-- --></a>
<h3 class="topictitle3">Formatting numbers with an MX formatter</h3>
<div>
<p>The MX <a href="https://flex.apache.org/asdoc/mx/formatters/NumberFormatter.html" target="_blank">NumberFormatter</a> class
provides basic formatting options for numeric data, including decimal
formatting, thousands separator formatting, and negative sign formatting.
The <samp class="codeph">format()</samp> method accepts a number or a number
formatted as a String value, and formats the resulting string.</p>
<p>When a number formatted as a String value is passed to the <samp class="codeph">format()</samp> 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 <samp class="codeph">thousandsSeparatorFrom</samp> property.
The parser searches for a period (.) for the decimal separator unless
you define a different character in the <samp class="codeph">decimalSeparator</samp> property.</p>
<div class="note"><span class="notetitle">Note:</span> The <samp class="codeph">format()</samp> method recognizes
a dash (-) immediately preceding the first number in the sequence
as a negative number. A dash, space, and then number sequence are
not interpreted as a negative number. </div>
<p>The <samp class="codeph">rounding</samp> and <samp class="codeph">precision</samp> properties
of the MX NumberFormatter class affect the formatting of the decimal
in a number. If you use both <samp class="codeph">rounding</samp> and <samp class="codeph">precision</samp> 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.</p>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf69084-7ce2_verapache__WS2db454920e96a9e51e63e3d11c0bf648c2-7ff4_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7ce2_verapache__WS2db454920e96a9e51e63e3d11c0bf648c2-7ff4_verapache"><!-- --></a><h4 class="sectiontitle">Example:
Using the MX NumberFormatter class</h4>
<p>The following example
uses the MX <a href="https://flex.apache.org/asdoc/mx/formatters/NumberFormatter.html" target="_blank">NumberFormatter</a> class
in an MXML file: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- formatters\MainNumberFormatter.mxml --&gt;
&lt;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"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
// Define variable to hold the number.
[Bindable]
private var bigNumber:Number = 6000000000.65;
]]&gt;
&lt;/fx:Script&gt;
&lt;fx:Declarations&gt;
&lt;!-- Declare and define parameters for the NumberFormatter.--&gt;
&lt;mx:NumberFormatter id="PrepForDisplay"
precision="0"
rounding="up"
decimalSeparatorTo="."
thousandsSeparatorTo=","
useThousandsSeparator="true"
useNegativeSign="true"/&gt;
&lt;/fx:Declarations&gt;
&lt;!-- Trigger the formatter while populating a string with data.--&gt;
&lt;s:TextInput text="{PrepForDisplay.format(bigNumber)}"/&gt;
&lt;/s:Application&gt;</pre>
<p>At run time, the following
text appears:</p>
<p>6,000,000,001</p>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf69084-7ce2_verapache__WS2db454920e96a9e51e63e3d11c0bf648c2-7ff3_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7ce2_verapache__WS2db454920e96a9e51e63e3d11c0bf648c2-7ff3_verapache"><!-- --></a><h4 class="sectiontitle">Error
handling: MX NumberFormatter class</h4>
<p>If an error occurs,
Flex returns an empty string and saves a description of the error in
the <a href="https://flex.apache.org/asdoc/mx/formatters/Formatter.html#error" target="_blank">error</a> property.
An error refers to a problem with the value being submitted or the
format string that contains the user settings, as described in the
following table:</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d218317e2002">
<p>Value of error property</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d218317e2008">
<p>When error occurs</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2002 ">
<div class="p">
<pre class="codeblock">Invalid value</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2008 ">
<p>An invalid numeric value is passed to the <samp class="codeph">format()</samp> method.
The value should be a valid number in the form of a Number or a
String.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2002 ">
<div class="p">
<pre class="codeblock">Invalid format</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2008 ">
<p>One or more of the parameters contain an
unusable setting.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf648c2-7ff2_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf648c2-7ff2_verapache"><!-- --></a>
<h3 class="topictitle3">Formatting phone numbers with an
MX formatter</h3>
<div>
<p>The <a href="https://flex.apache.org/asdoc/mx/formatters/PhoneFormatter.html" target="_blank">PhoneFormatter</a> 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 <samp class="codeph">PhoneFormatter.format()</samp> method must be a Number
object or a String object with only digits.</p>
<p>The PhoneFormatter <samp class="codeph">formatString</samp> property accepts
a formatted string as a definition of the format pattern. The following
table shows common options for <samp class="codeph">formatString</samp> values.
The <samp class="codeph">format()</samp> method for the PhoneFormatter accepts
a sequence of numbers. The numbers correspond to the number of placeholder
(#) symbols in the <samp class="codeph">formatString</samp> value. The number
of placeholder symbols in the <samp class="codeph">formatString</samp> property
and the number of digits in the <samp class="codeph">format()</samp> method
value must match. </p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d218317e2127">
<p>formatString value</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d218317e2133">
<p>Input</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d218317e2139">
<p>Output</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2127 ">
<div class="p">
<pre class="codeblock">###-####</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2133 ">
<p>1234567</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2139 ">
<p>(xxx) 456-7890</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2127 ">
<div class="p">
<pre class="codeblock">(###) ### ####</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2133 ">
<p>1234567890</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2139 ">
<p>(123) 456-7890</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2127 ">
<div class="p">
<pre class="codeblock">###-###-####</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2133 ">
<p>11234567890</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2139 ">
<p>123-456-7890</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2127 ">
<div class="p">
<pre class="codeblock">#(###) ### ####</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2133 ">
<p>11234567890</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2139 ">
<p>1(123) 456 7890</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2127 ">
<div class="p">
<pre class="codeblock">#-###-###-####</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2133 ">
<p>11234567890</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2139 ">
<p>1-123-456-7890</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2127 ">
<div class="p">
<pre class="codeblock">+###-###-###-####</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2133 ">
<p>1231234567890</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2139 ">
<p>+123-123-456-7890</p>
</td>
</tr>
</tbody>
</table>
</div>
<p>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 <samp class="codeph">validPatternChars</samp> property.
You can change the default character that represents a numeric placeholder
by using the <samp class="codeph">numberSymbol</samp> property (for example,
to change from # to $).</p>
<div class="note"><span class="notetitle">Note:</span> A shortcut is provided for the United States
seven-digit format. If the <samp class="codeph">areaCode</samp> property contains
a value and you use the seven-digit format string, a seven-digit
format entry automatically adds the area code to the string returned.
The default format for the area code is (<samp class="codeph">###</samp>).
You can change this by using the <samp class="codeph">areaCodeFormat</samp> property.
You can format the area code any way you want as long as it contains
three number placeholders.</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf648c2-7ff2_verapache__WS2db454920e96a9e51e63e3d11c0bf648c2-7ff1_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf648c2-7ff2_verapache__WS2db454920e96a9e51e63e3d11c0bf648c2-7ff1_verapache"><!-- --></a><h4 class="sectiontitle">Example:
Using the PhoneFormatter class</h4>
<p>The following example uses
the <a href="https://flex.apache.org/asdoc/mx/formatters/PhoneFormatter.html" target="_blank">PhoneFormatter</a> class
in an MXML file:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- formatters\MainPhoneFormatter.mxml --&gt;
&lt;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"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
// Define variable to hold the phone number.
[Bindable]
private var newNumber:Number = 1234567;
]]&gt;
&lt;/fx:Script&gt;
&lt;fx:Declarations&gt;
&lt;!-- Declare a PhoneFormatter and define formatting parameters.--&gt;
&lt;mx:PhoneFormatter id="PhoneDisplay"
areaCode="415"
formatString="###-####"/&gt;
&lt;/fx:Declarations&gt;
&lt;!-- Trigger the formatter while populating a string with data--&gt;
&lt;s:TextInput id="myTI"
initialize="myTI.text=PhoneDisplay.format(newNumber);"/&gt;
&lt;/s:Application&gt;</pre>
<p>At run time, the following
text is displayed:</p>
<p>(415) 123-4567</p>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf648c2-7ff2_verapache__WS2db454920e96a9e51e63e3d11c0bf648c2-7ff0_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf648c2-7ff2_verapache__WS2db454920e96a9e51e63e3d11c0bf648c2-7ff0_verapache"><!-- --></a><h4 class="sectiontitle">Error
handling: PhoneFormatter class</h4>
<p>If an error occurs, Flex
returns an empty string and saves a description of the error in
the <a href="https://flex.apache.org/asdoc/mx/formatters/Formatter.html#error" target="_blank">error</a> property.
An error points to a problem with the value being submitted or the
format string containing the user settings, as described in the following
table:</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d218317e2365">
<p>Value of error property</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d218317e2371">
<p>When error occurs</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2365 ">
<div class="p">
<pre class="codeblock">Invalid value</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2371 ">
<div class="p">
<ul>
<li>
<p>An invalid numeric value is passed
to the <samp class="codeph">format()</samp> method. The value should be a valid number
in the form of a Number or a String.</p>
</li>
<li>
<p>The value contains a different number of digits than what
is specified in the format string.</p>
</li>
</ul>
</div>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2365 ">
<div class="p">
<pre class="codeblock">Invalid format</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2371 ">
<div class="p">
<ul>
<li>
<p>One or more of the characters
in the <samp class="codeph">formatString</samp> do not match the allowed characters specified
in the <samp class="codeph">validPatternChars</samp> property.</p>
</li>
<li>
<p>The <samp class="codeph">areaCodeFormat</samp> property is specified
but does not contain exactly three numeric placeholders.</p>
</li>
</ul>
</div>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf648c2-7fef_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf648c2-7fef_verapache"><!-- --></a>
<h3 class="topictitle3">Formatting zip codes with an MX
formatter</h3>
<div>
<p>The <a href="https://flex.apache.org/asdoc/mx/formatters/ZipCodeFormatter.html" target="_blank">ZipCodeFormatter</a> class
lets you format five-digit or nine-digit United States ZIP codes
and six-character Canadian postal codes. The ZipCodeFormatter class's <samp class="codeph">formatString</samp> property
accepts a formatted string as a definition of the format pattern.
The <samp class="codeph">formatString</samp> property is optional. If it is
omitted, the default value of <samp class="codeph">#####</samp> is used.</p>
<p>The number of digits in the value to be formatted and the value
of the <samp class="codeph">formatString</samp> property must be five or nine
for United States ZIP codes, and six for Canadian postal codes.</p>
<p>The following table shows common <samp class="codeph">formatString</samp> values,
input values, and output values:</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d218317e2531">
<p>formatString value</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d218317e2537">
<p>Input</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d218317e2543">
<p>Output</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d218317e2549">
<p>Format</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2531 ">
<div class="p">
<pre class="codeblock">#####</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2537 ">
<p>94117, 941171234</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2543 ">
<p>94117, 94117</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2549 ">
<p>Five-digit U.S. ZIP code</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2531 ">
<div class="p">
<pre class="codeblock">#####-####</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2537 ">
<p>941171234, 94117</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2543 ">
<p>94117-1234, 94117-0000</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2549 ">
<p>Nine-digit U.S. ZIP code</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2531 ">
<div class="p">
<pre class="codeblock">### ###</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2537 ">
<p>A1B2C3</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2543 ">
<p>A1B 2C3</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2549 ">
<p>Six-character Canadian postal code</p>
</td>
</tr>
</tbody>
</table>
</div>
<p>For United States ZIP codes, if a nine-digit format is requested
and a five-digit value is supplied, ‑<samp class="codeph">0000</samp> 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. </p>
<p>For Canadian postal codes, only a six-digit value is allowed
for either the <samp class="codeph">formatString</samp> or the input value.</p>
<div class="note"><span class="notetitle">Note:</span> For United States ZIP codes, only numeric characters
are valid. For Canadian postal codes, alphanumeric characters are
allowed. Alphabetic characters must be in uppercase.</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf648c2-7fef_verapache__WS2db454920e96a9e51e63e3d11c0bf648c2-7fee_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf648c2-7fef_verapache__WS2db454920e96a9e51e63e3d11c0bf648c2-7fee_verapache"><!-- --></a><h4 class="sectiontitle">Example:
Using the ZipCodeFormatter class</h4>
<p>The following example
uses the <a href="https://flex.apache.org/asdoc/mx/formatters/ZipCodeFormatter.html" target="_blank">ZipCodeFormatter</a> class
in an MXML file:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- formatters\MainZipFormatter.mxml --&gt;
&lt;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"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
// Define variable to hold the ZIP code.
[Bindable]
private var storedZipCode:Number=123456789;
]]&gt;
&lt;/fx:Script&gt;
&lt;fx:Declarations&gt;
&lt;!-- Declare a ZipCodeFormatter and define parameters.--&gt;
&lt;mx:ZipCodeFormatter id="ZipCodeDisplay"
formatString="#####-####"/&gt;
&lt;/fx:Declarations&gt;
&lt;!-- Trigger the formatter while populating a string with data.--&gt;
&lt;s:TextInput text="{ZipCodeDisplay.format(storedZipCode)}"/&gt;
&lt;/s:Application&gt;</pre>
<p>At run time, the following
text is displayed:</p>
<p>12345-6789</p>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf648c2-7fef_verapache__WS2db454920e96a9e51e63e3d11c0bf648c2-7fed_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf648c2-7fef_verapache__WS2db454920e96a9e51e63e3d11c0bf648c2-7fed_verapache"><!-- --></a><h4 class="sectiontitle">Error
handling: ZipCodeFormatter class</h4>
<p>If an error occurs, Flex
returns an empty string and saves a description of the error in
the <a href="https://flex.apache.org/asdoc/mx/formatters/Formatter.html#error" target="_blank">error</a> property.
An error refers to a problem with the value being submitted or the
format string containing the user settings, as described in the
following table:</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d218317e2715">
<p>Value of error property</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d218317e2721">
<p>When error occurs</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2715 ">
<div class="p">
<pre class="codeblock">Invalid value</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2721 ">
<div class="p">
<ul>
<li>
<p>An invalid numeric value is passed
to the <samp class="codeph">format()</samp> method. The value should be a valid number
in the form of a Number or a String, except for Canadian postal
codes, which allow alphanumeric values.</p>
</li>
<li>
<p>The number of digits does not match the allowed digits from
the <samp class="codeph">formatString</samp> property.</p>
</li>
</ul>
</div>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2715 ">
<div class="p">
<pre class="codeblock">Invalid format</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d218317e2721 ">
<div class="p">
<ul>
<li>
<p>One or more of the characters
in the <samp class="codeph">formatString</samp> do not match the allowed characters specified
in the <samp class="codeph">validFormatChars</samp> property.</p>
</li>
<li>
<p>The number of numeric placeholders does not equal 9, 5, or
6.</p>
</li>
</ul>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<p/>
</div>
</div>
</div>
<div>
<p><strong>Navigation</strong></p>
<p><a href="index.html">Using Flex</a> &raquo; <a href="flx_p6_enhancing_usability.html">Enhancing usability</a></p>
</div>
<p>Adobe and Adobe Flash Platform are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries and are used by permission from Adobe. No other license to the Adobe trademarks are granted.</p>
</div>
</body>
</html>