Enables the users to select a localized date between 0001-01-01 and 9999-12-31.
The DatePicker
lets the users select a localized date using touch, mouse, or keyboard input. It consists of two parts: the date input field and the date picker.
Note: The application developer should add dependency to sap.ui.unified
library on application level to ensure that the library is loaded before the module dependencies will be required. The sap.ui.unified.Calendar is used internally only if the DatePicker
is opened (not used for the initial rendering). If the sap.ui.unified
library is not loaded before the DatePicker
is opened, it will be loaded upon opening. This could lead to CSP compliance issues and adds an additional waiting time when the DatePicker
is opened for the first time. To prevent this, apps using the DatePicker
should also load the sap.ui.unified
library in advance.
The user can enter a date by:
On app level, there are two options to provide a date for the DatePicker
- as a string to the value
property or as a JavaScript Date object to the dateValue
property (only one of these properties should be used at a time):
value
property if you want to bind the DatePicker
to a model using the sap.ui.model.type.Date
value
property if the date is provided as a string from the backend or inside the app (for example, as ABAP type DATS field)dateValue
property if the date is already provided as a JavaScript Date object or you want to work with a JavaScript Date object. Use dateValue
as a helper property to easily obtain the day, month and year of the chosen date. Although possible to bind it, the recommendation is not to do it. When binding is needed, use value
property insteadAll formatting and parsing of dates from and to strings is done using the sap.ui.core.format.DateFormat. If a date is entered by typing it into the input field, it must fit to the used date format and locale.
Supported format options are pattern-based on Unicode LDML Date Format notation. See http://unicode.org/reports/tr35/#Date_Field_Symbol_Table
For example, if the valueFormat
is "yyyy-MM-dd", the displayFormat
is "MMM d, y", and the used locale is English, a valid value string is "2015-07-30", which leads to an output of "Jul 30, 2015".
If no placeholder is set to the DatePicker
, the used displayFormat
is displayed as a placeholder. If another placeholder is needed, it must be set.
Note: If the string does NOT match the displayFormat
(from user input) or the valueFormat
(on app level), the sap.ui.core.format.DateFormat makes an attempt to parse it based on the locale settings. For more information, see the respective documentation in the API Reference.
The DatePicker
is smaller in compact mode and provides a touch-friendly size in cozy mode.
On mobile devices, one tap on the input field opens the DatePicker
in full screen. To close the window, the user can select a date (which triggers the close event), or select Cancel.
Constructor for a new DatePicker
.
Accepts an object literal mSettings
that defines initial property values, aggregated and associated objects as well as event handlers. See sap.ui.base.ManagedObject#constructor for a general description of the syntax of the settings object.
new sap.m.DatePicker(sId?, mSettings?)
Param | Type | Default Value | Description |
---|---|---|---|
sId? | string | Id for the new control, generated automatically if no id is given |
|
mSettings? | object | Initial settings for the new control |
Name | Type | Default Value | Description |
---|---|---|---|
displayFormatType | string | empty string | Displays date in this given type in input field. Default value is taken from locale settings. Accepted are values of |
maxDate | object | Maximum date that can be shown and selected in the Note: If the |
|
minDate | object | Minimum date that can be shown and selected in the Note: If the |
|
secondaryCalendarType | sap.ui.core.CalendarType | If set, the days in the calendar popup are also displayed in this calendar type If not set, the dates are only displayed in the primary calendar type |
|
showCurrentDateButton | boolean | false | Determines whether there is a shortcut navigation to Today. When used in Month, Year or Year-range picker view, the calendar navigates to Day picker view. Note: The Current date button appears if the |
showFooter | boolean | false | Hides or shows the popover's footer. |
Name | Type | Default Value | Description |
---|---|---|---|
dateValue | object | Holds a reference to a JavaScript Date Object. The |
|
displayFormat | string | Determines the format, displayed in the input field. Visibility: public |
|
initialFocusedDateValue | object | Holds a reference to a JavaScript Date Object to define the initially focused date/time when the picker popup is opened. Notes:
Since: 1.54.Visibility: public |
|
valueFormat | string | Determines the format of the value property. Visibility: public |
|
editable | boolean | true | Defines whether the control can be modified by the user or not. Note: A user can tab to non-editable control, highlight it, and copy the text from it. |
enabled | boolean | true | Indicates whether the user can interact with the control or not. Note: Disabled controls cannot be focused and they are out of the tab-chain. Visibility: public |
name | string | The name to be used in the HTML code (for example, for HTML forms that send data to the server via submission). Visibility: public |
|
placeholder | string | Defines a short hint intended to aid the user with data entry when the control has no value. Visibility: public |
|
required | boolean | false | Indicates that user input is required. This property is only needed for accessibility purposes when a single relationship between the field and a label (see aggregation |
showValueStateMessage | boolean | true | Indicates whether the value state message should be shown or not. |
textAlign | sap.ui.core.TextAlign | Initial | Defines the horizontal alignment of the text that is shown inside the input field. |
textDirection | sap.ui.core.TextDirection | Inherit | Defines the text directionality of the input field, e.g. |
value | string | Defines the value of the control. Visibility: public |
|
valueState | sap.ui.core.ValueState | None | Visualizes the validation state of the control, e.g. |
valueStateText | string | Defines the text that appears in the value state message pop-up. If this is not specified, a default text is shown from the resource bundle. |
|
width | sap.ui.core.CSSSize | Defines the width of the control. Note: If the provided width is too small, the control gets stretched to its min width, which is needed in order for the control to be usable and well aligned. Visibility: public |
Default Aggregation:
Name | Cardinality | Type | Description |
---|---|---|---|
_popup | 0..1 | sap.m.ResponsivePopover |
Internal aggregation that contains the inner picker pop-up. |
specialDates | 0..n | sap.ui.core.Element |
Date Range with type to visualize special days in the Calendar. If one day is assigned to more than one Type, only the first one will be used. To set a single date (instead of a range), set only the startDate property of the sap.ui.unified.DateRange class. Note: Since 1.48 you could set a non-working day via the sap.ui.unified.CalendarDayType.NonWorking enum type just as any other special date type using sap.ui.unified.DateRangeType. |
Name | Cardinality | Type | Description |
---|---|---|---|
formattedValueStateText | 0..1 | sap.m.FormattedText |
Defines the formatted text that appears in the value state message pop-up. It can include links. If both |
Name | Cardinality | Type | Description |
---|---|---|---|
legend | 0..1 | sap.ui.core.Control |
Association to the Note The legend does not have to be rendered but must exist, and all required types must be assigned. |
Event | Description |
---|---|
change |
Fired when the input operation has finished and the value has changed. Note: Fired only when a new date is selected. If you change the month or year from the picker but not select a new date from the newly selected month/year, the value of the |
navigate |
Fired when navigating in |
Fired when the input operation has finished and the value has changed.
Note: Fired only when a new date is selected. If you change the month or year from the picker but not select a new date from the newly selected month/year, the value of the sap.m.DatePicker
won't be updated and no change event will be fired.
Param | Type | Description |
---|---|---|
oControlEvent | sap.ui.base.Event | |
getSource | sap.ui.base.EventProvider | |
getParameters | object | |
value | string |
The new value of the |
valid | boolean |
Indicator for a valid date. |
Method | Description |
---|---|
addSpecialDate |
Adds some |
attachNavigate |
Attaches event handler When called, the context of the event handler (its Fired when navigating in |
destroySpecialDates |
Destroys all the specialDates in the aggregation specialDates. |
detachNavigate |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
sap.m.DatePicker.extend |
Creates a new subclass of class sap.m.DatePicker with name
|
fireChange |
Fire event change to attached listeners. Expects following event parameters:
|
fireNavigate |
Fires event navigate to attached listeners. |
getAccessibilityInfo |
References:
|
getDateValue |
The date as JavaScript Date object. This is independent from any formatter. Note: If this property is used, the |
getDisplayFormat |
The date is displayed in the input field using this format. By default, the medium format of the used locale is used. Supported format options are pattern-based on Unicode LDML Date Format notation. http://unicode.org/reports/tr35/#Date_Field_Symbol_Table
|
getDisplayFormatType |
Gets current value of property displayFormatType. Displays date in this given type in input field. Default value is taken from locale settings. Accepted are values of Default value is |
getLegend |
ID of the element which is the current target of the association legend, or |
getMaxDate |
Gets current value of property maxDate. Maximum date that can be shown and selected in the Note: If the |
sap.m.DatePicker.getMetadata |
Returns a metadata object for class sap.m.DatePicker. |
getMinDate |
Gets current value of property minDate. Minimum date that can be shown and selected in the Note: If the |
getSecondaryCalendarType |
Gets current value of property secondaryCalendarType. If set, the days in the calendar popup are also displayed in this calendar type If not set, the dates are only displayed in the primary calendar type |
getShowCurrentDateButton |
Gets current value of property showCurrentDateButton. Determines whether there is a shortcut navigation to Today. When used in Month, Year or Year-range picker view, the calendar navigates to Day picker view. Note: The Current date button appears if the Default value is |
getShowFooter |
Gets current value of property showFooter. Hides or shows the popover's footer. Default value is |
getSpecialDates |
Gets content of aggregation specialDates. Date Range with type to visualize special days in the Calendar. If one day is assigned to more than one Type, only the first one will be used. To set a single date (instead of a range), set only the startDate property of the sap.ui.unified.DateRange class. Note: Since 1.48 you could set a non-working day via the sap.ui.unified.CalendarDayType.NonWorking enum type just as any other special date type using sap.ui.unified.DateRangeType. |
getValue |
Getter for property Returns a date as a string in the format defined in property Note: If there is no data binding, the value is expected and updated in Gregorian calendar type. (Otherwise, the type of the binding is used.) If this property is used, the |
getValueFormat |
The date string expected and returned in the Supported format options are pattern-based on Unicode LDML Date Format notation. http://unicode.org/reports/tr35/#Date_Field_Symbol_Table
For example, if the date string represents an ABAP DATS type, the format should be "yyyyMMdd". Note: If data binding on |
indexOfSpecialDate |
Checks for the provided |
insertSpecialDate |
Inserts a |
isOpen |
Checks if the picker is open |
isValidValue |
Returns if the last entered value is valid. |
removeAllSpecialDates |
Removes all the controls from the aggregation specialDates. Additionally, it unregisters them from the hosting UIArea. |
removeSpecialDate |
Removes a |
setDisplayFormat |
Sets the displayFormat of the DatePicker. |
setDisplayFormatType |
Sets a new value for property displayFormatType. Displays date in this given type in input field. Default value is taken from locale settings. Accepted are values of When called with a value of Default value is |
setLegend |
Sets the associated legend. |
setMaxDate |
Sets a new value for property maxDate. Maximum date that can be shown and selected in the Note: If the When called with a value of |
setMinDate |
Sets a new value for property minDate. Minimum date that can be shown and selected in the Note: If the When called with a value of |
setSecondaryCalendarType |
Sets a new value for property secondaryCalendarType. If set, the days in the calendar popup are also displayed in this calendar type If not set, the dates are only displayed in the primary calendar type When called with a value of |
setShowCurrentDateButton |
Sets a new value for property showCurrentDateButton. Determines whether there is a shortcut navigation to Today. When used in Month, Year or Year-range picker view, the calendar navigates to Day picker view. Note: The Current date button appears if the When called with a value of Default value is |
setShowFooter |
Sets |
setValue |
Setter for property Expects a date as a string in the format defined in property Note: If there is no data binding, the value is expected and updated in Gregorian calendar type. (Otherwise, the type of the binding is used.) If this property is used, the If Data binding using a |
setWidth |
Defines the width of the DatePicker. Default value is 100% |
Adds some specialDate
to the aggregation specialDates
.
Param | Type | DefaultValue | Description |
---|---|---|---|
oSpecialDate | sap.ui.unified.DateTypeRange |
the specialDate to add; if empty, nothing is added |
Creates a new subclass of class sap.m.DatePicker with name sClassName
and enriches it with the information contained in oClassInfo
.
oClassInfo
might contain the same kind of information as described in sap.m.DateTimeField.extend.
Param | Type | DefaultValue | Description |
---|---|---|---|
sClassName | string |
Name of the class being created |
|
oClassInfo | object |
Object literal with information about the class |
|
FNMetaImpl | function |
Constructor function for the metadata object; if not given, it defaults to the metadata implementation used by this class |
Fire event change to attached listeners.
Expects following event parameters:
string
The new value of the sap.m.DatePicker
.boolean
Indicator for a valid date.Param | Type | DefaultValue | Description |
---|---|---|---|
mArguments | object |
the arguments to pass along with the event. |
The date as JavaScript Date object. This is independent from any formatter.
Note: If this property is used, the value
property should not be changed from the caller.
The date is displayed in the input field using this format. By default, the medium format of the used locale is used.
Supported format options are pattern-based on Unicode LDML Date Format notation. http://unicode.org/reports/tr35/#Date_Field_Symbol_Table
Note: If you use data binding on the
value
property with type sap.ui.model.type.Date
this property will be ignored. The format defined in the binding will be used.
Gets current value of property displayFormatType.
Displays date in this given type in input field. Default value is taken from locale settings. Accepted are values of sap.ui.core.CalendarType
or an empty string. If no type is set, the default type of the configuration is used. Note: If data binding on value
property with type sap.ui.model.type.Date
is used, this property will be ignored.
Default value is empty string
.
Gets current value of property maxDate.
Maximum date that can be shown and selected in the DatePicker
. This must be a JavaScript date object.
Note: If the maxDate
is set to be before the minDate
, the maxDate
and the minDate
are switched before rendering.
Gets current value of property minDate.
Minimum date that can be shown and selected in the DatePicker
. This must be a JavaScript date object.
Note: If the minDate
is set to be after the maxDate
, the maxDate
and the minDate
are switched before rendering.
Gets current value of property secondaryCalendarType.
If set, the days in the calendar popup are also displayed in this calendar type If not set, the dates are only displayed in the primary calendar type
Gets current value of property showCurrentDateButton.
Determines whether there is a shortcut navigation to Today. When used in Month, Year or Year-range picker view, the calendar navigates to Day picker view.
Note: The Current date button appears if the displayFormat
property allows entering day.
Default value is false
.
Gets content of aggregation specialDates.
Date Range with type to visualize special days in the Calendar. If one day is assigned to more than one Type, only the first one will be used.
To set a single date (instead of a range), set only the startDate property of the sap.ui.unified.DateRange class.
Note: Since 1.48 you could set a non-working day via the sap.ui.unified.CalendarDayType.NonWorking enum type just as any other special date type using sap.ui.unified.DateRangeType.
Getter for property value
.
Returns a date as a string in the format defined in property valueFormat
.
Note: If there is no data binding, the value is expected and updated in Gregorian calendar type. (Otherwise, the type of the binding is used.)
If this property is used, the dateValue
property should not be changed from the caller.
The date string expected and returned in the value
property uses this format. By default the medium format of the used locale is used.
Supported format options are pattern-based on Unicode LDML Date Format notation. http://unicode.org/reports/tr35/#Date_Field_Symbol_Table
For example, if the date string represents an ABAP DATS type, the format should be "yyyyMMdd".
Note: If data binding on value
property with type sap.ui.model.type.Date
is used, this property will be ignored. The format defined in the binding will be used.
Checks for the provided sap.ui.core.Element
in the aggregation specialDates. and returns its index if found or -1 otherwise.
Param | Type | DefaultValue | Description |
---|---|---|---|
oSpecialDate | sap.ui.core.Element |
The specialDate whose index is looked for |
Inserts a specialDate
to the aggregation specialDates
.
Param | Type | DefaultValue | Description |
---|---|---|---|
oSpecialDate | sap.ui.unified.DateTypeRange |
the specialDate to insert; if empty, nothing is inserted |
|
iIndex | int |
the 0-based index the |
Removes all the controls from the aggregation specialDates.
Additionally, it unregisters them from the hosting UIArea.
Removes a specialDate
from the aggregation specialDates
.
Param | Type | DefaultValue | Description |
---|---|---|---|
oSpecialDate | sap.ui.unified.DateTypeRange |
The |
Sets the displayFormat of the DatePicker.
Param | Type | DefaultValue | Description |
---|---|---|---|
sDisplayFormat | string |
new value for |
Sets a new value for property displayFormatType.
Displays date in this given type in input field. Default value is taken from locale settings. Accepted are values of sap.ui.core.CalendarType
or an empty string. If no type is set, the default type of the configuration is used. Note: If data binding on value
property with type sap.ui.model.type.Date
is used, this property will be ignored.
When called with a value of null
or undefined
, the default value of the property will be restored.
Default value is empty string
.
Param | Type | DefaultValue | Description |
---|---|---|---|
sDisplayFormatType | string | "" |
New value for property |
Sets the associated legend.
Param | Type | DefaultValue | Description |
---|---|---|---|
oLegend | sap.ui.core.ID sap.ui.unified.CalendarLegend |
ID of an element which becomes the new target of this |
Sets a new value for property maxDate.
Maximum date that can be shown and selected in the DatePicker
. This must be a JavaScript date object.
Note: If the maxDate
is set to be before the minDate
, the maxDate
and the minDate
are switched before rendering.
When called with a value of null
or undefined
, the default value of the property will be restored.
Param | Type | DefaultValue | Description |
---|---|---|---|
oMaxDate | object |
New value for property |
Sets a new value for property minDate.
Minimum date that can be shown and selected in the DatePicker
. This must be a JavaScript date object.
Note: If the minDate
is set to be after the maxDate
, the maxDate
and the minDate
are switched before rendering.
When called with a value of null
or undefined
, the default value of the property will be restored.
Param | Type | DefaultValue | Description |
---|---|---|---|
oMinDate | object |
New value for property |
Sets a new value for property secondaryCalendarType.
If set, the days in the calendar popup are also displayed in this calendar type If not set, the dates are only displayed in the primary calendar type
When called with a value of null
or undefined
, the default value of the property will be restored.
Param | Type | DefaultValue | Description |
---|---|---|---|
sSecondaryCalendarType | sap.ui.core.CalendarType |
New value for property |
Sets a new value for property showCurrentDateButton.
Determines whether there is a shortcut navigation to Today. When used in Month, Year or Year-range picker view, the calendar navigates to Day picker view.
Note: The Current date button appears if the displayFormat
property allows entering day.
When called with a value of null
or undefined
, the default value of the property will be restored.
Default value is false
.
Param | Type | DefaultValue | Description |
---|---|---|---|
bShowCurrentDateButton | boolean | false |
New value for property |
Setter for property value
.
Expects a date as a string in the format defined in property valueFormat
.
Note: If there is no data binding, the value is expected and updated in Gregorian calendar type. (Otherwise, the type of the binding is used.)
If this property is used, the dateValue
property should not be changed from the caller.
If Data binding using a sap.ui.model.type.Date
is used, please set the formatOption
stricktParsing
to true
. This prevents unwanted automatic corrections of wrong input.
Param | Type | DefaultValue | Description |
---|---|---|---|
sValue | string |
The new value of the input. |