DatePicker

known direct subclasses: DateRangeSelection, DateTimePicker

This is a date input control with a calendar as date picker.

A date can be entered using a calendar that opens in a popup. Alternatively a value can be entered directly in the input field by typing it in. (This is only possible on desktop devices, on mobile devices keyboard input is not possible.) If a date is entered by typing it into the input field, it must fit to the used date format and locale. (See sap.ui.core.format.DateFormat)

There are two options to provide a date for the DatePicker. You can put a date as a string to the property value or you can put a JavaScript Date object to the property dateValue. Only one of the properties should be used at one time, but they are synchronized internally. What property you should use depends on the use case of the application:

Use the value property if you want to bind the DatePicker to a model using the sap.ui.model.type.Date.
Use the value property if the date is provided as a string from the backend or inside the application (e.g. as ABAP type DATS field).
Use the dateValue property if the date is already provided as a JavaScript Date object or you want to work with a JavaScript Date object.

All formatting and parsing of dates from and to strings is done using the sap.ui.core.format.DateFormat, so read the corresponding documentation if you need some information about this.

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 valueFormat is "yyyy-MM-dd", 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 shown as placeholder. If another placeholder is needed, it must be set.

Internally the sap.ui.unified.Calendar is used, but it is only needed if the DatePicker is opened. This means that it is not needed 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 a waiting time before a DatePicker is opened the first time. To prevent this, applications using the DatePicker should also load the sap.ui.unified library.

Since: 1.22.0.

Constructor Summary

new sap.m.DatePicker(sId?, mSettings?)Constructor for a new DatePicker.

Fields borrowed from class sap.m.InputBase

bShowLabelAsPlaceholder

Event Summary

change(oControlEvent)This event gets fired when the input operation has finished and the value has changed.

Events borrowed from class sap.ui.core.Control

validateFieldGroup

Events borrowed from class sap.ui.base.ManagedObject

formatError, modelContextChange, parseError, validationError, validationSuccess

Method Summary

sap.m.DatePicker.extend(sClassName, oClassInfo?, FNMetaImpl?)Creates a new subclass of class sap.m.DatePicker with name sClassName and enriches it with the information contained in oClassInfo.

sap.m.DatePicker.getMetadata()Returns a metadata object for class sap.m.DatePicker.

addSpecialDate(oSpecialDate)Adds some specialDate to the aggregation specialDates.

destroySpecialDates()Destroys all the specialDates in the aggregation specialDates.

fireChange(mArguments?)Fire event change to attached listeners.

getAccessibilityInfo()

getDateValue()Gets current value of property dateValue.

getDisplayFormat()Gets current value of property displayFormat.

getDisplayFormatType()Gets current value of property displayFormatType.

getLegend()ID of the element which is the current target of the association legend, or null.

getMaxDate()Gets current value of property maxDate.

getMinDate()Gets current value of property minDate.

getSecondaryCalendarType()Gets current value of property secondaryCalendarType.

getSpecialDates()Gets content of aggregation specialDates.

getValueFormat()Gets current value of property valueFormat.

indexOfSpecialDate(oSpecialDate)Checks for the provided sap.ui.core.Element in the aggregation specialDates.

insertSpecialDate(oSpecialDate, iIndex)Inserts a specialDate to the aggregation specialDates.

removeAllSpecialDates()Removes all the controls from the aggregation specialDates.

removeSpecialDate(oSpecialDate)Removes a specialDate from the aggregation specialDates.

setDateValue(oDateValue)Sets a new value for property dateValue.

setDisplayFormat(sDisplayFormat)Sets a new value for property displayFormat.

setDisplayFormatType(sDisplayFormatType)Sets a new value for property displayFormatType.

setLegend(oLegend)Sets the associated legend.

setMaxDate(oMaxDate)Sets a new value for property maxDate.

setMinDate(oMinDate)Sets a new value for property minDate.

setSecondaryCalendarType(sSecondaryCalendarType)Sets a new value for property secondaryCalendarType.

setValueFormat(sValueFormat)Sets a new value for property valueFormat.

setWidth(sWidth)Defines the width of the DatePicker.

Methods borrowed from class sap.m.InputBase

Methods borrowed from class sap.ui.core.Control

Methods borrowed from class sap.ui.core.Element

Methods borrowed from class sap.ui.base.ManagedObject

