Class sap.m.DateRangeSelectionModule: sap/m/DateRangeSelection

extends DatePicker

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

A date range 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 range 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 DateRangeSelection. You can put a date range as a string to the property value or you can put JavaScript Date objects to the properties dateValue and secondDateValue. Only one of the properties should be used at one time, but they are synchronized internally. What property to use depends on the use case of the application.

  • Use the value property if the date range is already provided as a formatted string.
  • Use the dateValue and secondDateValue properties if the date range is already provided as JavaScript Date objects or you want to work with JavaScript Date objects.

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 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 will be displayed in the same way in the input field.

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


Since: 1.22.0.
Constructor Summary
new sap.m.DateRangeSelection(sId?, mSettings?)Constructor for a new DateRangeSelection.
Fields borrowed from class sap.m.InputBase
bShowLabelAsPlaceholder
Event Summary
change(oControlEvent)On change of date range event.
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.DateRangeSelection.extend(sClassName, oClassInfo?, FNMetaImpl?)Creates a new subclass of class sap.m.DateRangeSelection with name sClassName and enriches it with the information contained in oClassInfo.
sap.m.DateRangeSelection.getMetadata()Returns a metadata object for class sap.m.DateRangeSelection.
fireChange(mArguments?)Fire event change to attached listeners.
getAccessibilityInfo()
getDateValue()Getter for property dateValue.
getDelimiter()Gets current value of property delimiter.
getSecondDateValue()Gets current value of property secondDateValue.
getValue()Getter for property value.
getValueFormat()Getter for property valueFormat.
init()This file defines behavior for the control
setDateValue(oDateValue)Setter for property dateValue.
setDelimiter(sDelimiter)Sets a new value for property delimiter.
setSecondDateValue(oSecondDateValue)Sets a new value for property secondDateValue.
setValue(sValue)Setter for property value.
setValueFormat(sValueFormat)Setter for property valueFormat.
getFrom()Gets current value of property from.
getTo()Gets current value of property to.
setFrom(oFrom)Sets a new value for property from.
setTo(oTo)Sets a new value for property to.
Methods borrowed from class sap.m.DatePicker
addSpecialDate, destroySpecialDates, getDisplayFormat, getDisplayFormatType, getLegend, getMaxDate, getMinDate, getSecondaryCalendarType, getSpecialDates, indexOfSpecialDate, insertSpecialDate, removeAllSpecialDates, removeSpecialDate, setDisplayFormat, setDisplayFormatType, setLegend, setMaxDate, setMinDate, setSecondaryCalendarType, setWidth
Methods borrowed from class sap.m.InputBase
addAriaLabelledBy, applyFocusInfo, attachChange, bindToInputEvent, bindValue, closeValueStateMessage, detachChange, fireChangeEvent, getAriaLabelledBy, getDomRefForValueStateMessage, getEditable, getEnabled, getFocusInfo, getName, getPlaceholder, getRequired, getSelectedText, getShowValueStateMessage, getTextAlign, getTextDirection, getValueState, getValueStateText, getWidth, onChange, onValueRevertedByEscape, openValueStateMessage, removeAllAriaLabelledBy, removeAriaLabelledBy, selectText, setEditable, setEnabled, setName, setPlaceholder, setRequired, setShowValueStateMessage, setTextAlign, setTextDirection, setValueState, setValueStateText, unbindValue, updateDomValue
Methods borrowed from class sap.ui.core.Control
addStyleClass, allowTextSelection, attachBrowserEvent, attachValidateFieldGroup, checkFieldGroupIds, clone, detachBrowserEvent, detachValidateFieldGroup, fireValidateFieldGroup, getBusy, getBusyIndicatorDelay, getControlsByFieldGroupId, getFieldGroupIds, getIdForLabel, getRenderer, getVisible, hasStyleClass, invalidate, isBusy, placeAt, removeStyleClass, rerender, setBusy, setBusyIndicatorDelay, setFieldGroupIds, setVisible, toggleStyleClass, triggerValidateFieldGroup
Methods borrowed from class sap.ui.core.Element
$, addCustomData, addDependent, addEventDelegate, bindElement, data, destroy, destroyCustomData, destroyDependents, destroyLayoutData, destroyTooltip, enhanceAccessibilityState, findElements, fireEvent, focus, getCustomData, getDependents, getDomRef, getElementBinding, getFocusDomRef, getInterface, getLayoutData, getMetadata, getTooltip, getTooltip_AsString, getTooltip_Text, indexOfCustomData, indexOfDependent, insertCustomData, insertDependent, prop, removeAllCustomData, removeAllDependents, removeCustomData, removeDependent, removeEventDelegate, setLayoutData, setTooltip, toString, unbindElement
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.DateRangeSelection(sId?, mSettings?)
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 for a general description of the syntax of the settings object.

