A multi-input field allows the user to enter multiple values, which are displayed as tokens. You can enable auto-complete suggestions or value help to help the user choose the correct entry. You can define validator functions to define what token values are accepted.
Notes:
showValueHelp
property is overwritten and after initialization of the control, its value becomes truthy
.
If there are many tokens, the control shows only the last selected tokens that fit and for the others a label N-more is provided. In case the length of the last selected token is exceeding the width of the control, only a label N-Items is shown. In both cases, pressing on the label will show the tokens in a popup. On Phones:
Constructor for a new MultiInput.
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.MultiInput(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 |
---|---|---|---|
_semanticFormValue | string | empty string | Changed when tokens are changed. The value for sap.ui.core.ISemanticFormContent interface. Visibility: hidden |
enableMultiLineMode | boolean | false | If set to true, the MultiInput will be displayed in multi-line display mode. In multi-line display mode, all tokens can be fully viewed and easily edited in the MultiInput. The default value is false. Note: This property does not take effect on smartphones or when the editable property is set to false. Caution: Do not enable multi-line mode in tables and forms. |
maxTokens | int | The max number of tokens that is allowed in MultiInput. |
Name | Type | Default Value | Description |
---|---|---|---|
autocomplete | boolean | true | Specifies whether autocomplete is enabled. Works only if "showSuggestion" property is set to true. Note: The autocomplete feature is disabled on Android devices due to a OS specific issue. |
dateFormat | string | YYYY-MM-dd | Only used if type=date and no datepicker is available. The data is displayed and the user input is parsed according to this format. Note: The value property is always of the form RFC 3339 (YYYY-MM-dd). Visibility: public |
description | string | The description is a text after the input field, e.g. units of measurement, currencies. Visibility: public |
|
enableSuggestionsHighlighting | boolean | true | Specifies whether the suggestions highlighting is enabled. |
enableTableAutoPopinMode | boolean | false | Enables the |
fieldWidth | sap.ui.core.CSSSize | 50% | This property only takes effect if the description property is set. It controls the distribution of space between the input field and the description text. The default value is 50% leaving the other 50% for the description. Visibility: public |
filterSuggests | boolean | true | Defines whether to filter the provided suggestions before showing them to the user. Visibility: public |
maxLength | int | 0 | Maximum number of characters. Value '0' means the feature is switched off. This parameter is not compatible with the input type |
maxSuggestionWidth | sap.ui.core.CSSSize | If set, the value of this parameter will control the horizontal size of the suggestion list to display more data. This allows suggestion lists to be wider than the input field if there is enough space available. By default, the suggestion list is always as wide as the input field. Note: The value will be ignored if the actual width of the input field is larger than the specified parameter value. |
|
selectedKey | string | empty string | Defines the key of the selected item. Note: If duplicate keys exist, the first item matching the key is used. |
showClearIcon | boolean | false | Specifies whether clear icon is shown. Pressing the icon will clear input's value and fire the change and liveChange events. |
showSuggestion | boolean | false | If this is set to true, suggest event is fired when user types in the input. Changing the suggestItems aggregation in suggest event listener will show suggestions within a popup. When runs on phone, input will first open a dialog where the input and suggestions are shown. When runs on a tablet, the suggestions are shown in a popup next to the input. |
showTableSuggestionValueHelp | boolean | true | For tabular suggestions, this flag will show/hide the button at the end of the suggestion table that triggers the event "valueHelpRequest" when pressed. The default value is true. Note: If suggestions are not tabular or no suggestions are used, the button will not be displayed and this flag is without effect. |
showValueHelp | boolean | false | If set to true, a value help indicator will be displayed inside the control. When clicked the event "valueHelpRequest" will be fired. |
startSuggestion | int | 1 | Minimum length of the entered text in input before suggest event is fired. The default value is 1 which means the suggest event is fired after user types in input. Note: When it's set to 0, suggest event is fired when input with no text gets focus. In this case no suggestion popup will open. |
suggestionRowValidator | any | empty string | Defines the validation callback function called when a suggestion row gets selected. |
textFormatMode | sap.m.InputTextFormatMode | Value | Defines the display text format mode. |
textFormatter | any | empty string | Defines the display text formatter function. |
type | sap.m.InputType | Text | HTML type of the internal |
valueHelpIconSrc | sap.ui.core.URI | sap-icon://value-help | Set custom value help icon. |
valueHelpOnly | boolean | false | If set to true, direct text input is disabled and the control will trigger the event "valueHelpRequest" for all user interactions. The properties "showValueHelp", "editable", and "enabled" must be set to true, otherwise the property will have no effect |
valueLiveUpdate | boolean | false | Indicates when the value gets updated with the user changes: At each keystroke (true) or first when the user presses enter or tabs out (false). Note: When set to true and the value of the Input control is bound to a model, the change event becomes obsolete and will not be fired, as the value in the model will be updated each time the user provides input. In such cases, subscription to the liveChange event is more appropriate, as it corresponds to the way the underlying model gets updated. |
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 |
Default Aggregation:
Name | Cardinality | Type | Description |
---|---|---|---|
tokenizer | 0..1 | sap.m.Tokenizer |
The tokenizer which displays the tokens |
tokens | 0..n | sap.m.Token |
The currently displayed tokens |
Name | Cardinality | Type | Description |
---|---|---|---|
suggestionColumns | 0..n | sap.m.Column |
The suggestionColumns and suggestionRows are for tabular input suggestions. This aggregation allows for binding the table columns; for more details see the aggregation "suggestionRows". |
suggestionItems | 0..n | sap.ui.core.Item |
Defines the items displayed in the suggestion popup. Changing this aggregation (by calling To display suggestions with two text values, add Note: Only Note: Disabled items are not visualized in the list with the suggestions, however they can still be accessed through the aggregation. Note: If |
suggestionRows | 0..n | sap.m.ColumnListItem |
The suggestionColumns and suggestionRows are for tabular input suggestions. This aggregation allows for binding the table cells. The items of this aggregation are to be bound directly or to set in the suggest event method. Note: If |
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 |
Event | Description |
---|---|
tokenChange |
Fired when the tokens aggregation changed (add / remove token) |
tokenUpdate |
Fired when the tokens aggregation changed due to a user interaction (add / remove token) Listeners may prevent the default action of this event by calling the |
Fired when the tokens aggregation changed (add / remove token)
Param | Type | Description |
---|---|---|
oControlEvent | sap.ui.base.Event | |
getSource | sap.ui.base.EventProvider | |
getParameters | object | |
type | string |
Type of tokenChange event. There are four TokenChange types: "added", "removed", "removedAll", "tokensChanged". Use sap.m.Tokenizer.TokenChangeType.Added for "added", sap.m.Tokenizer.TokenChangeType.Removed for "removed", sap.m.Tokenizer.TokenChangeType.RemovedAll for "removedAll" and sap.m.Tokenizer.TokenChangeType.TokensChanged for "tokensChanged". |
token | sap.m.Token |
The added token or removed token. This parameter is used when tokenChange type is "added" or "removed". |
tokens | sap.m.Token[] |
The array of removed tokens. This parameter is used when tokenChange type is "removedAll". |
addedTokens | sap.m.Token[] |
The array of tokens that are added. This parameter is used when tokenChange type is "tokenChanged". |
removedTokens | sap.m.Token[] |
The array of tokens that are removed. This parameter is used when tokenChange type is "tokenChanged". |
Fired when the tokens aggregation changed due to a user interaction (add / remove token)
Listeners may prevent the default action of this event by calling the preventDefault
method on the event object.
Since: 1.46.
Param | Type | Description |
---|---|---|
oControlEvent | sap.ui.base.Event | |
getSource | sap.ui.base.EventProvider | |
getParameters | object | |
type | string |
Type of tokenChange event. There are two TokenUpdate types: "added", "removed" Use sap.m.Tokenizer.TokenUpdateType.Added for "added" and sap.m.Tokenizer.TokenUpdateType.Removed for "removed". |
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 |
---|---|
_decoratePopupInput |
Decorates Input |
addToken |
Adds some token to the aggregation tokens. |
addValidateToken |
Function validates the given text and adds a new token if validation was successful. |
addValidator |
Function adds a validation callback called before any new token gets added to the tokens aggregation. |
attachTokenChange |
Attaches event handler When called, the context of the event handler (its Fired when the tokens aggregation changed (add / remove token)
Since 1.46 Please use the new event tokenUpdate.
|
attachTokenUpdate |
Attaches event handler When called, the context of the event handler (its Fired when the tokens aggregation changed due to a user interaction (add / remove token) |
clone |
Clones the |
closeMultiLine |
Close multi-line MultiInput in multi-line mode |
destroyTokens |
Destroys all the tokens in the aggregation tokens. |
detachTokenChange |
Detaches event handler The passed function and listener object must match the ones used for event registration.
Since 1.46 Please use the new event tokenUpdate.
|
detachTokenUpdate |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
sap.m.MultiInput.extend |
Creates a new subclass of class sap.m.MultiInput with name
|
fireTokenChange |
Fires event tokenChange to attached listeners.
Since 1.46 Please use the new event tokenUpdate.
|
fireTokenUpdate |
Fires event tokenUpdate to attached listeners. Listeners may prevent the default action of this event by calling the |
getAccessibilityInfo |
References:
|
getDialogTitle |
Gets the picker header title. |
getDomRefForValueStateMessage |
Get the reference element which the message popup should dock to |
getEnableMultiLineMode |
Gets current value of property enableMultiLineMode. If set to true, the MultiInput will be displayed in multi-line display mode. In multi-line display mode, all tokens can be fully viewed and easily edited in the MultiInput. The default value is false. Note: This property does not take effect on smartphones or when the editable property is set to false. Caution: Do not enable multi-line mode in tables and forms. Default value is
Since 1.58 Replaced with N-more/N-items labels, which work in all cases.
|
getMaxTokens |
Gets current value of property maxTokens. The max number of tokens that is allowed in MultiInput. |
sap.m.MultiInput.getMetadata |
Returns a metadata object for class sap.m.MultiInput. |
getPopupAnchorDomRef |
Function returns domref which acts as reference point for the opening suggestion menu |
getTokens |
Gets content of aggregation tokens. The currently displayed tokens |
getValidators |
Function returns all validation callbacks. |
indexOfToken |
Checks for the provided |
insertToken |
Inserts a token into the aggregation tokens. |
isValueHelpOnlyOpener |
Gets the supported openers for the valueHelpOnly. |
onChange |
Overwrites the change event handler of the sap.m.InputBase. In case of added token it will not reset the value. |
onfocusin |
Focus is on MultiInput |
onsapescape |
When press ESC, deselect all tokens and all texts |
ontap |
When tap on text field, deselect all tokens |
openMultiLine |
Expand multi-line MultiInput in multi-line mode |
removeAllTokens |
Removes all the controls from the aggregation tokens. Additionally, it unregisters them from the hosting UIArea. |
removeAllValidators |
Function removes all validation callbacks. |
removeToken |
Removes a token from the aggregation tokens. |
removeValidator |
Function removes a validation callback. |
setEnableMultiLineMode |
Sets a new value for property enableMultiLineMode. If set to true, the MultiInput will be displayed in multi-line display mode. In multi-line display mode, all tokens can be fully viewed and easily edited in the MultiInput. The default value is false. Note: This property does not take effect on smartphones or when the editable property is set to false. Caution: Do not enable multi-line mode in tables and forms. When called with a value of Default value is
Since 1.58 Replaced with N-more/N-items labels, which work in all cases.
|
setMaxTokens |
Sets a new value for property maxTokens. The max number of tokens that is allowed in MultiInput. When called with a value of |
setTokens |
Function sets an array of tokens, existing tokens will get overridden |
updateInputField |
Updates the inner input field. |
Adds some token to the aggregation tokens.
Param | Type | DefaultValue | Description |
---|---|---|---|
oToken | sap.m.Token |
The token to add; if empty, nothing is inserted |
Function validates the given text and adds a new token if validation was successful.
Param | Type | DefaultValue | Description |
---|---|---|---|
oParameters | object |
Parameter bag containing the following fields: |
|
text | string |
The source text {sap.m.Token} |
|
token | object |
Suggested token |
|
suggestionObject | object |
Any object used to find the suggested token |
|
validationCallback | function |
Callback which gets called after validation has finished |
|
aValidators | function[] |
[optional] Array of all validators to be used |
Function adds a validation callback called before any new token gets added to the tokens aggregation.
Param | Type | DefaultValue | Description |
---|---|---|---|
fValidator | function |
The validation function |
Attaches event handler fnFunction
to the tokenChange event of this sap.m.MultiInput
.
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.MultiInput
itself.
Fired when the tokens aggregation changed (add / remove token)
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.m.MultiInput
.
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.MultiInput
itself.
Fired when the tokens aggregation changed due to a user interaction (add / remove token)
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 |
Detaches event handler fnFunction
from the tokenChange event of this sap.m.MultiInput
.
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.m.MultiInput
.
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.m.MultiInput 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.Input.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 tokenChange to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object |
Parameters to pass along with the event |
|
type | string |
Type of tokenChange event. There are four TokenChange types: "added", "removed", "removedAll", "tokensChanged". Use sap.m.Tokenizer.TokenChangeType.Added for "added", sap.m.Tokenizer.TokenChangeType.Removed for "removed", sap.m.Tokenizer.TokenChangeType.RemovedAll for "removedAll" and sap.m.Tokenizer.TokenChangeType.TokensChanged for "tokensChanged". |
|
token | sap.m.Token |
The added token or removed token. This parameter is used when tokenChange type is "added" or "removed". |
|
tokens | sap.m.Token[] |
The array of removed tokens. This parameter is used when tokenChange type is "removedAll". |
|
addedTokens | sap.m.Token[] |
The array of tokens that are added. This parameter is used when tokenChange type is "tokenChanged". |
|
removedTokens | sap.m.Token[] |
The array of tokens that are removed. This parameter is used when tokenChange type is "tokenChanged". |
Fires event tokenUpdate 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 |
|
type | string |
Type of tokenChange event. There are two TokenUpdate types: "added", "removed" Use sap.m.Tokenizer.TokenUpdateType.Added for "added" and sap.m.Tokenizer.TokenUpdateType.Removed for "removed". |
|
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 enableMultiLineMode.
If set to true, the MultiInput will be displayed in multi-line display mode. In multi-line display mode, all tokens can be fully viewed and easily edited in the MultiInput. The default value is false. Note: This property does not take effect on smartphones or when the editable property is set to false. Caution: Do not enable multi-line mode in tables and forms.
Default value is false
.
Gets current value of property maxTokens.
The max number of tokens that is allowed in MultiInput.
Function returns domref which acts as reference point for the opening suggestion menu
Checks for the provided sap.m.Token
in the aggregation tokens. and returns its index if found or -1 otherwise.
Param | Type | DefaultValue | Description |
---|---|---|---|
oToken | sap.m.Token |
The token whose index is looked for |
Inserts a token into the aggregation tokens.
Param | Type | DefaultValue | Description |
---|---|---|---|
oToken | sap.m.Token |
The token to insert; if empty, nothing is inserted |
|
iIndex | int |
The |
Gets the supported openers for the valueHelpOnly.
Param | Type | DefaultValue | Description |
---|---|---|---|
oTarget | HTMLElement |
The target of the event. |
Overwrites the change event handler of the sap.m.InputBase. In case of added token it will not reset the value.
Param | Type | DefaultValue | Description |
---|---|---|---|
oEvent | object |
Event object |
|
mParameters | object |
Additional event parameters to be passed in to the change event handler if * the value has changed |
|
sNewValue | string |
Passed value on change |
Focus is on MultiInput
Param | Type | DefaultValue | Description |
---|---|---|---|
oEvent | jQuery.Event |
The event object |
When press ESC, deselect all tokens and all texts
Param | Type | DefaultValue | Description |
---|---|---|---|
oEvent | jQuery.Event |
The event object |
When tap on text field, deselect all tokens
Param | Type | DefaultValue | Description |
---|---|---|---|
oEvent | jQuery.Event |
The event object |
Removes all the controls from the aggregation tokens.
Additionally, it unregisters them from the hosting UIArea.
Removes a token from the aggregation tokens.
Param | Type | DefaultValue | Description |
---|---|---|---|
vToken | int string sap.m.Token |
The token to remove or its index or id |
Function removes a validation callback.
Param | Type | DefaultValue | Description |
---|---|---|---|
fValidator | function |
The validation function |
Sets a new value for property enableMultiLineMode.
If set to true, the MultiInput will be displayed in multi-line display mode. In multi-line display mode, all tokens can be fully viewed and easily edited in the MultiInput. The default value is false. Note: This property does not take effect on smartphones or when the editable property is set to false. Caution: Do not enable multi-line mode in tables and forms.
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 |
---|---|---|---|
bEnableMultiLineMode | boolean | false |
New value for property |
Sets a new value for property maxTokens.
The max number of tokens that is allowed in MultiInput.
When called with a value of null
or undefined
, the default value of the property will be restored.
Param | Type | DefaultValue | Description |
---|---|---|---|
iMaxTokens | int |
New value for property |