addAggregation, addAssociation, applySettings, attachFormatError, attachModelContextChange, attachParseError, attachValidationError, attachValidationSuccess, bindAggregation, bindContext, bindObject, bindProperty, destroyAggregation, detachFormatError, detachModelContextChange, detachParseError, detachValidationError, detachValidationSuccess, findAggregatedObjects, fireFormatError, fireModelContextChange, fireParseError, fireValidationError, fireValidationSuccess, getAggregation, getAssociation, getBinding, getBindingContext, getBindingInfo, getBindingPath, getEventingParent, getId, getModel, getObjectBinding, getOriginInfo, getParent, getProperty, hasModel, indexOfAggregation, insertAggregation, isBound, isInvalidateSuppressed, isTreeBinding, removeAggregation, removeAllAggregation, removeAllAssociation, removeAssociation, setAggregation, setAssociation, setBindingContext, setModel, unbindAggregation, unbindContext, unbindObject, unbindProperty, validateAggregation, validateProperty

Methods borrowed from class sap.ui.base.EventProvider

attachEvent, attachEventOnce, detachEvent, hasListeners

Constructor Detail

new sap.m.DatePicker(sId?, mSettings?)

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 for a general description of the syntax of the settings object.

The supported settings are:

Properties
- displayFormat : string
- valueFormat : string
- dateValue : object
- displayFormatType : string (default: )
- secondaryCalendarType : sap.ui.core.CalendarType
- minDate : object
- maxDate : object
Aggregations
- specialDates : sap.ui.core.Element[]

In addition, all settings applicable to the base type sap.m.InputBase can be used as well.

Parameters:

{string}	sId?	Id for the new control, generated automatically if no id is given
{object}	mSettings?	Initial settings for the new control

Event Detail

change(oControlEvent)

This event gets fired when the input operation has finished and the value has changed.

Parameters:

{sap.ui.base.Event}	oControlEvent
{sap.ui.base.EventProvider}	oControlEvent.getSource
{object}	oControlEvent.getParameters
{string}	oControlEvent.getParameters.value	The new value of the `sap.m.DatePicker` as specified by `valueFormat`.
{boolean}	oControlEvent.getParameters.valid	Indicator for a valid date.

Method Detail

sap.m.DatePicker.extend(sClassName, oClassInfo?, FNMetaImpl?): function

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.InputBase.extend.

Parameters:

{string}	sClassName	Name of the class being created
{object}	oClassInfo?	Object literal with information about the class
{function}	FNMetaImpl?	Constructor function for the metadata object; if not given, it defaults to `sap.ui.core.ElementMetadata`

Returns:

{function}

Created class / constructor function

sap.m.DatePicker.getMetadata(): sap.ui.base.Metadata

Returns a metadata object for class sap.m.DatePicker.

Returns:

{sap.ui.base.Metadata}

Metadata object describing this class

addSpecialDate(oSpecialDate): sap.m.DatePicker

Adds some specialDate to the aggregation specialDates.

Parameters:

{sap.ui.unified.DateTypeRange}

oSpecialDate

the specialDate to add; if empty, nothing is added

Since:: 1.38.5

Returns:

{sap.m.DatePicker} Reference to this in order to allow method chaining

destroySpecialDates(): sap.m.DatePicker

Destroys all the specialDates in the aggregation specialDates.

Since:: 1.38.5

Returns:

{sap.m.DatePicker} Reference to this in order to allow method chaining

fireChange(mArguments?): sap.m.DatePicker

Fire event change to attached listeners.

Expects following event parameters:

'value' of type string The new value of the sap.m.DatePicker.
'valid' of type boolean Indicator for a valid date.

Parameters:

{Map}

mArguments?

the arguments to pass along with the event.

Returns:

{sap.m.DatePicker} this to allow method chaining

getAccessibilityInfo()

See:

