class sap.m.DateTimePicker

Control sample: sap.m.DateTimePicker
Visiblity: public
UX Guidelines: Date/Time Picker
Implements:
Available since: N/A
Module: sap/m/DateTimePicker
Application Component: CA-UI5-CTR

Enables the users to select date (between 0001-01-01 and 9999-12-31) and time values in a combined input.

Overview

The DateTimePicker control consists of two parts: the input field and the date/time 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 DateTimePicker is opened (not used for the initial rendering). If the sap.ui.unified library is not loaded before the DateTimePicker is opened, it will be loaded upon opening. This could lead to CSP compliance issues and adds an additional waiting time when the DateTimePicker is opened for the first time. To prevent this, apps using the DateTimePicker should also load the sap.ui.unified library in advance.

Usage

Use this control if you need a combined date and time input control.

Don't use it if you want to use either a date or a time value. In this case, use the sap.m.DatePicker or the sap.m.TimePicker controls instead.

The user can enter a date by:

On app level, there are two options to provide a date for the DateTimePicker - 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):

Formatting

All 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-HH-mm-ss", the displayFormat is "MMM d, y, HH:mm:ss", and the used locale is English, a valid value string is "2015-07-30-10-30-15", which leads to an output of "Jul 30, 2015, 10:30:15".

If no placeholder is set to the DateTimePicker, 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.

Responsive behavior

The DateTimePicker is responsive and fully adapts to all devices. For larger screens, such as tablet or desktop, it opens as a popover. For mobile devices, it opens in full screen.

This control can be a drop target.

Constructor

Constructor for a new DateTimePicker.

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.DateTimePicker(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


Properties

Name Type Default Value Description
minutesStep int 1

Sets the minutes slider step. If the step is less than 1, it will be automatically converted back to 1. The minutes slider is populated only by multiples of the step.

Since: 1.56.

Visibility: public
secondsStep int 1

Sets the seconds slider step. If the step is less than 1, it will be automatically converted back to 1. The seconds slider is populated only by multiples of the step.

Since: 1.56.

Visibility: public

Borrowed Properties

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

Since: 1.28.6.

Visibility: public
maxDate object

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.

Visibility: public
minDate object

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.

Visibility: public
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

Since: 1.34.1.

Visibility: public
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 displayFormat property allows entering day.

Since: 1.95.

Visibility: public
showFooter boolean false

Hides or shows the popover's footer.

Since: 1.70.

Visibility: public
dateValue object

Holds a reference to a JavaScript Date Object. The value (string) property will be set according to it. Alternatively, if the value and valueFormat pair properties are supplied instead, the dateValue will be instantiated according to the parsed value. Use dateValue as a helper property to easily obtain the day, month, year, hours, minutes and seconds of the chosen date and time. Although possible to bind it, the recommendation is not to do it. When binding is needed, use value property instead.

Visibility: public
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:

  • Setting this property does not change the value property.
  • Depending on the context this property is used in (sap.m.TimePicker, sap.m.DatePicker or sap.m.DateTimePicker), it takes into account only the time part, only the date part or both parts of the JavaScript Date Object.


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.

Since: 1.12.0.

Visibility: public
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 labelFor of sap.m.Label) cannot be established (e.g. one label should label multiple fields).

Since: 1.38.4.

Visibility: public
showValueStateMessage boolean true

Indicates whether the value state message should be shown or not.

Since: 1.26.0.

Visibility: public
textAlign sap.ui.core.TextAlign Initial

Defines the horizontal alignment of the text that is shown inside the input field.

Since: 1.26.0.

Visibility: public
textDirection sap.ui.core.TextDirection Inherit

Defines the text directionality of the input field, e.g. RTL, LTR

Since: 1.28.0.

Visibility: public
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. Error, Warning, Success.

Visibility: public
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.

Since: 1.26.0.

Visibility: public
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

Borrowed Aggregations

Name Cardinality Type Description
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.

Since: 1.38.5.

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 valueStateText and formattedValueStateText are set - the latter is shown.

Since: 1.78.


Methods Overview

Method Description
sap.m.DateTimePicker.extend

Creates a new subclass of class sap.m.DateTimePicker 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.DatePicker.extend.

getAccessibilityInfo

References:

  • sap.ui.core.Control#getAccessibilityInfo

getIconSrc

Apply the correct icon to the used Date control

sap.m.DateTimePicker.getMetadata

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

getMinutesStep

Gets current value of property minutesStep.

Sets the minutes slider step. If the step is less than 1, it will be automatically converted back to 1. The minutes slider is populated only by multiples of the step.

Default value is 1.

getSecondsStep

Gets current value of property secondsStep.

Sets the seconds slider step. If the step is less than 1, it will be automatically converted back to 1. The seconds slider is populated only by multiples of the step.

Default value is 1.

setMinutesStep

Sets a new value for property minutesStep.

Sets the minutes slider step. If the step is less than 1, it will be automatically converted back to 1. The minutes slider is populated only by multiples of the step.

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

Default value is 1.

setSecondsStep

Sets a new value for property secondsStep.

Sets the seconds slider step. If the step is less than 1, it will be automatically converted back to 1. The seconds slider is populated only by multiples of the step.

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

Default value is 1.

sap.m.DateTimePicker.extend

Creates a new subclass of class sap.m.DateTimePicker 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.DatePicker.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

getAccessibilityInfo

References:

getIconSrc

Apply the correct icon to the used Date control

sap.m.DateTimePicker.getMetadata

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

getMinutesStep

Gets current value of property minutesStep.

Sets the minutes slider step. If the step is less than 1, it will be automatically converted back to 1. The minutes slider is populated only by multiples of the step.

Default value is 1.

getSecondsStep

Gets current value of property secondsStep.

Sets the seconds slider step. If the step is less than 1, it will be automatically converted back to 1. The seconds slider is populated only by multiples of the step.

Default value is 1.

setMinutesStep

Sets a new value for property minutesStep.

Sets the minutes slider step. If the step is less than 1, it will be automatically converted back to 1. The minutes slider is populated only by multiples of the step.

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

Default value is 1.

Param Type DefaultValue Description
iMinutesStep int 1

New value for property minutesStep

setSecondsStep

Sets a new value for property secondsStep.

Sets the seconds slider step. If the step is less than 1, it will be automatically converted back to 1. The seconds slider is populated only by multiples of the step.

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

Default value is 1.

Param Type DefaultValue Description
iSecondsStep int 1

New value for property secondsStep