DateField - CUBA Platform. Developer’s Manual

5.5.2.1.8. DateField

DateField is a field to display and enter date and time. It is an input field, inside which there is a button with a drop-down calendar. To the right, there is a time field.

XML name of the component: dateField.

The DateField component is implemented for Web Client and Desktop Client.

To create a date field associated with data, you should use the datasource and property attributes:
```
<dsContext>
    <datasource id="orderDs" class="com.sample.sales.entity.Order" view="_local"/>
</dsContext>
<layout>
    <dateField datasource="orderDs" property="date"/>
```
In the example above, the screen has the orderDs data source for the Order entity, which has the date property. The reference to the data source is specified in the datasource attribute of the dateField component; the name of the entity attribute which value should be displayed in the field is specified in the property attribute.
If the field is associated with an entity attribute, it will automatically take the appropriate form:
- If the attribute has the java.sql.Date type or the @Temporal(TemporalType.DATE) annotation is specified, the time field will not be displayed. The date format is defined by the date datatype and is specified in the main localized message pack in the dateFormat key.
- Otherwise, the time field with hours and minutes will be displayed. The time format is defined by the time datatype and is specified in the main localized message pack in the timeFormat key.

You can change the date and time format using the dateFormat attribute. An attribute value can be either a format string itself or a key in a message pack (if the value starts with msg://).

The format is defined by rules of the SimpleDateFormat class (http://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html). If there are no H or h characters in the format, the time field will not be displayed.

<dateField dateFormat="MM/yy" caption="msg://monthOnlyDateField"/>

Warning

DateField is primarily intended for quick input by filling placeholders from keyboard. Therefore the component supports only formats with digits and separators. Complex formats with textual representation of weekdays or months will not work.

You can specify available dates by using rangeStart and rangeEnd attributes. If a range is set, all dates outside the range will be disabled. You can set range dates in the "yyyy-MM-dd" format in XML or programmatically by using corresponding setters.
```
<dateField id="dateField" rangeStart="2016-08-15" rangeEnd="2016-08-19"/>
```
Changes of the DateField value, as well as of any other components implementing the Field interface, can be tracked using a ValueChangeListener.

Date and time accuracy can be defined using a resolution attribute. An attribute value should match the DateField.Resolution enumeration − SEC, MIN, HOUR, DAY, MONTH, YEAR. Default is MIN, i.e., to within a minute.

If resolution="DAY" and dateFormat is not specified, the format will be taken from one specified in the main message pack with the dateFormat key.

If resolution="MIN" and dateFormat is not specified, the format will be taken from one specified in the main message pack with the dateTimeFormat key. Below is a field definition for entering a date up to within a month.
```
<dateField resolution="MONTH" caption="msg://monthOnlyDateField"/>
```

DateField can perform timestamp value conversions between server and user time zones if the user’s time zone is set by setTimeZone() method. The time zone is assigned automatically from the current user session when the component is bound to an entity attribute of the timestamp type. If the component is not bound to such attribute, you can call setTimeZone() in the screen controller to make the DateField perform required conversions..

In Web Client with a Halo-based theme, you can set predefined borderless style name to the DateField component to remove borders and background from the field. This can be done either in the XML descriptor or in the screen controller:
```
<dateField id="dateField"
           stylename="borderless"/>
```
When setting a style programmatically, select the HaloTheme class constant with the DATEFIELD_ prefix:
```
dateField.setStyleName(HaloTheme.DATEFIELD_BORDERLESS);
```

Attributes of dateField: align - caption - datasource - dateFormat - description - editable - enable - height - icon - id - property - stylename - required - rangeEnd - rangeStart - requiredMessage - resolution - tabIndex - visible - width
Elements of dateField: validator
Predefined styles of dateField: borderless
API: addValueChangeListener - commit - discard - isModified