class sap.m.DateRangeSelection

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

A single-field input control that enables the users to enter a localized date range (between 0001-01-01 and 9999-12-31).

Overview

The DateRangeSelection enables the users to enter a localized date range using touch, mouse, keyboard input, or by selecting a date range in the calendar. They can also navigate directly from one month or year to another.

Note: The control is not UTC aware and the selected date range starts from 00:00:00:000 of the first date and ends in 23:59:59:999 on the second date.

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

Usage

When to use?

If you need a date range and know that your user is a power user who has to input lots of data. If the keyboard is the primary device used for navigating the app, use two input fields. This allows the user to quickly jump from field to field. By selecting a date in one of the fields, the other field should recognize the information and jump to the same selection.

When not to use?

If the user's primary goal is not to select ranges or if you just want to enter a date and a time. For such cases, use the sap.m.DatePicker or sap.m.TimePicker.

The user can enter a date by:

On app level, there are two options to provide a date for the DateRangeSelection - date range as a string to the value property or JavaScript Date objects to the dateValue and secondDateValue properties (only one of these options 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 displayFormat is "MMM d, y", delimiter is "-", and the used locale is English, a valid value string is "Jul 29, 2015 - Jul 31, 2015" and it is displayed in the same way in the input field.

If no placeholder is set to the DateRangeSelection, 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 DateRangeSelection is fully responsive. It is smaller in compact mode and provides a touch-friendly size in cozy mode.

This control can be a drop target.

Constructor

Constructor for a new DateRangeSelection.

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.DateRangeSelection(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
delimiter string -

Delimiter between start and end date. Default value is "-". If no delimiter is given, the one defined for the used locale is used.

Visibility: public
from object

Start date of the range.

Visibility: public
secondDateValue object

The end date of the range 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.

Visibility: public
to object

End date of the range.

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.


Events Overview

Event Description
change

On change of date range event.

change

On change of date range event.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
value string

The new value of the sap.m.DateRangeSelection.

valid boolean

Indicator for a valid date.

from object

Current start date after change.

to object

Current end date after change.


Methods Overview

Method Description
sap.m.DateRangeSelection.extend

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

fireChange

Fire event change to attached listeners.

Expects following event parameters:

  • 'value' of type string The new value of the sap.m.DateRangeSelection.
  • 'valid' of type boolean Indicator for a valid date.
  • 'from' of type object Current start date after change.
  • 'to' of type object Current end date after change.

getAccessibilityInfo

References:

  • sap.ui.core.Control#getAccessibilityInfo

getDateValue

Getter for property dateValue.

The start date of the range 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.

getDelimiter

Gets current value of property delimiter.

Delimiter between start and end date. Default value is "-". If no delimiter is given, the one defined for the used locale is used.

Default value is '-'.

getFrom

Gets current value of property from.

Start date of the range.

Since 1.22.0 replaced by <code>dateValue</code> property of the {@link sap.m.DateTimeField}
sap.m.DateRangeSelection.getMetadata

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

getSecondDateValue

Gets current value of property secondDateValue.

The end date of the range 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.

getTo

Gets current value of property to.

End date of the range.

Since 1.22.0 replaced by <code>secondDateValue</code> property
getValue

Getter for property value.

Returns a date as a string in the format defined in property displayFormat.

Note: As the value string always used the displayFormat, it is both locale-dependent and calendar-type-dependent.

If this property is used, the dateValue property should not be changed from the caller.

getValueFormat

Getter for property valueFormat.

Note: Property valueFormat is not supported in the sap.m.DateRangeSelection control.

setDateValue

Setter for property dateValue.

The start date of the range 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.

setDelimiter

Sets a new value for property delimiter.

Delimiter between start and end date. Default value is "-". If no delimiter is given, the one defined for the used locale is used.

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

Default value is '-'.

setFrom

Sets a new value for property from.

Start date of the range.

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

Since 1.22.0 replaced by <code>dateValue</code> property of the {@link sap.m.DateTimeField}
setSecondDateValue

Sets a new value for property secondDateValue.

The end date of the range 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.

setTo

Sets a new value for property to.

End date of the range.

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

Since 1.22.0 replaced by <code>secondDateValue</code> property
setValue

Setter for property value.

Expects a date as a string in the format defined in property displayFormat.

Note: As the value string always used the displayFormat, it is both locale-dependent and calendar-type-dependent.

If this property is used, the dateValue property should not be changed from the caller.

setValueFormat

Setter for property valueFormat.

Note: Property valueFormat is not supported in the sap.m.DateRangeSelection control.

sap.m.DateRangeSelection.extend

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

fireChange

Fire event change to attached listeners.

Expects following event parameters:

Param Type DefaultValue Description
mArguments object

The arguments to pass along with the event.

getAccessibilityInfo

References:

getDateValue

Getter for property dateValue.

The start date of the range 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.

getDelimiter

Gets current value of property delimiter.

Delimiter between start and end date. Default value is "-". If no delimiter is given, the one defined for the used locale is used.

Default value is '-'.

getFrom

Gets current value of property from.

Start date of the range.

Since 1.22.0 replaced by <code>dateValue</code> property of the {@link sap.m.DateTimeField}

sap.m.DateRangeSelection.getMetadata

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

getSecondDateValue

Gets current value of property secondDateValue.

The end date of the range 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.

getTo

Gets current value of property to.

End date of the range.

Since 1.22.0 replaced by <code>secondDateValue</code> property

getValue

Getter for property value.

Returns a date as a string in the format defined in property displayFormat.

Note: As the value string always used the displayFormat, it is both locale-dependent and calendar-type-dependent.

If this property is used, the dateValue property should not be changed from the caller.

getValueFormat

Getter for property valueFormat.

Note: Property valueFormat is not supported in the sap.m.DateRangeSelection control.

setDateValue

Setter for property dateValue.

The start date of the range 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.

Param Type DefaultValue Description
oDateValue object

New value for property dateValue

setDelimiter

Sets a new value for property delimiter.

Delimiter between start and end date. Default value is "-". If no delimiter is given, the one defined for the used locale is used.

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

Default value is '-'.

Param Type DefaultValue Description
sDelimiter string '-'

New value for property delimiter

setFrom

Sets a new value for property from.

Start date of the range.

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

Since 1.22.0 replaced by <code>dateValue</code> property of the {@link sap.m.DateTimeField}
Param Type DefaultValue Description
oFrom object

New value for property from

setSecondDateValue

Sets a new value for property secondDateValue.

The end date of the range 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.

Param Type DefaultValue Description
oSecondDateValue object

New value for property secondDateValue

setTo

Sets a new value for property to.

End date of the range.

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

Since 1.22.0 replaced by <code>secondDateValue</code> property
Param Type DefaultValue Description
oTo object

New value for property to

setValue

Setter for property value.

Expects a date as a string in the format defined in property displayFormat.

Note: As the value string always used the displayFormat, it is both locale-dependent and calendar-type-dependent.

If this property is used, the dateValue property should not be changed from the caller.

Param Type DefaultValue Description
sValue string

The new value of the input.

setValueFormat

Setter for property valueFormat.

Note: Property valueFormat is not supported in the sap.m.DateRangeSelection control.

Param Type DefaultValue Description
sValueFormat string

New value for property valueFormat