A single-field input control that enables the users to enter a localized date range (between 0001-01-01 and 9999-12-31).
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.
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):
value
property if the date range is already provided as a formatted stringdateValue
and secondDateValue
properties if the date range is already provided as JavaScript Date objects or you want to work with JavaScript Date objectsAll 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.
The DateRangeSelection
is fully responsive. It is smaller in compact mode and provides a touch-friendly size in cozy mode.
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 |
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 |
|
to | object | End date of the range. Visibility: public |
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. |
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 |
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. |
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 |
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 |
valid | boolean |
Indicator for a valid date. |
from | object |
Current start date after change. |
to | object |
Current end date after change. |
Method | Description |
---|---|
sap.m.DateRangeSelection.extend |
Creates a new subclass of class sap.m.DateRangeSelection with name
|
fireChange |
Fire event change to attached listeners. Expects following event parameters:
|
getAccessibilityInfo |
References:
|
getDateValue |
Getter for property The start date of the range as JavaScript Date object. This is independent from any formatter. Note: If this property is used, the |
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 |
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 Returns a date as a string in the format defined in property Note: As the value string always used the If this property is used, the |
getValueFormat |
Getter for property Note: Property |
setDateValue |
Setter for property The start date of the range as JavaScript Date object. This is independent from any formatter. Note: If this property is used, the |
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 Default value is |
setFrom |
Sets a new value for property from. Start date of the range. When called with a value of
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 When called with a value of |
setTo |
Sets a new value for property to. End date of the range. When called with a value of
Since 1.22.0 replaced by <code>secondDateValue</code> property
|
setValue |
Setter for property Expects a date as a string in the format defined in property Note: As the value string always used the If this property is used, the |
setValueFormat |
Setter for property Note: Property |
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 |
Fire event change to attached listeners.
Expects following event parameters:
string
The new value of the sap.m.DateRangeSelection
.boolean
Indicator for a valid date.object
Current start date after change.object
Current end date after change.Param | Type | DefaultValue | Description |
---|---|---|---|
mArguments | object |
The arguments to pass along with the event. |
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.
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 '-'
.
Gets current value of property from.
Start date of the range.
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.
Gets current value of property to.
End date of the range.
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.
Getter for property valueFormat
.
Note: Property valueFormat
is not supported in the sap.m.DateRangeSelection
control.
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 |
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 |
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.
Param | Type | DefaultValue | Description |
---|---|---|---|
oFrom | object |
New value for property |
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 |
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.
Param | Type | DefaultValue | Description |
---|---|---|---|
oTo | object |
New value for property |
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. |