The supported settings are:

In addition, all settings applicable to the base type sap.m.DatePicker 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)
On change of date range event.
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.DateRangeSelection.
{boolean}oControlEvent.getParameters.valid Indicator for a valid date.
{object}oControlEvent.getParameters.from Current start date after change.
{object}oControlEvent.getParameters.to Current end date after change.
Method Detail
sap.m.DateRangeSelection.extend(sClassName, oClassInfo?, FNMetaImpl?): function
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.

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.DateRangeSelection.getMetadata(): sap.ui.base.Metadata
Returns a metadata object for class sap.m.DateRangeSelection.
Returns:
{sap.ui.base.Metadata} Metadata object describing this class
fireChange(mArguments?): sap.m.DateRangeSelection
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.
Parameters:
{Map}mArguments? The arguments to pass along with the event.
Returns:
{sap.m.DateRangeSelection}this to allow method chaining
getAccessibilityInfo()
See:
{sap.ui.core.Control#getAccessibilityInfo}
getDateValue(): object
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.

Returns:
{object} the value of property dateValue
getDelimiter(): string
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 -.

Returns:
{string} Value of property delimiter
getSecondDateValue(): object
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.

Returns:
{object} Value of property secondDateValue
getValue(): string
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.

Returns:
{string} the value of property value
getValueFormat(): string
Getter for property valueFormat.

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

Returns:
{string} the value of property valueFormat
init()
This file defines behavior for the control
setDateValue(oDateValue): sap.m.DatePicker
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.

Parameters:
{object}oDateValue New value for property dateValue
Returns:
{sap.m.DatePicker}this to allow method chaining.
setDelimiter(sDelimiter): sap.m.DateRangeSelection
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 -.

Parameters:
{string}sDelimiter New value for property delimiter
Returns:
{sap.m.DateRangeSelection} Reference to this in order to allow method chaining
setSecondDateValue(oSecondDateValue): sap.m.DateRangeSelection
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.

Parameters:
{object}oSecondDateValue New value for property secondDateValue
Returns:
{sap.m.DateRangeSelection} Reference to this in order to allow method chaining
setValue(sValue): sap.m.DatePicker
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.

Parameters:
{string}sValue The new value of the input.
Returns:
{sap.m.DatePicker}this to allow method chaining.
setValueFormat(sValueFormat): sap.m.DateRangeSelection
Setter for property valueFormat.

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

Parameters:
{string}sValueFormat New value for property valueFormat
Returns:
{sap.m.DateRangeSelection}this to allow method chaining
getFrom(): object
Gets current value of property from.

Start date of the range.

Deprecated:
Since version 1.22.0 Use dateValue instead.
Returns:
{object} Value of property from
getTo(): object
Gets current value of property to.

End date of the range.

Deprecated:
Since version 1.22.0 Use secondDateValue instead.
Returns:
{object} Value of property to
setFrom(oFrom): sap.m.DateRangeSelection
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.

Parameters:
{object}oFrom New value for property from
Deprecated:
Since version 1.22.0 Use dateValue instead.
Returns:
{sap.m.DateRangeSelection} Reference to this in order to allow method chaining
setTo(oTo): sap.m.DateRangeSelection
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.

Parameters:
{object}oTo New value for property to
Deprecated:
Since version 1.22.0 Use secondDateValue instead.
Returns:
{sap.m.DateRangeSelection} Reference to this in order to allow method chaining