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.

Fields of type FieldType are considered to be logical Dates. System wide formatting for dates may be controlled via the com.smartgwt.client..Date#setNormalDisplayFormat and com.smartgwt.client..Date#setShortDisplayFormat methods. Components also support applying custom display formats for specific date fields, typically achieved via the dateFormatter or field.displayFormat attributes.

On the client date type fields are stored as JavaScript Date objects. When formatted for display to the user, they are typically displayed without any time information.

When communicating with a non Smart GWT server via an "xml" DataSource, date field values in requests will be serialized out as logical date information only (omitting time) in the standard truncated XML Schema date format - YYYY-MM-DD. Date values received from the server in responses are expected to be in the same format, though if time information is included in the returned date-string it will be understood. This matches the default date serialization behavior for "json" dataSources, though dates may also be communicated as a JavaScript date instantiation string (EG: new Date(1238792738633)). See dateFormat.

Fields of type FieldType are dates with full time information. System wide formatting for datetimes may be controlled via the com.smartgwt.client..Date#setShortDatetimeDisplayFormat method, or at a component level by datetimeFormatter or field.displayFormat attributes. DateTimes willbe displayed to the user in local time as set up via com.smartgwt.client..Time#setDefaultDisplayTimezone. Note that if not explicitly set, this will default to the browser native timezone.

On the client datetime type fields are stored as JavaScript Date objects. When communicating with a non Smart GWT server via an "xml" DataSource, datetime field values in requests will be serialized out as full datetimes in UTC using the standard XML Schema date format - YYYY-MM-DDTHH:MM:SS. Date values received from the server in responses are expected to also be in XML Schema date format - and assumed to be in UTC time unless an explicit timezone offset is specified on the datetime string (EG:2006-01-10T12:22:04-04:00). As with dates, "json" format dataSources use the same XML Schema format by default but may use JavaScript date instantiaion strings instead.

Fields of type FieldType are logical time values. These are stored on the client as JavaScript date objects, but only the time information is displayed to the user. Time formatting is handled by the com.smartgwt.client..Time class APIs. By default times are displayed to users in the display timezone set up via com.smartgwt.client..Time#setDefaultDisplayTimezone [if not explicitly set, defaults to native browser local time].
When communicating with a non Smart GWT server via an "xml" DataSource, time field values in requests will be serialized out as full times in UTC using the standard XML Schema date / time format - HH:MM:SS. Note that the flag com.smartgwt.client.data.DataSource#serializeTimeAsDatetime may be set to serialize all times as full datetimes rather than just time strings. Time values received from the server in responses are expected to be in the same format, in UTC, or with an explicit timezone offset specified (for example "22:01:45-01:00")

When communicating with the Smart GWT server fields of type date, datetime and time are all automatically translated to Java date objects on the server side.