11.7 Formatting Actions
| The JSTL formatting actions parse and format numbers , currencies, percents, and dates. Four configuration settings support these actions. Overview of the JSTL Formatting ActionsTable 11.17 lists the JSTL formatting actions. Table 11.17. Formatting Actions
JSTL Formatting Configuration SettingsThe following configuration settings support the JSTL formatting actions:
The FMT_TIME_ZONE configuration setting is listed in Table 11.18. Table 11.18. FMT_TIME_ZONE
The <fmt:formatDate> and <fmt:parseDate> actions require a time zone to format and parse times, respectively. If you do not specify the timeZone attribute for those actions and those actions do not reside in a <fmt:timeZone> action, they will use the time zone stored in the FMT_TIME_ZONE configuration setting. That configuration setting can be set in a number of different ways; one way to set it is with the <fmt:setTimeZone> action. You can also set the FMT_TIME_ZONE configuration setting with a context initialization parameter or in a business component. See "Configuration Settings" on page 230 for more information on how to do that. The <fmt:formatNumber>, <fmt:parseNumber>, <fmt:formatDate>, and <fmt:parseDate> actions use the locale stored in the FMT_LOCALIZATION_CONTEXT configuration setting if they do not reside in a <fmt:bundle> action and the parseLocale attribute was not specified (for <fmt:parseNumber> and <fmt:parseDate>). The locale stored in the FMT_LOCALE configuration setting is used by the <fmt:formatNumber>, <fmt:parseNumber>, <fmt:formatDate>, and <fmt:parseDate> actions when those actions do not reside in a <fmt:bundle> action and the localization context in the FMT_LOCALIZATION_CONTEXT configuration setting has not been set or does not have a locale. See "<fmt:bundle>" on page 500 for more information about the <fmt:bundle> action, and see "JSTL Internationalization Configuration Settings" on page 494 for more information about the FMT_LOCALE and FMT_LOCALIZATION_CONTEXT configuration settings. The <fmt:formatNumber>, <fmt:parseNumber>, <fmt:formatDate>, and <fmt:parseDate> actions use the locale stored in the FMT_FALLBACK_LOCALE configuration setting as a last resort to locate a formatting locale. See "JSTL Internationalization Configuration Settings" on page 494 for more information about the FMT_FALLBACK_LOCALE configuration setting, and see "Formatting Locale Lookup" on page 354 for more information about how formatting actions look up a locale. JSTL Formatting Actions
Syntax: [19]
Syntax #1: Without a body <fmt:formatNumber value [type] [pattern] [currencyCode] [currencySymbol] [groupingUsed] [minIntegerDigits] [maxIntegerDigits] [minFractionDigits] [maxFractionDigits] [var] [scope]/> Syntax #2: With a body that specifies a numeric value to format <fmt:formatNumber [type] [pattern] [currencyCode] [currencySymbol] [groupingUsed] [minIntegerDigits] [maxIntegerDigits] [minFractionDigits] [maxFractionDigits] [var] [scope]> value </fmt:formatNumber> Description: The <fmt:formatNumber> action formats a numeric value in a locale-dependent manner as a number, currency, or percent. You can specify that numeric value with the value attribute or in the body of the <fmt:formatNumber> action. By default, <fmt:formatNumber> sends its output to the current JspWriter , but if you specify the var attribute, and optionally , the scope attribute, <fmt:formatNumber> stores its output in a scoped variable instead. Attributes:
Constraints and Error Handling:
In a Nutshell: The <fmt:formatNumber> action formats numbers, currencies, and percents differently for different locales; for example: <fmt:setLocale value='en-US'/> English: <fmt:formatNumber value='1255.23'/> <fmt:setLocale value='de-DE'/> German: <fmt:formatNumber value='1255.23'/> In the preceding code fragment, <fmt:formatNumber> formats the string " 1255.23" as 1,255.23 for English and 1.255,23 for German. Most of the time, the value that you specify for <fmt:formatNumber> will probably be a variable that you read from a data store, such as a database or flat file, so <fmt:formatNumber> lets you specify its value as a scoped variable; for example: <%-- Typically, the numericValue scoped variable would be calcu- lated or created from a value stored in a data store; here, <c:set> is used in the interest of simplicity --%> <c:set var='numericValue' value='234682.155'/> <fmt:formatNumber value='${numericValue}'/> Besides specifying a value with the value attribute, you can also specify a value in the body of the <fmt:formatNumber> action. That feature is useful for computed values, such as those produced by a custom action; for example: <fmt:formatNumber> <acme:getSomeNumericValue/> </fmt:formatNumber> You can specify whether <fmt:formatNumber> formats its value as a number, currency, or percent with the type attribute, like this: <fmt:formatNumber value='1255.23'/> <fmt:formatNumber value='1255.23' type='currency'/> <fmt:formatNumber value='.2348' type='percent'/> For the U.S. English locale, the preceding code fragment will produce the following output: 1,255.23 $1,255.23 23% . If you don't specify the type attribute, as is the case for the first line of code in the preceding code fragment, that attribute defaults to number . Notice that <fmt:formatNumber> formats percents by multiplying the value by 100 and adding a locale-dependent percent symbol. Most of the <fmt:formatNumber> attributes are used to control exactly how numbers, currencies, and percents are formatted; for example: <fmt:formatNumber value='1255.23' minIntegerDigits='5' minFractionDigits='5' groupingUsed='false'/> For the U.S. English locale, the preceding code fragment formats the specified value like this: 01255.23000 . With the currencySymbol attribute, you can directly specify the currency symbol that <fmt:formatNumber> uses to format currencies, like this: <fmt:setLocale value='en-US'/> <fmt:formatNumber value='1255.23' type='currency' currencySymbol='[$]'/> In the preceding code fragment, the <fmt:formatNumber> action formats its value for U.S. currency but uses the currency symbol [$] , so the output is [$]1,255.23 . You can also indirectly specify a currency symbol with the currencyCode attribute; for example: <fmt:setLocale value='fr-FR'/> <fmt:formatNumber value='1255.23' type='currency' currencyCode='FRF'/> The <fmt:formatNumber> action in the preceding code fragment formats its value for French francs, which is specified with the FRF currency code, so the output is 1 255,23 F . You can also specify custom formatting patterns for numbers and currencies; for example: <fmt:setLocale value='en-US'/> <fmt:formatNumber value='1255.23' pattern='#,#.000000'/> <fmt:setLocale value='de-DE'/> <fmt:formatNumber value='1255.23' pattern='#,#.000000'/> The output of the first <fmt:formatNumber> action in the preceding code fragment is 1,2,5,5.230000 , and the output of the second <fmt:formatNumber> action is 1.2.5.5,230000 . The same formatting pattern is used in each case, but the formatting symbols are locale-dependent; those formatting symbols remain the same, regardless of the <fmt:formatNumber> attributes that you specify.
Syntax: [20]
Syntax #1: Without a body <fmt:parseNumber value [type] [pattern] [parseLocale] [integerOnly] [var] [scope]/> Syntax #2: With a body that specifies a number to format <fmt:parseNumber [type] [pattern] [parseLocale] [integerOnly] [var] [scope]> value </fmt:parseNumber> Description: The <fmt:parseNumber> action is the inverse of <fmt:formatNumber>: it parses a string representing a formatted number, currency, or percent into a number. You can specify that string with the value attribute or in the body of the <fmt:parseNumber> action. By default, <fmt:parseNumber> sends its output to the current JspWriter , but if you specify the var attribute, <fmt:parseNumber> stores its output in a scoped variable instead. Attributes:
Constraints and Error Handling:
In a Nutshell: Sometimes you need to manipulate numeric values that are already formatted as numbers, currencies, or percents. For those types of use cases, you can use <fmt:parseNumber> to parse the original formatted value. You can then adjust the numeric value that <fmt:parseNumber> produces and subsequently use <fmt:formatNumber> to reformat the adjusted numeric value. For example, the following code fragment uses <fmt:parseNumber> in the manner described above: <c:set value=',255.23' var='formattedCurrency'/> <fmt:parseNumber value='${formattedCurrency}' type='currency' parseLocale='en-US' var='parsedCurrency'/> <c:set value='${parsedCurrency + 250}' var='updatedAmount'/> <fmt:setLocale value='en-US'/> <fmt:formatNumber value='${updatedAmount}' type='currency'/> The preceding code fragment uses the <c:set> action to create a scoped variable that references a formatted currency, but that formatted currency could come from anywhere , perhaps from a Web Service. The <fmt:parseNumber> action parses that formatted currency, using the U.S. English locale and stores the resulting numeric value in a scoped variable named parsedCurrency . Subsequently, the <c:set> action adds 250 to that parsed amount and stores the resulting value in a scoped variable named updatedAmount . Finally, the <fmt:formatNumber> action reformats the updated amount as U.S. currency. The output of the preceding code fragment is $1505.23 . The <fmt:parseNumber> action can be rather picky about the value it parses ”if its value does not match the attributes that you specify, <fmt:parseNumber> will throw an exception. In the preceding code fragment, if the parsed currency is not formatted correctly, <fmt:parseNumber> throws an exception; for example, if you specify that formatted currency as 1,255.23 instead of $1,255.23 , <fmt:parseNumber> will throw an exception because it cannot parse the specified value as U.S. currency. If <fmt:parseNumber> throws an exception, check the formatting of the value specified for <fmt:parseNumber>. Like <fmt:formatNumber>, <fmt:parseNumber> has a type attribute that you can set to number , currency , or percent . Unlike <fmt:formatNumber>, <fmt:parseNumber> has a parseLocale attribute that you can use to specify the locale that <fmt:parseNumber> uses to parse its value. The parseLocale attribute was used in the preceding code fragment. The <fmt:parseNumber> action also has an integerOnly attribute. If you set that attribute to true , <fmt:parseNumber> will only parse the integer portion of its numeric value. You can also specify custom parsing patterns with the pattern attribute, just like you can specify custom formatting patterns for <fmt:formatNumber>.
Syntax: [21]
<fmt:formatDate value [type] [dateStyle] [timeStyle] [pattern] [timeZone] [var] [scope]/> Description: The <fmt:formatDate> action formats an instance of java.util.Date in a locale-dependent manner. You specify that date with the value attribute. By default, <fmt:formatDate> sends its output to the current JspWriter , but if you specify the var attribute, <fmt:formatDate> stores its output in a scoped variable instead. Attributes:
Constraints and Error Handling:
In a Nutshell: The <fmt:formatDate> action formats an instance of java.util.Date and outputs a string representation of that formatted date. You can create a Date instance with <jsp:useBean>, like this: <jsp:useBean id='now' class='java.util.Date'/> <fmt:formatDate value='${now}'/> In the preceding code fragment, <jsp:useBean> creates an instance of java.util.Date , representing the current date and time, which is subsequently formatted by <fmt:formatDate>. You can also create a Date instance with the <fmt:parseDate> action; see "<fmt:parseDate>" on page 522. The <fmt:formatDate> action will format the same date differently for different locales; for example, if the current date is the 1st of June 1998, the preceding code fragment will output Jun 1, 1998 for U.S English; for France French, the preceding code fragment will output 1 juin 1998 . All instances of java.util.Date contain date and time information. The <fmt:formatDate> action lets you format the date portion, the time portion, or both the date and time with the <fmt:formatDate> type attribute; for example: <jsp:useBean id='now' class='java.util.Date'/> <fmt:formatDate value='${now}'/> <fmt:formatDate value='${now}' type='time'/> <fmt:formatDate value='${now}' type='both'/> If you don't specify the type attribute, it defaults to date . In the preceding code fragment, if the locale is U.S. English and the current time and date is 3:55:41 P.M. on the 15th of May 2002, the first <fmt:formatDate> action will format that date like this: May 15, 2002 . The second <fmt:formatDate> action in the preceding code fragment formats only the time portion of the date and produces this output: 3:55:41 PM . The last <fmt:formatDate> action formats both the date and time, like this: May 15, 2002 3:55:41 PM . The <fmt:formatDate> dateStyle and timeStyle attributes let you specify a locale-dependent predefined formatting style for dates and times, respectively; for example: <jsp:useBean id='now' class='java.util.Date'/> <fmt:formatDate value='${now}' type='time' timeStyle='short'/> The preceding code fragment formats the current time in short format. If the current time is 4:05 in the afternoon, the output of the preceding code fragment for U.S. English will be 4:05 PM . Table 8.4 on page 334 illustrates the various styles for dates and times. In addition to the predefined date and time styles, you can also specify a custom pattern with the <fmt:formatDate> pattern attribute, like this: <jsp:useBean id='now' class='java.util.Date'/> <fmt:formatDate value='${now}' pattern='MM/dd/yy, hh:mm'/> For the U.S. English locale, on the 5th of May 2002 at 4:15 P.M., the preceding code fragment will produce this output: 05/15/02, 04:15 . Table 8.5 on page 337 lists the valid characters that constitute a custom date and time pattern. You can also specify a time zone with the <fmt:formatDate> timeZone attribute, and <fmt:formatDate> will format its date relative to that time zone; for example: <jsp:useBean id='now' class='java.util.Date'/> <fmt:formatDate value='${now}' type='time' timeStyle='short'/> <fmt:formatDate value='${now}' type='time' timeStyle='short' timeZone='America/Los_Angeles'/> If your server resides in the U.S. Eastern time zone and the current time is 5:00 in the afternoon, the first <fmt:formatDate> action in the preceding code fragment will output 5:00 PM for the U.S. English locale, whereas the second <fmt:formatDate>, which interprets the time relative to the U.S. Pacific time zone, will produce this output: 2:00 PM .
Syntax: [22]
Syntax #1: Without a body <fmt:parseDate value [type] [dateStyle] [timeStyle] [pattern] [timeZone] [parseLocale] [var] [scope]/> Syntax #2: With a body that specifies a date string to parse <fmt:parseDate [type] [dateStyle] [timeStyle] [pattern] [timeZone] [parseLocale] [var] [scope]> value </fmt:parseDate> Description: The <fmt:parseDate> action is the inverse of <fmt:formatDate>: it parses a string representing a formatted date, time, or both, into its original, unformatted form. You can specify that string with the value attribute or in the body of the <fmt:parseDate> action. By default, <fmt:parseDate> sends its output to the current JspWriter , but if you specify the var attribute, <fmt:parseDate> stores its output in a scoped variable instead. Attributes:
Constraints and Error Handling:
In a Nutshell: The <fmt:parseDate> action parses a string into an instance of java.util.Date . Because <fmt:formatDate> does not accept a string value for the value attribute ”<fmt:formatDate> only formats instances of java.util.Date ”<fmt:parseDate> is commonly used to parse a string to provide a Date instance for <fmt:formatDate>, like this: <fmt:parseDate value='06/01/98' var='parsedDate' dateStyle='short'/> <fmt:formatDate value='${parsedDate}'/> In the preceding code fragment, <fmt:parseDate> parses the string 06/01/98 and creates a java.util.Date instance that it stores in a scoped variable named parsedDate . Subsequently, <fmt:formatDate> formats that Date instance. The output of the preceding code fragment for the U.S. English locale is Jun 1, 1998 . The following <fmt:parseDate> attributes let you specify how the string that <fmt:parseDate> parses is interpreted: dateStyle , timeStyle , and parseLocale . You must make sure that those attributes match the string that <fmt:parseDate> parses; for example, in the following code fragment <fmt:parseDate> will throw an exception: <%-- This code fragment throws an exception --%> <fmt:parseDate value='06/01/98' dateStyle='long'/> In the preceding code fragment, the <fmt:parseDate> dateStyle attribute is set to long , but the string that <fmt:parseDate> tries to parse is formatted with the short format for dates. Because of that mismatch, <fmt:parseDate> will throw an exception. You must also make sure that the parse locale used by <fmt:parseDate> matches the value that <fmt:parseDate> parses; for example, the following code fragment also throws an exception: <%-- This code fragment throws an exception also --%> <fmt:parseDate value='06/20/98' dateStyle='short' parseLocale='fr-FR'/> In the preceding code fragment, the string that <fmt:parseDate> tries to parse is formatted as MM/dd/yy , where M represents the month, d represents the day, and y represents the year. But because the parseLocale attribute is set to France French and because dates in that locale are formatted as dd/MM/yy , the <fmt:parseDate> action will not be able to parse its string (20 is not a valid month), and therefore that action will throw an exception. For dates and times that are not formatted according to one of the standard formats ”see Table 8.4 on page 334 for more information about those standard formats ”you can specify a custom pattern with the <fmt:parseDate> pattern attribute, like this: <fmt:parseDate value='06/20/98, 10:25' pattern='MM/dd/yy, hh:mm'/> If you specify a custom pattern, as in the preceding code fragment, you must make sure that the pattern matches the string that <fmt:parseDate> tries to parse. For example, in the preceding code fragment, if you change the pattern to MM/dd/yy, hh:mm:ss , the <fmt:parseDate> action will throw an exception.
Syntax: <fmt:timeZone value> body content, presumably with <fmt:formatDate> or <fmt:parseDate> actions </fmt:timeZone> Description: The <fmt:formatDate> and <fmt:parseDate> actions format and parse dates, respectively, according to a time zone. One way to specify that time zone is with the <fmt:timeZone> action, which establishes a time zone for <fmt:formatDate> and <fmt:parseDate> actions that reside in the body of the <fmt:timeZone> action. You specify that time zone with the <fmt:timeZone> action's value attribute, which can be either a string or an instance of java.util.TimeZone . Attributes:
Constraints and Error Handling:
In a Nutshell: You can use the <fmt:timeZone> action to specify a time zone for <fmt:parseDate> and <fmt:formatDate> actions, like this: <jsp:useBean id='now' class='java.util.Date'/> <fmt:timeZone value='America/New_York'> <fmt:formatDate value='${now}' type='time' timeStyle='full'/> </fmt:timeZone> In the preceding code fragment, if the current time is 10:30 A.M. MDT, the <fmt:formatDate> action will produce this output: 12:30:00 PM EDT . You can override the time zone specified with the <fmt:timeZone> action with the timeZone attribute for <fmt:formatDate> and <fmt:parseDate>; for example: <jsp:useBean id='now' class='java.util.Date'/> <fmt:timeZone value='America/New_York'> <fmt:formatDate value='${now}' type='both' timeStyle='full'/> <fmt:formatDate value='${now}' type='both' timeZone='America/Denver' timeStyle='full'/> </fmt:timeZone> In the preceding code fragment, the first <fmt:formatDate> action formats the current date and time for U.S. Eastern Time, whereas the second <fmt:formatDate> formats the current date and time for Mountain Daylight Time.
Syntax: [23]
<fmt:setTimeZone value [var] [scope]/> Description: The <fmt:formatDate> and <fmt:parseDate> actions format and parse dates, respectively, according to a time zone. One way to specify that time zone is with the <fmt:setTimeZone> action, which stores a time zone in the FMT_TIME_ZONE configuration setting or, if you specify the var attribute, a scoped variable. You specify that time zone with the value attribute, which can be either a string or an instance of java.util.TimeZone . Attributes:
Constraints and Error Handling:
In a Nutshell: The <fmt:setTimeZone> action stores a time zone in the FMT_TIME_ZONE configuration setting or in a scoped variable. This action is useful if you need to set a time zone for <fmt:formatDate> and <fmt:parseDate> actions that span one or more JSP pages. There are a number of ways that you can use <fmt:setTimeZone>; here are some examples: <fmt:setTimeZone value='America/New_York'/> <fmt:setTimeZone value='America/New_York' scope='request'/> <fmt:setTimeZone value='America/New_York' var='timeZone'/> <fmt:setTimeZone value='America/New_York' var='timeZone' scope='session'/> In the preceding code fragment, the first line of code sets the America/New_York Time time zone for the current JSP page. It does that by storing the time zone in a configuration variable named FMT_TIME_ZONE in page scope, which overrides the configuration setting of the same name in that scope. If the FMT_TIME_ZONE configuration setting was previously set for a scope other than page scope, that setting will be restored when the current JSP page is no longer active. See "Configuration Settings" on page 230 for more information about JSTL configuration settings. The second line of code in the preceding code fragment stores the America/New_York time zone in the FMT_TIME_ZONE configuration variable for request scope, making that time zone the default for the current HTTP request. If the FMT_TIME_ZONE configuration setting was previously set for session or application scope, that setting will be restored when the current HTTP request is finished. The last two lines of code in the preceding code fragment store the America/New_York Time time zone in a scoped variable. The third line of code stores that scoped variable in page scope, and the last line of code stores that scoped variable in session scope. You can access that scoped variable like this: <fmt:formatDate value='${now}' type='both' timeZone='${timeZone}' timeStyle='full'/> |
![Core JSTL[c] Mastering the JSP Standard Tag Library](/icons/blank_book.jpg "Core JSTL[c] Mastering the JSP Standard Tag Library"){kind=icon}
EAN: N/A
Pages: 124