class sap.ui.mdc.MultiValueField

Visiblity: restricted
UX Guidelines:
Implements: sap.ui.core.IFormContent
Available since: N/A
Module: sap/ui/mdc/MultiValueField
Application Component: CA-UI5-MDC

A MultiValueField control can hold multiple values. The values are stored as items. A MultiValueField control can be used to bind its items to data of a certain data type. Based on the data type settings, a default control is rendered by the MultiValueField control.


Constructor

Constructor for a new MultiValueField control.

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.ui.mdc.MultiValueField(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
delegate object ...see text or source

Path to the MultiValueFieldDelegate module that provides the required APIs to execute model-specific logic.
Note: Ensure that the related file can be requested (any required library has to be loaded before that).
Do not bind or modify the module. Once the required module is associated, this property might not be needed any longer.

Visibility: public

Borrowed Properties

Name Type Default Value Description
conditions object[]

Sets the conditions that represent the values of the field.

This should be bound to a ConditionModel using the corresponding fieldPath.

Note: For FilterField controls, the conditions property must be used to bind FilterField to a ConditionModel.
For example, for a FilterField control inside a FilterBar control the binding looks like this:
conditions="{$filters>/conditions/propertyPath}" with the following data:

  • $filters as the name of the condition model
  • /conditions/ as a required static part of the binding
  • propertyPath as the property name

For an Any (see sap.ui.model.FilterOperator) FilterField control, the binding looks like this:
conditions='{$filters>/conditions/navPath*/propertyPath}' with the following data:

  • $filters as the name of the condition model
  • /conditions/ as a required static part of the binding
  • navPath#42;/ as the navigation property name
  • propertyPath as the property name
Between navPath and propertyPath, */ is required.

Note: A condition must have the structure of ConditionObject.

Visibility: public
dataType string sap.ui.model.type.String

The type of data handled by the field. This type is used to parse, format, and validate the value.

Visibility: public
dataTypeConstraints object

The constraints of the type specified in dataType.

Visibility: public
dataTypeFormatOptions object

The format options of the type specified in dataType.

Visibility: public
delegate object ...see text or source

Path to FieldBaseDelegate module that provides the required APIs to execute model-specific logic.
Note: Ensure that the related file can be requested (any required library has to be loaded before that).
Do not bind or modify the module. Once the required module is associated, this property might not be needed any longer.

Since: 1.72.0.

Visibility: public
display sap.ui.mdc.enum.FieldDisplay Value

Defines whether the value and/or description of the field is shown and in what order.

Visibility: public
editMode sap.ui.mdc.enum.EditMode Editable

Determines whether the field is editable, read-only, or disabled.

Visibility: public
label string empty string

Defines the label text for the field.

This can be used by FilterBar or Form controls to create a Label control for the field.

Since: 1.62.0.

Visibility: public
maxConditions int -1

Sets the maximum amount of conditions that are allowed for this field.

The default value of -1 indicates that an unlimited amount of conditions can be defined.

Note If the data type used doesn't support multiple conditions, an error is thrown.

Visibility: public
multipleLines boolean false

If set, the Field is rendered using a multi-line control.

This property only affects types that support multiple lines.

Note If the data type used doesn't support multiple lines an error is thrown.

Visibility: public
placeholder string empty string

Defines a short hint intended to aid the user with data entry when the control has no value. If the value is null no placeholder is shown.

Note: If the rendered control doesn't support this feature, this property is ignored.

Visibility: public
required boolean false

Indicates that user input is required.

Visibility: public
showEmptyIndicator boolean false

If set, an empty Field renders an empty-indicator in display mode.

This property only takes effect if editMode is set to Display.

Note Empty means the Field holds no value. If an empty string is a valid value, the Field might show nothing, depending on the display settings and assigned description or FieldHelp.

Since: 1.85.0.

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

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

Note: If the rendered control doesn't support this feature, this property is ignored.

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

Defines the text directionality of the input field, for example RTL, LTR.

Note: If the rendered control doesn't support this feature, this property is ignored.

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

Visualizes the validation state of the control, for example Error, Warning, Success.

Note: The visualization of the ValueState property is handled by the inner rendered control. If a control is set (using content, contentEdit, or contentDisplay), this control needs to support the valueState behavior, otherwise valueState is not visualized.

Visibility: public
valueStateText string

Defines the text that appears in the value state message pop-up. If this has not specified, a default text from the resource bundle is shown.

Visibility: public
width sap.ui.core.CSSSize

Defines the width of the control.

Visibility: public
delegate object

Path to the Delegate module that provides the required APIs to execute model-specific logic.
Note: Ensure that the related file can be requested (any required library has to be loaded before that).
Do not bind or modify the module. This property can only be configured during control initialization.

Visibility: public

Aggregations

Default Aggregation: items

Name Cardinality Type Description
items (default) 0..n sap.ui.mdc.field.MultiValueFieldItem

Items of the MultiValueField control.

Borrowed Aggregations

Name Cardinality Type Description
content 0..1 sap.ui.core.Control

Optional content that can be rendered.

Note: Bind the value-holding property of the control to '$field>/conditions' using ConditionsType as type.

If the control needs to show multiple conditions, bind its aggregation to '$field>/conditions'. Bind the item controls value-holding property using ConditionType as type.

Warning: Only controls allowed in a Form are allowed to be used for this optional content. Other controls might break the layout. This means the IFormContent interface needs to be implemented by these controls.

contentDisplay 0..1 sap.ui.core.Control

Optional content to be rendered if the editMode property is set to Display.

Note: If a control is assigned to the content aggregation, this one is ignored.

Note: Bind the value-holding property of the control to '$field>/conditions' using ConditionsType as type.

If the control needs to show multiple conditions, bind its aggregation to '$field>/conditions'. Bind the item controls value-holding property using ConditionType as type.

Warning: Only controls allowed in a Form are allowed to be used for this optional content. Other controls might break the layout. This means the IFormContent interface needs to be implemented by these controls.

Since: 1.61.0.

contentEdit 0..1 sap.ui.core.Control

Optional content to be rendered if the editMode property is not set to Display.

Note: If a control is assigned to the content aggregation, this one is ignored.

Note: Bind the value-holding property of the control to '$field>/conditions' using ConditionsType as type.

If the control needs to show multiple conditions, bind its aggregation to '$field>/conditions'. Bind the item controls value-holding property using ConditionType as type.

Warning: Only controls allowed in a Form are allowed to be used for this optional content. Other controls might break the layout. This means the IFormContent interface needs to be implemented by these controls.

Since: 1.61.0.

fieldInfo 0..1 sap.ui.mdc.field.FieldInfoBase

Optional FieldInfo used for detail information. This is only active in display mode.

Note: If a special data type is defined or a content control is set, this is ignored.


Events Overview

Event Description
change

This event is fired when the items aggregation of the field is changed by user interaction.

Note This event is only triggered if the used content control has a change event.

change

This event is fired when the items aggregation of the field is changed by user interaction.

Note This event is only triggered if the used content control has a change event.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
items sap.ui.mdc.field.MultiValueFieldItem[]

The new items of the MultiValueField control.

If a FieldHelp element is assigned to the MultiValueField control, the key of the items is used as key for the FieldHelp items.

valid boolean

Flag that indicates if the entered user input is valid

promise Promise

Returns a Promise for the change. The Promise returns the items when it is resolved. If the change event is synchronous, the promise has already been resolved. If it is asynchronous, it will be resolved after the items have been updated.

The MultiValueField control should be set to busy during the parsing to prevent user input. As there might be a whole group of fields that need to be busy, this cannot be done automatically.


Methods Overview

Method Description
addItem

Adds some item to the aggregation items.

attachChange

Attaches event handler fnFunction to the change event of this sap.ui.mdc.MultiValueField.

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.ui.mdc.MultiValueField itself.

This event is fired when the items aggregation of the field is changed by user interaction.

Note This event is only triggered if the used content control has a change event.

destroyItems

Destroys all the items in the aggregation items.

detachChange

Detaches event handler fnFunction from the change event of this sap.ui.mdc.MultiValueField.

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

sap.ui.mdc.MultiValueField.extend

Creates a new subclass of class sap.ui.mdc.MultiValueField 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.mdc.field.FieldBase.extend.

fireChange

Fires event change to attached listeners.

getConditions

Gets conditions of the property conditions.

Do not use the conditions property, use the items aggregation instead.

Since Not supported, use the <code>items</code> aggregation to bind the control.
getDelegate

Gets current value of property delegate.

Path to the MultiValueFieldDelegate module that provides the required APIs to execute model-specific logic.
Note: Ensure that the related file can be requested (any required library has to be loaded before that).
Do not bind or modify the module. Once the required module is associated, this property might not be needed any longer.

Default value is ...see text or source.

getItems

Gets content of aggregation items.

Items of the MultiValueField control.

sap.ui.mdc.MultiValueField.getMetadata

Returns a metadata object for class sap.ui.mdc.MultiValueField.

indexOfItem

Checks for the provided sap.ui.mdc.field.MultiValueFieldItem in the aggregation items. and returns its index if found or -1 otherwise.

insertItem

Inserts a item into the aggregation items.

removeAllItems

Removes all the controls from the aggregation items.

Additionally, it unregisters them from the hosting UIArea.

removeItem

Removes a item from the aggregation items.

setConditions

Sets conditions to the property conditions.

Do not use the conditions property, use the items aggregation instead.

Since Not supported, use the <code>items</code> aggregation to bind the control.
setDataType

The type of data handled by the field. The type is used to parse, format, and validate the value.

Note: If the items aggregation is bound to a model using a type, this type is used. In this case the value of the dataType property is ignored.

Since Not supported, the type in the binding to the <code>items</code> aggregation is used.
setDataTypeConstraints

The constraints of the type specified in dataType.

Note: If the items aggregation is bound to a model using a type, this type is used. In this case the values of the dataType property and the dataTypeConstraints property are ignored.

Since Not supported, the type in the binding to the <code>items</code> aggregation is used.
setDataTypeFormatOptions

The format options of the type specified in dataType.

Note: If the items aggregation is bound to a model using a type, this type is used. In this case the values of the dataType property and the dataTypeFormatOptions property are ignored.

Since Not supported, the type in the binding to the <code>items</code> aggregation is used.
setDelegate

Sets a new value for property delegate.

Path to the MultiValueFieldDelegate module that provides the required APIs to execute model-specific logic.
Note: Ensure that the related file can be requested (any required library has to be loaded before that).
Do not bind or modify the module. Once the required module is associated, this property might not be needed any longer.

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

Default value is ...see text or source.

setMaxConditions

This property must not be set for the MultiValueField control.

Since Not supported, this property is not supported for the <code>MultiValueField</code> control.

addItem

Adds some item to the aggregation items.

Param Type DefaultValue Description
oItem sap.ui.mdc.field.MultiValueFieldItem

The item to add; if empty, nothing is inserted

attachChange

Attaches event handler fnFunction to the change event of this sap.ui.mdc.MultiValueField.

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.ui.mdc.MultiValueField itself.

This event is fired when the items aggregation of the field is changed by user interaction.

Note This event is only triggered if the used content control has a change event.

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.ui.mdc.MultiValueField itself

destroyItems

Destroys all the items in the aggregation items.

detachChange

Detaches event handler fnFunction from the change event of this sap.ui.mdc.MultiValueField.

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.ui.mdc.MultiValueField.extend

Creates a new subclass of class sap.ui.mdc.MultiValueField 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.mdc.field.FieldBase.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

items sap.ui.mdc.field.MultiValueFieldItem[]

The new items of the MultiValueField control.

If a FieldHelp element is assigned to the MultiValueField control, the key of the items is used as key for the FieldHelp items.

valid boolean

Flag that indicates if the entered user input is valid

promise Promise

Returns a Promise for the change. The Promise returns the items when it is resolved. If the change event is synchronous, the promise has already been resolved. If it is asynchronous, it will be resolved after the items have been updated.

The MultiValueField control should be set to busy during the parsing to prevent user input. As there might be a whole group of fields that need to be busy, this cannot be done automatically.

getConditions

Gets conditions of the property conditions.

Do not use the conditions property, use the items aggregation instead.

Since Not supported, use the <code>items</code> aggregation to bind the control.

getDelegate

Gets current value of property delegate.

Path to the MultiValueFieldDelegate module that provides the required APIs to execute model-specific logic.
Note: Ensure that the related file can be requested (any required library has to be loaded before that).
Do not bind or modify the module. Once the required module is associated, this property might not be needed any longer.

Default value is ...see text or source.

getItems

Gets content of aggregation items.

Items of the MultiValueField control.

sap.ui.mdc.MultiValueField.getMetadata

Returns a metadata object for class sap.ui.mdc.MultiValueField.

indexOfItem

Checks for the provided sap.ui.mdc.field.MultiValueFieldItem in the aggregation items. and returns its index if found or -1 otherwise.

Param Type DefaultValue Description
oItem sap.ui.mdc.field.MultiValueFieldItem

The item whose index is looked for

insertItem

Inserts a item into the aggregation items.

Param Type DefaultValue Description
oItem sap.ui.mdc.field.MultiValueFieldItem

The item to insert; if empty, nothing is inserted

iIndex int

The 0-based index the item should be inserted at; for a negative value of iIndex, the item is inserted at position 0; for a value greater than the current size of the aggregation, the item is inserted at the last position

removeAllItems

Removes all the controls from the aggregation items.

Additionally, it unregisters them from the hosting UIArea.

removeItem

Removes a item from the aggregation items.

Param Type DefaultValue Description
vItem int string sap.ui.mdc.field.MultiValueFieldItem

The item to remove or its index or id

setConditions

Sets conditions to the property conditions.

Do not use the conditions property, use the items aggregation instead.

Since Not supported, use the <code>items</code> aggregation to bind the control.
Param Type DefaultValue Description
aConditions object[]

Conditions to be set

setDataType

The type of data handled by the field. The type is used to parse, format, and validate the value.

Note: If the items aggregation is bound to a model using a type, this type is used. In this case the value of the dataType property is ignored.

Since Not supported, the type in the binding to the <code>items</code> aggregation is used.
Param Type DefaultValue Description
sDataType string

DataType to be set

setDataTypeConstraints

The constraints of the type specified in dataType.

Note: If the items aggregation is bound to a model using a type, this type is used. In this case the values of the dataType property and the dataTypeConstraints property are ignored.

Since Not supported, the type in the binding to the <code>items</code> aggregation is used.
Param Type DefaultValue Description
oDataTypeConstraints string

Constraints to be set

setDataTypeFormatOptions

The format options of the type specified in dataType.

Note: If the items aggregation is bound to a model using a type, this type is used. In this case the values of the dataType property and the dataTypeFormatOptions property are ignored.

Since Not supported, the type in the binding to the <code>items</code> aggregation is used.
Param Type DefaultValue Description
oDataTypeFormatOptions string

Format options to be set

setDelegate

Sets a new value for property delegate.

Path to the MultiValueFieldDelegate module that provides the required APIs to execute model-specific logic.
Note: Ensure that the related file can be requested (any required library has to be loaded before that).
Do not bind or modify the module. Once the required module is associated, this property might not be needed any longer.

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

Default value is ...see text or source.

Param Type DefaultValue Description
oDelegate object ...see text or source

New value for property delegate

setMaxConditions

This property must not be set for the MultiValueField control.

Since Not supported, this property is not supported for the <code>MultiValueField</code> control.
Param Type DefaultValue Description
iMaxConditions int

More than 1 condition must be allowed in MultiValueField