com.smartgwt.client.docs
Interface DateFormatAndStorage

public interface DateFormatAndStorage

Date and Time Format and Storage

The Smart GWT system has the following features for handling Date and Time type values within DataSources and databound components.

DataSources and databound components may define fields of type date, time, or datetime.

"date" handling

Fields of type date are considered to be logical Dates with no time value, such as a holiday or birthday. In the browser, values for "date" fields are stored as Date objects, but when formatted for display to the user, they are typically displayed without any time information.

When using the Smart GWT server framework, "date" values are automatically transmitted with year, month and day preserved and time value ignored.

When sent or received in XML or JSON, date field values should be serialized in the XML Schema date format - YYYY-MM-DD - are expected to be received in the same format. Any time value present for a "date" field is ignored.

System wide formatting for dates may be controlled via the Date.setNormalDisplayFormat and Date.setShortDisplayFormat methods.

"datetime" handling

Fields of type datetime are dates with full time information. In the browser, values for datetime fields are stored as Date objects.

When using the Smart GWT server framework, "datetime" values are automatically transmitted such that the resulting Date object has the same GMT/UTC timestamp (milliseconds since epoch).

When sent or received in XML or JSON, datetime field values should be serialized out as full datetimes using the standard XML Schema date format (EG:2006-01-10T12:22:04-04:00). If no timezone offset is supplied, the value is assumed to be GMT/UTC.

System wide formatting for datetimes may be controlled via the Date.setShortDatetimeDisplayFormat method. Datetimes will be displayed to the user in browser local time by default (see also timezone notes below).

"time" handling

Fields of type time are time values in the absence of a day, such as the beginning of the workday (9:00). In the browser, values for "time" fields are stored as Date objects with the time in browser local time. The date information has no meaning and only the time information is displayed to the user.

Time formatting is handled by the String class APIs.
When using the Smart GWT server framework, "time" values are automatically transmitted such that the resulting Date object has the same hour, minute and second values in local time, and year/month/day is ignored.

When sent or received in XML or JSON, date field values should be serialized as hours, minutes and seconds using the standard XML Schema time format - "22:01:45". Timezone is not relevant and should be omitted.

Timezone settings and Daylight Savings Time

By default, "datetime" values will be shown to the user in browser local time, as derived from the native browser locale. Developers may modify this behavior by specifying an explicit display timezone via String.

Note that depending on the specific date being displayed, a Daylight Savings Time offset may also be applied based on the browser locale. To disable this behavior set String to false.

If a custom timezone is specified, it will be respected by all TimeDisplayFormats, and by the standard short DateDisplayFormats when formatting dates representing datetime type values. However native JavaScript Date formatters, including toLocaleString() will not respect the specified timezone. Developers specifying a custom timezone may therefore wish to modify the Date.setNormalDisplayFormat to avoid using a native JS Date formatter function.

Note that in addition to the system-wide date, datetime and time-formatting settings described above, databound components also support applying custom display formats for date values. Typically this can be achieved via a custom dateFormatter or timeFormatter at the field level (see dateFormatter, timeFormatter and for example dateFormatter). Date formatting may also be configured at the component level by setting the dateFormatter, datetimeFormatter and timeFormatter attributes (See for example dateFormatter, timeFormatter, and datetimeFormatter).