The SmartMultiInput
control is a wrapper for other controls that extends the sap.ui.comp.smartfield.SmartField control and supports the same settings and annotations.
It interprets OData metadata to create multi-input controls, such as sap.m.MultiInput and sap.m.MultiComboBox.
The OData entity property that is changed or displayed in the control is derived from the control's value
property. You can use the SmartMultiInput
control in two ways:
value
property is bound to a navigation property (1:N relationship).value
property is bound to an arbitrary property of the entity set that is specified in the entitySet
property.SmartMultiInput
can be retrieved using either the #getTokens or the #getValue method.<sap.ui.comp.smartmultiinput.SmartMultiInput value="{Categories/CategoryId}"/> <sap.ui.comp.smartmultiinput.SmartMultiInput entitySet="Categories" value="{CategoryId}"/>
For more details, see the samples
.
Note: Just as the rest of the sap.ui.comp library, this control supports only OData V2 (see sap.ui.model.odata.v2.ODataModel) and default models.
Constructor for a new sap.ui.comp.smartfield.SmartMultiInput
.
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.comp.smartmultiinput.SmartMultiInput(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 |
---|---|---|---|
enableODataSelect | boolean | false | Enables specific properties to be provided in the select query. Visibility: public |
requestAtLeastFields | string | empty string | Enables requestAtLeast properties to be added additionally when enableODataSelect is set to True. These are comma-separated value of fields that must be requested from the backend. Visibility: public |
supportMultiSelect | boolean | true | Enables multiple selection in value help dialog. Visibility: public |
supportRanges | boolean | false | Enables value help with conditions. Can only be used without binding context. Otherwise, has no effect. Visibility: public |
textSeparator | string | Denotes the separator between texts in the display mode. The default value is loaded from the component resource bundle. Visibility: public |
Name | Type | Default Value | Description |
---|---|---|---|
clientSideMandatoryCheck | boolean | true | Determines if the mandatory check happens on the client side Note: If the sap.ui.comp.smartfield.SmartField#value property of the Example: <Property Name="CategoryID" Type="Edm.String" Nullable="false"/> Since: 1.38.3.Visibility: public |
contextEditable | boolean | true | Notifies the control whether controls using the |
controlContext | sap.ui.comp.smartfield.ControlContextType | None | Defines the context in which the layout of the |
editable | boolean | true | Indicates whether the control is in display or edit mode. Note: The
|
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 order. Visibility: public |
entitySet | string | empty string | The name of an entity set for which the control manages values. This is an optional property. If this property is left empty, the entity set is computed by parsing the binding context path, for example, |
expandNavigationProperties | boolean | false | Indicates if entities related to navigation properties inside the metadata are requested. If set to Annotations that can have navigation properties are the following:
Note: Independent of the Note: The back-end request to expand the navigation properties is sent only if the entity to which |
fetchValueListReadOnly | boolean | true | Indicates whether the value list collection is fetched in display mode from the resource path specified in the This collection data is used to infer a descriptive text for the value of the Note: Setting this property to |
fixedValueListValidationEnabled | boolean | false | If the property is set to Note: If the property is set to Note: This property is applicable only for fixed-value scenarios. |
historyEnabled | boolean | true | If the property is set to Note: For sap.m.ComboBox and sap.m.MultiComboBox the history values are disabled by default. To enable them for these controls, you need to set the |
importance | sap.ui.comp.smartfield.Importance | Low | Specifies the importance of the field. Applicable only when the |
jsontype | sap.ui.comp.smartfield.JSONType | Data types to be used, if the |
|
mandatory | boolean | false | Indicates whether user input is required. Note: The
|
maxLength | int | 0 | Defines the highest possible number of permitted input characters that the user can enter into the text input field. Computed |
name | string | empty string | To be used in the HTML code (for example, for HTML forms that send data to the server via 'submit'). Visibility: public |
placeholder | string | empty string | Text shown when no value available. Visibility: public |
proposedControl | sap.ui.comp.smartfield.ControlProposalType | None | Proposes a control to be rendered. The |
showLabel | boolean | true | If set to |
showSuggestion | boolean | true | If set to |
showValueHelp | boolean | true | If set to |
showValueStateMessage | boolean | true | Defines whether the value state message is shown or not. Visibility: public |
textAlign | sap.ui.core.TextAlign | Initial | Horizontal alignment of the text. Visibility: public |
textDirection | sap.ui.core.TextDirection | Inherit | The available text direction options are LTR and RTL. By default, the control inherits the text direction from its parent control. The Note: The |
textInEditModeSource | sap.ui.comp.smartfield.TextInEditModeSource | None | Sets the source from which text descriptions for Note: The
Note: In addition, the
Note: As of version 1.82, if |
textLabel | string | empty string | This property contains the text of an associated |
tooltipLabel | string | empty string | This property contains the tool tip of the associated |
uomEditState | int | -1 | This property is for internal use only. |
uomEditable | boolean | true | Indicates whether the unit of measure field is in display or edit mode. Note: This control property is only valid if the
Note: The
|
uomEnabled | boolean | true | Enabled state of the unit, if the |
uomVisible | boolean | true | Indicates whether the unit of measure field is visible. Note: This control property is only valid if the
Note: The |
url | string | empty string | Contains a URL which is used to render a link. The link is rendered, if the OData property, to which the value property of the control is bound, is of type |
value | any | The binding path expression used to determine the bound Entity Data Model (EDM) property. Note: Composite binding expressions for this property are not supported. Note: Custom formatters for this property are not supported. The |
|
valueState | sap.ui.core.ValueState | None | Visualizes the validation state of the control, e.g. Note: This method is public because of an implementation side effect and should not be used for validation purposes as it may conflict with the Custom validation logic must be implemented in a custom binding type rather than in a |
valueStateText | string | empty string | Defines the text of the value state message popup. Note: This method is public because of an implementation side effect and should not be used for validation purposes as it may conflict with the Custom validation logic must be implemented in a custom binding type rather than in a |
width | sap.ui.core.CSSSize | empty string | Defines the width of the control. Visibility: public |
wrapping | boolean | true | Indicates whether the control break lines (in display mode) to prevent overflow. |
Name | Cardinality | Type | Description |
---|---|---|---|
configuration | 0..1 | sap.ui.comp.smartfield.Configuration |
Optional configuration for Note: By default, the value of the |
controlProposal | 0..1 | sap.ui.comp.smartfield.ControlProposal |
Proposes a control to be rendered. The |
semanticObjectController | 0..1 | sap.ui.comp.navpopover.SemanticObjectController |
The Semantic Object Controller allows the user to specify and overwrite functionality for semantic object navigation. |
Event | Description |
---|---|
beforeCreate |
This event is fired before the OData model's Listeners may prevent the default action of this event by calling the |
beforeRemove |
This event is fired before the OData model's Listeners may prevent the default action of this event by calling the |
selectionChange |
This event is fired when item selection is changed. It is relevant only for selection changes on |
selectionFinish |
Event is fired when user has finished a selection of items in a list box and list box has been closed. It is relevant only for selection finishes on |
tokenUpdate |
This event is fired when the tokens aggregation is changed due to a user action (add / remove token). This event is fired only for token changes in |
This event is fired before the OData model's create
method is called. Provides object with parameters of the call for editing.
Listeners may prevent the default action of this event by calling the preventDefault
method on the event object.
Param | Type | Description |
---|---|---|
oControlEvent | sap.ui.base.Event | |
getSource | sap.ui.base.EventProvider | |
getParameters | object | |
oData | object |
Data of the entry that should be created. |
mParameters | object |
Parameter map that will be passed to the OData model's |
This event is fired before the OData model's remove
method is called. Provides object with parameters of the call in key:value format for editing.
Listeners may prevent the default action of this event by calling the preventDefault
method on the event object.
Param | Type | Description |
---|---|---|
oControlEvent | sap.ui.base.Event | |
getSource | sap.ui.base.EventProvider | |
getParameters | object | |
mParameters | object |
Parameter map that will be passed to the OData model's |
This event is fired when item selection is changed. It is relevant only for selection changes on SmartMultiInput
elements with fixed values, such as sap.m.MultiComboBox.
Param | Type | Description |
---|---|---|
oControlEvent | sap.ui.base.Event | |
getSource | sap.ui.base.EventProvider | |
getParameters | object | |
changedItem | sap.ui.core.Item |
Item that was selected or deselected. |
selected | boolean |
Selection state: |
Event is fired when user has finished a selection of items in a list box and list box has been closed. It is relevant only for selection finishes on SmartMultiInput
elements with fixed values, such as sap.m.MultiComboBox.
Param | Type | Description |
---|---|---|
oControlEvent | sap.ui.base.Event | |
getSource | sap.ui.base.EventProvider | |
getParameters | object | |
selectedItems | sap.ui.core.Item[] |
The selected items which are selected after list box has been closed. |
This event is fired when the tokens aggregation is changed due to a user action (add / remove token). This event is fired only for token changes in SmartMultiInput
elements.
Param | Type | Description |
---|---|---|
oControlEvent | sap.ui.base.Event | |
getSource | sap.ui.base.EventProvider | |
getParameters | object | |
type | string |
Type of TokenUpdate event. There are two TokenUpdate types: |
addedTokens | sap.m.Token[] |
The array of tokens that are added. This parameter is used when tokenUpdate type is "added". |
removedTokens | sap.m.Token[] |
The array of tokens that are removed. This parameter is used when tokenUpdate type is "removed". |
Method | Description |
---|---|
attachBeforeCreate |
Attaches event handler When called, the context of the event handler (its This event is fired before the OData model's |
attachBeforeRemove |
Attaches event handler When called, the context of the event handler (its This event is fired before the OData model's |
attachSelectionChange |
Attaches event handler When called, the context of the event handler (its This event is fired when item selection is changed. It is relevant only for selection changes on |
attachSelectionFinish |
Attaches event handler When called, the context of the event handler (its Event is fired when user has finished a selection of items in a list box and list box has been closed. It is relevant only for selection finishes on |
attachTokenUpdate |
Attaches event handler When called, the context of the event handler (its This event is fired when the tokens aggregation is changed due to a user action (add / remove token). This event is fired only for token changes in |
checkClientError |
Checks whether a client error has been detected. In addition, this method displays an error message, if it is not already displayed. |
detachBeforeCreate |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
detachBeforeRemove |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
detachSelectionChange |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
detachSelectionFinish |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
detachTokenUpdate |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
sap.ui.comp.smartmultiinput.SmartMultiInput.extend |
Creates a new subclass of class sap.ui.comp.smartmultiinput.SmartMultiInput with name
|
fireBeforeCreate |
Fires event beforeCreate to attached listeners. Listeners may prevent the default action of this event by calling the |
fireBeforeRemove |
Fires event beforeRemove to attached listeners. Listeners may prevent the default action of this event by calling the |
fireSelectionChange |
Fires event selectionChange to attached listeners. |
fireSelectionFinish |
Fires event selectionFinish to attached listeners. |
fireTokenUpdate |
Fires event tokenUpdate to attached listeners. |
getEnableODataSelect |
Gets current value of property enableODataSelect. Enables specific properties to be provided in the select query. Default value is |
getFilter |
Returns a filter that can be applied to restrict the OData query. |
sap.ui.comp.smartmultiinput.SmartMultiInput.getMetadata |
Returns a metadata object for class sap.ui.comp.smartmultiinput.SmartMultiInput. |
getRangeData |
Returns an array of token values in range format. |
getRequestAtLeastFields |
Gets current value of property requestAtLeastFields. Enables requestAtLeast properties to be added additionally when enableODataSelect is set to True. These are comma-separated value of fields that must be requested from the backend. Default value is |
getSupportMultiSelect |
Gets current value of property supportMultiSelect. Enables multiple selection in value help dialog. Default value is |
getSupportRanges |
Gets current value of property supportRanges. Enables value help with conditions. Can only be used without binding context. Otherwise, has no effect. Default value is |
getTokens |
Returns tokens selected in |
getValue |
Returns tokens selected in |
setEnableODataSelect |
Sets a new value for property enableODataSelect. Enables specific properties to be provided in the select query. When called with a value of Default value is |
setRangeData |
Sets tokens based on given objects with range data. Can only be used without a data binding. Otherwise, has no effect. |
setRequestAtLeastFields |
Sets a new value for property requestAtLeastFields. Enables requestAtLeast properties to be added additionally when enableODataSelect is set to True. These are comma-separated value of fields that must be requested from the backend. When called with a value of Default value is |
setSupportMultiSelect |
Sets a new value for property supportMultiSelect. Enables multiple selection in value help dialog. When called with a value of Default value is |
setSupportRanges |
Sets a new value for property supportRanges. Enables value help with conditions. Can only be used without binding context. Otherwise, has no effect. When called with a value of Default value is |
setTextSeparator |
Sets a new value for property textSeparator. Denotes the separator between texts in the display mode. The default value is loaded from the component resource bundle. When called with a value of |
Attaches event handler fnFunction
to the beforeCreate event of this sap.ui.comp.smartmultiinput.SmartMultiInput
.
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.comp.smartmultiinput.SmartMultiInput
itself.
This event is fired before the OData model's create
method is called. Provides object with parameters of the call for editing.
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 |
Attaches event handler fnFunction
to the beforeRemove event of this sap.ui.comp.smartmultiinput.SmartMultiInput
.
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.comp.smartmultiinput.SmartMultiInput
itself.
This event is fired before the OData model's remove
method is called. Provides object with parameters of the call in key:value format for editing.
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 |
Attaches event handler fnFunction
to the selectionChange event of this sap.ui.comp.smartmultiinput.SmartMultiInput
.
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.comp.smartmultiinput.SmartMultiInput
itself.
This event is fired when item selection is changed. It is relevant only for selection changes on SmartMultiInput
elements with fixed values, such as sap.m.MultiComboBox.
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 |
Attaches event handler fnFunction
to the selectionFinish event of this sap.ui.comp.smartmultiinput.SmartMultiInput
.
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.comp.smartmultiinput.SmartMultiInput
itself.
Event is fired when user has finished a selection of items in a list box and list box has been closed. It is relevant only for selection finishes on SmartMultiInput
elements with fixed values, such as sap.m.MultiComboBox.
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 |
Attaches event handler fnFunction
to the tokenUpdate event of this sap.ui.comp.smartmultiinput.SmartMultiInput
.
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.comp.smartmultiinput.SmartMultiInput
itself.
This event is fired when the tokens aggregation is changed due to a user action (add / remove token). This event is fired only for token changes in SmartMultiInput
elements.
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 |
Checks whether a client error has been detected. In addition, this method displays an error message, if it is not already displayed.
Detaches event handler fnFunction
from the beforeCreate event of this sap.ui.comp.smartmultiinput.SmartMultiInput
.
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 |
Detaches event handler fnFunction
from the beforeRemove event of this sap.ui.comp.smartmultiinput.SmartMultiInput
.
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 |
Detaches event handler fnFunction
from the selectionChange event of this sap.ui.comp.smartmultiinput.SmartMultiInput
.
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 |
Detaches event handler fnFunction
from the selectionFinish event of this sap.ui.comp.smartmultiinput.SmartMultiInput
.
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 |
Detaches event handler fnFunction
from the tokenUpdate event of this sap.ui.comp.smartmultiinput.SmartMultiInput
.
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 |
Creates a new subclass of class sap.ui.comp.smartmultiinput.SmartMultiInput 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.comp.smartfield.SmartField.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 |
Fires event beforeCreate to attached listeners.
Listeners may prevent the default action of this event by calling the preventDefault
method on the event object. The return value of this method indicates whether the default action should be executed.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object |
Parameters to pass along with the event |
|
oData | object |
Data of the entry that should be created. |
|
mParameters | object |
Parameter map that will be passed to the OData model's |
Fires event beforeRemove to attached listeners.
Listeners may prevent the default action of this event by calling the preventDefault
method on the event object. The return value of this method indicates whether the default action should be executed.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object |
Parameters to pass along with the event |
|
mParameters | object |
Parameter map that will be passed to the OData model's |
Fires event selectionChange to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object |
Parameters to pass along with the event |
|
changedItem | sap.ui.core.Item |
Item that was selected or deselected. |
|
selected | boolean |
Selection state: |
Fires event selectionFinish to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object |
Parameters to pass along with the event |
|
selectedItems | sap.ui.core.Item[] |
The selected items which are selected after list box has been closed. |
Fires event tokenUpdate to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object |
Parameters to pass along with the event |
|
type | string |
Type of TokenUpdate event. There are two TokenUpdate types: |
|
addedTokens | sap.m.Token[] |
The array of tokens that are added. This parameter is used when tokenUpdate type is "added". |
|
removedTokens | sap.m.Token[] |
The array of tokens that are removed. This parameter is used when tokenUpdate type is "removed". |
Gets current value of property enableODataSelect.
Enables specific properties to be provided in the select query.
Default value is false
.
Returns a metadata object for class sap.ui.comp.smartmultiinput.SmartMultiInput.
Gets current value of property requestAtLeastFields.
Enables requestAtLeast properties to be added additionally when enableODataSelect is set to True. These are comma-separated value of fields that must be requested from the backend.
Default value is empty string
.
Gets current value of property supportMultiSelect.
Enables multiple selection in value help dialog.
Default value is true
.
Gets current value of property supportRanges.
Enables value help with conditions. Can only be used without binding context. Otherwise, has no effect.
Default value is false
.
Sets a new value for property enableODataSelect.
Enables specific properties to be provided in the select query.
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 |
---|---|---|---|
bEnableODataSelect | boolean | false |
New value for property |
Sets tokens based on given objects with range data. Can only be used without a data binding. Otherwise, has no effect.
Param | Type | DefaultValue | Description |
---|---|---|---|
vRangeData | object array |
Object or array of objects with range data. Tokens will be created based on this data and fed into the smart multi input. |
Sets a new value for property requestAtLeastFields.
Enables requestAtLeast properties to be added additionally when enableODataSelect is set to True. These are comma-separated value of fields that must be requested from the backend.
When called with a value of null
or undefined
, the default value of the property will be restored.
Default value is empty string
.
Param | Type | DefaultValue | Description |
---|---|---|---|
sRequestAtLeastFields | string | "" |
New value for property |
Sets a new value for property supportMultiSelect.
Enables multiple selection in value help dialog.
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 |
---|---|---|---|
bSupportMultiSelect | boolean | true |
New value for property |
Sets a new value for property supportRanges.
Enables value help with conditions. Can only be used without binding context. Otherwise, has no effect.
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 |
---|---|---|---|
bSupportRanges | boolean | false |
New value for property |
Sets a new value for property textSeparator.
Denotes the separator between texts in the display mode. The default value is loaded from the component resource bundle.
When called with a value of null
or undefined
, the default value of the property will be restored.
Param | Type | DefaultValue | Description |
---|---|---|---|
sTextSeparator | string |
New value for property |