Interface FormatString
format and exportFormat properties. For fields with a numeric type, the format string is similar to java.text.NumberFormat (see DecimalFormat JavaDoc), and for date, time, and datetime types, the format string is similar to java.text.SimpleDateFormat (see SimpleDateFormat JavaDoc).
Note that all the client-side formatting described in this section is is done by the NumberUtil.format() and com.smartgwt.client.util.DateUtil#format()
methods. These are static utility methods that your own code can call if you need to programmatically format a date or
number using a FormatString
There are 3 possible contexts where a FormatString may be
interpreted, and each has slightly different limitations:
in-browser rendering & client-driven exports
Almost complete support for Java's SimpleDateFormat/DecimalFormat, as described below, with some small extensions for formatting with awareness of aFiscalCalendar. This category includes cases
where code running in the browser does the rendering and the rendered result is passed to the server, such as client-driven export and PDF export of the printed view.
Excel export
Almost the same as in-browser rendering, with minor limitations due to missing features in Excel. Exact differences are described underDataSourceField.exportFormat. non-Excel server export
For example, CSV, XML or JSONexport formats provided via
DataSource.exportData(). Full support for
SimpleDateFormat/DecimalFormat as provided by whichever Java version you have installed on the server. However note
that depending on the context of the export, the default behavior may be to ignore format strings, since formatting
intended for end users wouldn't be desirable if data exchange is the goal. See the Export Formatting overview for details.
Date Format
| Format token | Description | Sample value |
| yy | Year as a two-digit number | "99" or "07" |
| yyyy | Year as a four-digit number | "1999" or "2007" |
| YY | Week year as a two-digit number (week year is the year associated with the entire week deemed to contain a given date, and it may differ from calendar year. For example, the week year of December 31 2012 is 2013) | "99" or "07" |
| YYYY | Week year as a four-digit number | "1999" or "2007" |
| LL | Fiscal year as a two-digit number (FiscalCalendar) | "99" or "07" |
| LLLL | Fiscal year as a four-digit number | "1999" or "2007" |
| M | Month in year | "1" to "12" |
| MM | Month in year with leading zero if required | "01" to "12" |
| MMM | Short month name (com.smartgwt.client.util.DateUtil#setShortMonthNames()) | "Jan" to "Dec" |
| MMMM | Full month name (com.smartgwt.client.util.DateUtil#setMonthNames()) | "January" to "December" |
| w | Week in year | "1" to "52" |
| ww | Week in year with leading zero if required | "01" to "52" |
| C | Week in fiscal year (FiscalCalendar)
| "7" or "29" |
| CC | Week in fiscal year with leading zero if required | "07" or "29" |
| d | Day of the month | "1" to "31" |
| dd | Day of the month with leading zero if required | "01" to "31" |
| ddd | Short day name (shortDayNames) | "Mon" to "Sun" |
| dddd | Full day name. (dayNames) | "Monday" to "Sunday" |
| E | Short day name ("EE" and "EEE" are equivalent; all are exactly the same as "ddd" - "E" is supported purely to conform with SimpleDateFormat) | "Mon" to "Sun" |
| EEEE | Full day name (exactly the same as "dddd") | "Monday" to "Sunday" |
| D | Day in year | "1" to "366" |
| DD | Day in year with leading zero if required | "01" to "366" |
| c | Day in fiscal year (FiscalCalendar) | "5" or "204" |
| cc | Day in fiscal year with leading zero if required | "05" or "204" |
| u | Day number in week (1 is Monday) | "1" to "7" |
| H | Hour in day, 0-23 (24-hour clock) | "0" to "23" |
| HH | Hour in day with leading zero if required (24-hour) | "00" to "23" |
| h | Hour in day, 1-12 (12-hour clock) | "1" to "12" |
| hh | Hour in day with leading zero if required (12-hour) | "01" to "12" |
| m | Minute in hour | "0" to "59" |
| mm | Minute in hour with leading zero if required | "00" to "59" |
| s | Second in minute | "0" to "59" |
| ss | Second in minute with leading zero if required | "00" to "59" |
| S | Millisecond in second | "0" to "999" |
| SSS | Millisecond in second with leading zero(s) if required | "000" to "999" |
| a | The AM/PM designator (String) | " am" or " pm" |
Note that all text that doesn't represent tokens specified above will be passed through to the output, but such
unmapped character sequences are reserved for future use. To future-proof your code, you may single quote
"'" any text to escape it to ensure no formatting is applied, guaranting that it's passed through
unaltered. Thus, a format of "h'h'" might end up as "5h". To create a single quote itself,
use two in a row - for example "h o''clock".
Examples - various formatted versions of the datetime "2006-08-03 11:26:18"
| "M/d/yy" | 8/3/06 |
| "MMMM yyyy" | August 2006 |
| "HH:mm" | 11:26 |
| "d MMM yyyy, H:ma" | 3 Aug 2006, 11:26 am |
| "dd/MM/yyyy" | 03/08/2006 |
| "CC/LLLL" | 53/2006 (assuming the fiscal year ends in the first week of August) |
SimpleDateFormat specifiers
that we do not support:
- Era designator, BC/AD (G)
- Day of week in month (F)
- Hour in day, 24-hour, with 1-based instead of normal 0-based numbering (hours are 1-24) (k)
- Hour in day, 12-hour, with 0-based instead of normal 1-based numbering (hours are 0-11) (K)
- Timezone (z, Z, X)
Number Format
| Format char | Description |
| 0 | Digit, zero is displayed |
| # | Digit, zero is not displayed |
| - | Minus sign |
| . | Decimal separator |
| % | Multiply by 100 and show as percentage |
| ‰ (‰) | Multiply by 1000 and show as per mille. See below. |
| , | Indicates digit grouping should be used - eg 1,000,000. See below. |
| ; | Separates positive and negative subpatterns. See below. |
| ¤ (\\u00A4) | As a prefix or suffix, indicates the local currency symbol should be used. Note that you must use special notation to include this character in an XML file (such as a .ds.xml file). See below. |
| ' | Used to quote special characters in a prefix or suffix, for example, "'#'#" formats 123 to "#123". To create a single quote itself, use two in a row: "# o''clock". |
All other characters in the format string are taken literally and output unchanged.
Examples
| Format string | Zero value | Positive value: 12345.678 | Negative value: -2345.123 |
| "0.00" | 0.00 | 12345.68 | -2345.12 |
| ",##0.00" | 0.00 | 12,345.68 | -2,345.12 |
| "0.###" | 0 | 12345.678 | -2345.123 |
| "¤,0.00" | $0.00 | $12,345.68 | -$2345.12 |
| "0.0#%" | 0.0% | 1234567.8% | -234512.3% |
| "0.0#‰" | 0.0‰ | 12345678.0‰ | -2345123.0‰ |
| "0.0#'%'" | 0.0% | 12345.68% | -2345.12% |
| "0.00;(0.00)" | 0.0% | 12345.68 | (2345.12) |
Note, the above examples include cases where there are multiple '#' characters in the integer part of the number format (ie, to the left of the decimal separator, or the entire format if there is no separator). We support this pattern simply because
DecimalFormat does: the extra '#' characters are not significant. In other words, the format "##0.00"
produces exactly the same formatting as "0.00", and "##,###,###.##" produces exactly the same formatting as ",#.##".
However, multiple '0' characters in the integer part of the format are significant, as are both '#' and '0'
characters in the decimal part of the format (ie, to the right of any decimal separator). The ";" character marks the boundary between two subpatterns - the first to be used for formatting positive numbers (and 0), the second for negative numbers. Specifying a separate pattern for negative numbers is optional: if no negative subpattern is specified, negative numbers are formatted like positive numbers, but with a leading "-" sign.
The "¤" symbol (¤) is documented in the Java DecimalFormat class as a placeholder for the currency symbol appropriate to the current locale. For client-driven exports, we replace it with whatever GWT's built-in NumberFormat's class uses. Likewise, the decimal symbol and grouping symbol will match what GWT's NumberFormat returns. Note that "¤" is the correct way to specify this character in Javascript code. If you need to specify the character in an XML file - the common requirement is in a .ds.xml DataSource descriptor file - you must use the code "¤" instead.
The "‰" per mille symbol is specified as "‰" in Javascript code; in XML or HTML you can use either the equivalent notation "‰" or the special HTML code "‰".
DecimalFormat features
that we do not support:
- Scientific notation
- Doubled currency symbol means "use international currency symbol"
- We do not support arbitrary digit grouping, by providing patterns of the '#' and
',' characters, like
DecimalFormatdoes. Grouping in Smart GWT FormatStrings is enabled with a single "," character somewhere before or within the number-formatting part of the string - extra "," characters within the number-formatting part of the string are tolerated, but they have no effect. Grouping in Smart GWT always causes digits to be gathered in groups of three