class sap.m.DynamicDateRange

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

A control base type.

Overview

The dynamic date range is a control that offers a choice of absolute and relative dates, using different offset from the current date. The list of values offered must be defined by the application.

Usage

The control usage is recommended when:

The DynamicDateRange control supports a number of standard options: see sap.m.StandardDynamicDateRangeKeys. A custom option could be defined by using the sap.m.CustomDynamicDateOption class and appending an instance of this class into the sap.m.DynamicDateUtil options. In order for a specific option to be used its key should be added into the options property of the control. No options are added by default.

Suggestions are available when the user types in the control input field.

Responsive behavior

On mobile devices, when user taps on the DynamicDateRange input icon a full screen dialog is opened. The dialog is closed via a date time period value selection or by pressing the "Cancel" button.


Constructor

Constructor for a new DynamicDateRange.

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.DynamicDateRange(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
editable boolean true

Defines whether the control can be modified by the user or not. Note: A user can tab to the non-editable control, highlight it, and copy the text from it.

Since: 1.92.

Visibility: public
enableGroupHeaders boolean true

Disable list group headers.

Since: 1.92.

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.

Since: 1.92.

Visibility: public
formatter object

An instance of sap.m.DynamicDateFormat or a user defined format object with the corresponding formatting and parsing functionality.

Since: 1.92.

Visibility: public
name string

Defines the name of the control for the purposes of form submission.

Since: 1.92.

Visibility: public
options string[]

Array of standard and custom option keys

Since: 1.92.

Visibility: public
placeholder string

Defines a short hint intended to aid the user with data entry when the control has no value.

Since: 1.92.

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

Visibility: public
value object

Defines the control value. The object has two properties 'operator' - a string, the key of a DynamicDateOption and 'values' - an array of parameters for the same option. The control uses a special wrong-value object, when the input receives an unrecognized string - { operator: "PARSEERROR", values: [...]}

Since: 1.92.

Visibility: public
valueState sap.ui.core.ValueState None

Accepts the core enumeration ValueState.type that supports None, Error, Warning and Success. ValueState is managed internally only when validation is triggered by user interaction.

Since: 1.92.

Visibility: public
valueStateText string

Defines the text that appears in the value state message popup.

Since: 1.92.

Visibility: public
width sap.ui.core.CSSSize

Defines the width of the control.

Since: 1.92.

Visibility: public

Aggregations

Default Aggregation:

Name Cardinality Type Description
_input 0..1 sap.m.Input
_popup 0..1 sap.m.ResponsivePopover

Associations

Name Cardinality Type Description
ariaDescribedBy 0..n sap.ui.core.Control

Association to controls / IDs that describe this control (see WAI-ARIA attribute aria-describedby).

Since: 1.92.

ariaLabelledBy 0..n sap.ui.core.Control

Association to controls / IDs that label this control (see WAI-ARIA attribute aria-labelledby).

Since: 1.92.


Events Overview

Event Description
change

Is fired when the text in the input field has changed and the focus leaves the input field or the Enter key is pressed.

change

Is fired when the text in the input field has changed and the focus leaves the input field or the Enter key is pressed.

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

The current value of the control.

valid boolean

Whether the new value is valid.


Methods Overview

Method Description
addAriaDescribedBy

Adds some ariaDescribedBy into the association ariaDescribedBy.

addAriaLabelledBy

Adds some ariaLabelledBy into the association ariaLabelledBy.

addOption

Appends an option key, identifying an additional option to be used by the control.

attachChange

Attaches event handler fnFunction to the change event of this sap.m.DynamicDateRange.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.DynamicDateRange itself.

Is fired when the text in the input field has changed and the focus leaves the input field or the Enter key is pressed.

detachChange

Detaches event handler fnFunction from the change event of this sap.m.DynamicDateRange.

The passed function and listener object must match the ones used for event registration.

sap.m.DynamicDateRange.extend

Creates a new subclass of class sap.m.DynamicDateRange with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.core.Control.extend.

fireChange

Fires event change to attached listeners.

getAriaDescribedBy

Returns array of IDs of the elements which are the current targets of the association ariaDescribedBy.

getAriaLabelledBy

Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.

getEditable

Gets current value of property editable.

Defines whether the control can be modified by the user or not. Note: A user can tab to the non-editable control, highlight it, and copy the text from it.

Default value is true.

getEnabled

Gets current value of property enabled.

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.

Default value is true.

getEnableGroupHeaders

Gets current value of property enableGroupHeaders.

Disable list group headers.

Default value is true.

getFormatter

Gets current value of property formatter.

An instance of sap.m.DynamicDateFormat or a user defined format object with the corresponding formatting and parsing functionality.

sap.m.DynamicDateRange.getMetadata

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

getName

Gets current value of property name.

Defines the name of the control for the purposes of form submission.

getOptions

Gets current value of property options.

Array of standard and custom option keys

Default value is [].

getPlaceholder

Gets current value of property placeholder.

Defines a short hint intended to aid the user with data entry when the control has no value.

getRequired

Gets current value of property required.

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

Default value is false.

getValue

Gets current value of property value.

Defines the control value. The object has two properties 'operator' - a string, the key of a DynamicDateOption and 'values' - an array of parameters for the same option. The control uses a special wrong-value object, when the input receives an unrecognized string - { operator: "PARSEERROR", values: [...]}

getValueState

Gets current value of property valueState.

Accepts the core enumeration ValueState.type that supports None, Error, Warning and Success. ValueState is managed internally only when validation is triggered by user interaction.

Default value is None.

getValueStateText

Gets current value of property valueStateText.

Defines the text that appears in the value state message popup.

getWidth

Gets current value of property width.

Defines the width of the control.

open

Opens the value help dialog.

removeAllAriaDescribedBy

Removes all the controls in the association named ariaDescribedBy.

removeAllAriaLabelledBy

Removes all the controls in the association named ariaLabelledBy.

removeAriaDescribedBy

Removes an ariaDescribedBy from the association named ariaDescribedBy.

removeAriaLabelledBy

Removes an ariaLabelledBy from the association named ariaLabelledBy.

setEditable

Sets a new value for property editable.

Defines whether the control can be modified by the user or not. Note: A user can tab to the non-editable control, highlight it, and copy the text from it.

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

Default value is true.

setEnabled

Sets a new value for property enabled.

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.

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

Default value is true.

setEnableGroupHeaders

Sets a new value for property enableGroupHeaders.

Disable list group headers.

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

Default value is true.

setFormatter

Sets a new value for property formatter.

An instance of sap.m.DynamicDateFormat or a user defined format object with the corresponding formatting and parsing functionality.

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

setName

Sets a new value for property name.

Defines the name of the control for the purposes of form submission.

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

setOptions

Sets a new value for property options.

Array of standard and custom option keys

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

Default value is [].

setPlaceholder

Sets a new value for property placeholder.

Defines a short hint intended to aid the user with data entry when the control has no value.

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

setRequired

Sets a new value for property required.

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

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

Default value is false.

setValue

Sets a new value for property value.

Defines the control value. The object has two properties 'operator' - a string, the key of a DynamicDateOption and 'values' - an array of parameters for the same option. The control uses a special wrong-value object, when the input receives an unrecognized string - { operator: "PARSEERROR", values: [...]}

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

setValueState

Sets a new value for property valueState.

Accepts the core enumeration ValueState.type that supports None, Error, Warning and Success. ValueState is managed internally only when validation is triggered by user interaction.

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

Default value is None.

setValueStateText

Sets a new value for property valueStateText.

Defines the text that appears in the value state message popup.

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

setWidth

Sets a new value for property width.

Defines the width of the control.

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

addAriaDescribedBy

Adds some ariaDescribedBy into the association ariaDescribedBy.

Param Type DefaultValue Description
vAriaDescribedBy sap.ui.core.ID sap.ui.core.Control

The ariaDescribedBy to add; if empty, nothing is inserted

addAriaLabelledBy

Adds some ariaLabelledBy into the association ariaLabelledBy.

Param Type DefaultValue Description
vAriaLabelledBy sap.ui.core.ID sap.ui.core.Control

The ariaLabelledBy to add; if empty, nothing is inserted

addOption

Appends an option key, identifying an additional option to be used by the control.

Param Type DefaultValue Description
sKey string

option key

attachChange

Attaches event handler fnFunction to the change event of this sap.m.DynamicDateRange.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.DynamicDateRange itself.

Is fired when the text in the input field has changed and the focus leaves the input field or the Enter key is pressed.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.m.DynamicDateRange itself

detachChange

Detaches event handler fnFunction from the change event of this sap.m.DynamicDateRange.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

sap.m.DynamicDateRange.extend

Creates a new subclass of class sap.m.DynamicDateRange with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.core.Control.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

Fires event change to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

value object

The current value of the control.

valid boolean

Whether the new value is valid.

getAriaDescribedBy

Returns array of IDs of the elements which are the current targets of the association ariaDescribedBy.

getAriaLabelledBy

Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.

getEditable

Gets current value of property editable.

Defines whether the control can be modified by the user or not. Note: A user can tab to the non-editable control, highlight it, and copy the text from it.

Default value is true.

getEnabled

Gets current value of property enabled.

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.

Default value is true.

getEnableGroupHeaders

Gets current value of property enableGroupHeaders.

Disable list group headers.

Default value is true.

getFormatter

Gets current value of property formatter.

An instance of sap.m.DynamicDateFormat or a user defined format object with the corresponding formatting and parsing functionality.

sap.m.DynamicDateRange.getMetadata

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

getName

Gets current value of property name.

Defines the name of the control for the purposes of form submission.

getOptions

Gets current value of property options.

Array of standard and custom option keys

Default value is [].

getPlaceholder

Gets current value of property placeholder.

Defines a short hint intended to aid the user with data entry when the control has no value.

getRequired

Gets current value of property required.

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

Default value is false.

getValue

Gets current value of property value.

Defines the control value. The object has two properties 'operator' - a string, the key of a DynamicDateOption and 'values' - an array of parameters for the same option. The control uses a special wrong-value object, when the input receives an unrecognized string - { operator: "PARSEERROR", values: [...]}

getValueState

Gets current value of property valueState.

Accepts the core enumeration ValueState.type that supports None, Error, Warning and Success. ValueState is managed internally only when validation is triggered by user interaction.

Default value is None.

getValueStateText

Gets current value of property valueStateText.

Defines the text that appears in the value state message popup.

getWidth

Gets current value of property width.

Defines the width of the control.

open

Opens the value help dialog.

removeAllAriaDescribedBy

Removes all the controls in the association named ariaDescribedBy.

removeAllAriaLabelledBy

Removes all the controls in the association named ariaLabelledBy.

removeAriaDescribedBy

Removes an ariaDescribedBy from the association named ariaDescribedBy.

Param Type DefaultValue Description
vAriaDescribedBy int sap.ui.core.ID sap.ui.core.Control

The ariaDescribedBy to be removed or its index or ID

removeAriaLabelledBy

Removes an ariaLabelledBy from the association named ariaLabelledBy.

Param Type DefaultValue Description
vAriaLabelledBy int sap.ui.core.ID sap.ui.core.Control

The ariaLabelledBy to be removed or its index or ID

setEditable

Sets a new value for property editable.

Defines whether the control can be modified by the user or not. Note: A user can tab to the non-editable control, highlight it, and copy the text from it.

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

Default value is true.

Param Type DefaultValue Description
bEditable boolean true

New value for property editable

setEnabled

Sets a new value for property enabled.

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.

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

Default value is true.

Param Type DefaultValue Description
bEnabled boolean true

New value for property enabled

setEnableGroupHeaders

Sets a new value for property enableGroupHeaders.

Disable list group headers.

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

Default value is true.

Param Type DefaultValue Description
bEnableGroupHeaders boolean true

New value for property enableGroupHeaders

setFormatter

Sets a new value for property formatter.

An instance of sap.m.DynamicDateFormat or a user defined format object with the corresponding formatting and parsing functionality.

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

Param Type DefaultValue Description
oFormatter object

New value for property formatter

setName

Sets a new value for property name.

Defines the name of the control for the purposes of form submission.

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

Param Type DefaultValue Description
sName string

New value for property name

setOptions

Sets a new value for property options.

Array of standard and custom option keys

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
sOptions string[] []

New value for property options

setPlaceholder

Sets a new value for property placeholder.

Defines a short hint intended to aid the user with data entry when the control has no value.

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

Param Type DefaultValue Description
sPlaceholder string

New value for property placeholder

setRequired

Sets a new value for property required.

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

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

Default value is false.

Param Type DefaultValue Description
bRequired boolean false

New value for property required

setValue

Sets a new value for property value.

Defines the control value. The object has two properties 'operator' - a string, the key of a DynamicDateOption and 'values' - an array of parameters for the same option. The control uses a special wrong-value object, when the input receives an unrecognized string - { operator: "PARSEERROR", values: [...]}

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

Param Type DefaultValue Description
oValue object

New value for property value

setValueState

Sets a new value for property valueState.

Accepts the core enumeration ValueState.type that supports None, Error, Warning and Success. ValueState is managed internally only when validation is triggered by user interaction.

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

Default value is None.

Param Type DefaultValue Description
sValueState sap.ui.core.ValueState None

New value for property valueState

setValueStateText

Sets a new value for property valueStateText.

Defines the text that appears in the value state message popup.

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

Param Type DefaultValue Description
sValueStateText string

New value for property valueStateText

setWidth

Sets a new value for property width.

Defines the width of the control.

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

Param Type DefaultValue Description
sWidth sap.ui.core.CSSSize

New value for property width