public interface DateFormatAndStorage
DataSources and databound components may define fields of type date
,
time
, or datetime
.
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.
The DateUtil.createLogicalDate() method may be used to create a new Date object to represent a logical date value on the browser.
System wide formatting for dates may be controlled via the
Date.setNormalDisplayFormat()
and
Date.setShortDisplayFormat()
methods.
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 datetime
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).
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.
The DateUtil.createLogicalTime() method may be used to create a new Date object to represent a logical time value on the browser.
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 TimeDisplayFormat
s, and
by the standard short DateDisplayFormat
s 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 DataSourceField.dateFormatter
,
DataSourceField.timeFormatter
and for example ListGridField.dateFormatter
).
Date formatting may also be configured at the component level by setting the
dateFormatter
, datetimeFormatter
and timeFormatter
attributes (See for example ListGrid.dateFormatter
, ListGrid.timeFormatter
,
and ListGrid.datetimeFormatter
).
Date and time storage and timezones can be confusing, and Isomorphic receives a steady stream of false bug reports from users that are incorrectly analyzing logs and diagnostics. Please consider the following points when troubleshooting issues such as date values changing to a different day, or datetime value shifting when saved and reloaded:
Whenever you use Date.toString() (client or server-side) the value you get is based on the server or browser timezone.
Perhaps you are troubleshooting an issue with datetimes and you try to log the value of a Date like this:
Date someDate = <some expression>; log("date value is: " + someDate);Code like this will show the datetime value in the server's timezone if executed server-side, and in the client's timezone if executed client-side. If they are in different timezones, the hour or day will be different, whereas the actual datetime value - milliseconds since epoch as retrieved by Date.getTime() - is the same. To correctly compare two datetime values, compare the result of getTime().
This is the inverse situation as for "datetime" values. As explained above, "date" values have no meaningful values for time fields (hours/minutes/seconds) and "time" values have no meaningful values for date fields (month/day/year). Here, the result of Date.getTime() is not meaningful, and values should be compared via getHours(), getMonth() et al.
If you've called setDefaultDisplayTimezone() to cause all datetime values to be rendered in a particular timezone, this does not affect the return values of Date.getHours(), which will still return values for the browser's current timezone. Hence it is not a bug if you have a "datetime" value which is displaying as 4am, but getHours() returns 10 or some other number. This just reflects the timezone offset between the timezone passed to setDefaultDisplayTimezone() and the browser's local timezone.
If you declare a field as type "date" but values you provide actually contain specific hours, minutes and seconds, these will not be preserved. The system will discard or reset the hours, minutes and seconds in the course of serialization or editing. Likewise if you declare a field as type "time" but actually provide values where year, month and day have meaning, these values will be dropped.
Similarly, DateItem expects values for "date" fields, TimeItem expects values for "time" fields, and DateTimeItem expects values for "datetime" fields. Providing the wrong type of value to a control, such as providing a value from a "datetime" field to a DateItem, will have unspecified results.
If you want to take the date and time aspects of a "datetime" value and edit them in separate
FormItems, use
getLogicalDateOnly()
and DateUtil.getLogicalTimeOnly()
to
split a datetime value into date and time values, and use
DateUtil.combineLogicalDateAndTime()
to re-combine
such values. Otherwise it is very
easy to make mistakes related to timezone offsets.
If you're having a problem with round-tripping "datetime" values or "date" values shifting to another day, you need to isolate the problem to a specific layer. Bearing in mind the techniques above for comparing values, you potentially need to look at any/all of the following:
DataSource.fetchData()
and inspect the
data in the callback)
DataSource.transformRequest()
is a good place to check)