{sap.ui.core.Control#getAccessibilityInfo}

getDateValue(): object

Gets current value of property dateValue.

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.

Returns:

{object} Value of property dateValue

getDisplayFormat(): string

Gets current value of property displayFormat.

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_TableNote: 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.

Returns:

{string} Value of property displayFormat

getDisplayFormatType(): string

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 .

Since:: 1.28.6

Returns:

{string} Value of property displayFormatType

getLegend(): sap.ui.core.Control

ID of the element which is the current target of the association legend, or null.

Since:: 1.38.5

Returns:

{sap.ui.core.Control}

getMaxDate(): object

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.

Since:: 1.38.0

Returns:

{object} Value of property maxDate

getMinDate(): object

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.

Since:: 1.38.0

Returns:

{object} Value of property minDate

getSecondaryCalendarType(): sap.ui.core.CalendarType

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

Since:: 1.34.1

Returns:

{sap.ui.core.CalendarType} Value of property secondaryCalendarType

getSpecialDates(): sap.ui.core.Element[]

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.

Since:: 1.38.5

Returns:

{sap.ui.core.Element[]}

getValueFormat(): string

Gets current value of property valueFormat.

The date string expected and returned in the value property uses this format. By default the short 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.

Returns:

{string} Value of property valueFormat

indexOfSpecialDate(oSpecialDate): int

Checks for the provided sap.ui.core.Element in the aggregation specialDates. and returns its index if found or -1 otherwise.

Parameters:

{sap.ui.core.Element}

oSpecialDate

The specialDate whose index is looked for

Since:: 1.38.5

Returns:

{int}

The index of the provided control in the aggregation if found, or -1 otherwise

insertSpecialDate(oSpecialDate, iIndex): sap.m.DatePicker

Inserts a specialDate to the aggregation specialDates.

Parameters:

{sap.ui.unified.DateTypeRange}	oSpecialDate	the specialDate to insert; if empty, nothing is inserted
{int}	iIndex	the 0-based index the `specialDate` should be inserted at; for a negative value of `iIndex`, the `specialDate` is inserted at position 0; for a value greater than the current size of the aggregation, the `specialDate` is inserted at the last position

Since:: 1.38.5

Returns:

{sap.m.DatePicker} Reference to this in order to allow method chaining

removeAllSpecialDates(): sap.ui.core.Element[]

Removes all the controls from the aggregation specialDates.

Additionally, it unregisters them from the hosting UIArea.

Since:: 1.38.5

Returns:

{sap.ui.core.Element[]}

An array of the removed elements (might be empty)

removeSpecialDate(oSpecialDate): sap.ui.unified.DateTypeRange

Removes a specialDate from the aggregation specialDates.

Parameters:

{sap.ui.unified.DateTypeRange} oSpecialDate The specialDate to remove or its index or id

Since:: 1.38.5

Returns:

{sap.ui.unified.DateTypeRange} The removed specialDate or null

setDateValue(oDateValue): sap.m.DatePicker

Sets a new value for property dateValue.

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.

When called with a value of null or undefined, the default value of the property will be restored.

Parameters:

{object} oDateValue New value for property dateValue

Returns:

{sap.m.DatePicker} Reference to this in order to allow method chaining

setDisplayFormat(sDisplayFormat): sap.m.DatePicker

Sets a new value for property displayFormat.

The date is displayed in the input field using this format. By default, the medium format of the used locale is used.

When called with a value of null or undefined, the default value of the property will be restored.

Parameters:

{string} sDisplayFormat New value for property displayFormat

Returns:

{sap.m.DatePicker} Reference to this in order to allow method chaining

setDisplayFormatType(sDisplayFormatType): sap.m.DatePicker

Sets a new value for property displayFormatType.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is .

Parameters:

{string} sDisplayFormatType New value for property displayFormatType

Since:: 1.28.6

Returns:

{sap.m.DatePicker} Reference to this in order to allow method chaining

setLegend(oLegend): sap.m.DatePicker

Sets the associated legend.

Parameters:

{sap.ui.core.ID|sap.ui.unified.CalendarLegend} oLegend ID of an element which becomes the new target of this legend association; alternatively, an element instance may be given

Since:: 1.38.5

Returns:

{sap.m.DatePicker} Reference to this in order to allow method chaining

setMaxDate(oMaxDate): sap.m.DatePicker

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.

Parameters:

{object} oMaxDate New value for property maxDate

Since:: 1.38.0

Returns:

{sap.m.DatePicker} Reference to this in order to allow method chaining

setMinDate(oMinDate): sap.m.DatePicker

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.

Parameters:

{object} oMinDate New value for property minDate

Since:: 1.38.0

Returns:

{sap.m.DatePicker} Reference to this in order to allow method chaining

setSecondaryCalendarType(sSecondaryCalendarType): sap.m.DatePicker

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.

Parameters:

{sap.ui.core.CalendarType} sSecondaryCalendarType New value for property secondaryCalendarType

Since:: 1.34.1

Returns:

{sap.m.DatePicker} Reference to this in order to allow method chaining

setValueFormat(sValueFormat): sap.m.DatePicker

Sets a new value for property valueFormat.

The date string expected and returned in the value property uses this format. By default the short 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.

When called with a value of null or undefined, the default value of the property will be restored.

Parameters:

{string} sValueFormat New value for property valueFormat

Returns:

{sap.m.DatePicker} Reference to this in order to allow method chaining

setWidth(sWidth): sap.m.DatePicker

Defines the width of the DatePicker. Default value is 100%

Parameters:

{string} sWidth new value for width

Returns:

{sap.m.DatePicker} this to allow method chaining