A tokenizer is a container for Tokens. It also handles all actions associated with the tokens like adding, deleting, selecting and editing.
The tokens are stored in the tokens
aggregation. The tokenizer can determine, by setting the editable
property, whether the tokens in it are editable. Still the Token itself can determine if it is editable
. This allows you to have non-editable Tokens in an editable Tokenizer.
The tokenizer can only be used as part of MultiComboBox,MultiInput or ValueHelpDialog
Constructor for a new Tokenizer.
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.Tokenizer(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 |
---|---|---|---|
editable | boolean | true | true if tokens shall be editable otherwise false Visibility: public |
maxWidth | sap.ui.core.CSSSize | 100% | Defines the maximum width of the Tokenizer. Visibility: public |
renderMode | string | sap.m.TokenizerRenderMode.Loose | Defines the mode that the Tokenizer will use:
|
width | sap.ui.core.CSSSize | Defines the width of the Tokenizer. Visibility: public |
Default Aggregation: tokens
Name | Cardinality | Type | Description |
---|---|---|---|
_tokensInfo | 0..1 | sap.ui.core.InvisibleText |
Hidden text used for accesibility |
tokens (default) | 0..n | sap.m.Token |
the currently displayed tokens |
Name | Cardinality | Type | Description |
---|---|---|---|
ariaDescribedBy | 0..n | sap.ui.core.Control |
Association to controls / ids which describe this control (see WAI-ARIA attribute aria-describedby). |
ariaLabelledBy | 0..n | sap.ui.core.Control |
Association to controls / ids which label this control (see WAI-ARIA attribute aria-labelledby). |
Event | Description |
---|---|
tokenChange |
Fired when the tokens aggregation changed (add / remove token) |
tokenDelete |
Fired when a token is deleted by clicking icon, pressing backspace or delete button. |
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 a token is deleted by clicking icon, pressing backspace or delete button.
Since: 1.82.
Param | Type | Description |
---|---|---|
oControlEvent | sap.ui.base.Event | |
getSource | sap.ui.base.EventProvider | |
getParameters | object | |
tokens | sap.m.Token[] |
The array of tokens that are removed. |
keyCode | number |
Keycode of the key pressed for deletion (backspace or delete). |
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 |
---|---|
_togglePopup |
Toggles the popover. |
addAriaDescribedBy |
Adds some ariaDescribedBy into the association ariaDescribedBy. |
addAriaLabelledBy |
Adds some ariaLabelledBy into the association ariaLabelledBy. |
addToken |
Adds some token to the aggregation tokens. |
addValidateToken |
Function validates the given text and adds a new token if validation was successful.
Since 1.81 replaced by {@link MultiInput.prototype.addValidator}
|
addValidator |
Function adds a validation callback called before any new token gets added to the tokens aggregation.
Since 1.81 replaced by {@link MultiInput.prototype.addValidator}
|
attachTokenChange |
Attaches event handler When called, the context of the event handler (its Fired when the tokens aggregation changed (add / remove token)
Since 1.82 replaced by <code>tokenDelete</code> event.
|
attachTokenDelete |
Attaches event handler When called, the context of the event handler (its Fired when a token is deleted by clicking icon, pressing backspace or delete button. |
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)
Since 1.82 replaced by <code>tokenDelete</code> event.
|
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.82 replaced by <code>tokenDelete</code> event.
|
detachTokenDelete |
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.
Since 1.82 replaced by <code>tokenDelete</code> event.
|
sap.m.Tokenizer.extend |
Creates a new subclass of class sap.m.Tokenizer with name
|
fireTokenChange |
Fires event tokenChange to attached listeners.
Since 1.82 replaced by <code>tokenDelete</code> event.
|
fireTokenDelete |
Fires event tokenDelete to attached listeners. |
fireTokenUpdate |
Fires event tokenUpdate to attached listeners. Listeners may prevent the default action of this event by calling the
Since 1.82 replaced by <code>tokenDelete</code> event.
|
focusToken |
Forwards focus to the last token or calls callback if no tokens are left. |
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. true if tokens shall be editable otherwise false Default value is |
getHiddenTokensCount |
Gets the count of hidden tokens that will be used for the n-More indicator. If the count is 0, there is no n-More indicator shown. |
getMaxWidth |
Gets current value of property maxWidth. Defines the maximum width of the Tokenizer. Default value is |
sap.m.Tokenizer.getMetadata |
Returns a metadata object for class sap.m.Tokenizer. |
getRenderMode |
Gets current value of property renderMode. Defines the mode that the Tokenizer will use:
Default value is |
getScrollDelegate |
Function returns the internally used scroll delegate. |
getScrollWidth |
Function returns the tokens' width. |
getSelectedTokens |
Function returns all currently selected tokens. |
getTokens |
Gets content of aggregation tokens. the currently displayed tokens |
getTokensInfoId |
Gets the accessibility text aggregation id. |
getTokensPopup |
Returns N-More Popover/Dialog. |
getWidth |
Gets current value of property width. Defines the width of the Tokenizer. |
hasOneTruncatedToken |
Checks if the token is one and truncated. |
indexOfToken |
Checks for the provided |
insertToken |
Inserts a token into the aggregation tokens. |
onclick |
Handle the focus event on the control. |
removeAllAriaDescribedBy |
Removes all the controls in the association named ariaDescribedBy. |
removeAllAriaLabelledBy |
Removes all the controls in the association named ariaLabelledBy. |
removeAllTokens |
Removes all the controls from the aggregation tokens. Additionally, it unregisters them from the hosting UIArea. |
removeAllValidators |
Function removes all validation callbacks
Since 1.81 replaced by {@link MultiInput.prototype.addValidator}
|
removeAriaDescribedBy |
Removes an ariaDescribedBy from the association named ariaDescribedBy. |
removeAriaLabelledBy |
Removes an ariaLabelledBy from the association named ariaLabelledBy. |
removeToken |
Removes a token from the aggregation tokens. |
removeValidator |
Function removes a validation callback.
Since 1.81 replaced by {@link MultiInput.prototype.addValidator}
|
scrollToEnd |
Function scrolls the tokens to the end. |
scrollToStart |
Function scrolls the tokens to the start. |
selectAllTokens |
Function selects all tokens. |
setEditable |
Sets a new value for property editable. true if tokens shall be editable otherwise false When called with a value of Default value is |
setFirstTokenTruncated |
Sets the first token truncation. |
setMaxWidth |
Sets a new value for property maxWidth. Defines the maximum width of the Tokenizer. When called with a value of Default value is |
setPixelWidth |
Function sets the tokenizer's width in pixels. |
setRenderMode |
Sets a new value for property renderMode. Defines the mode that the Tokenizer will use:
When called with a value of Default value is |
setWidth |
Sets a new value for property width. Defines the width of the Tokenizer. When called with a value of |
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 |
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 |
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 |
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.Tokenizer
.
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.Tokenizer
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 tokenDelete event of this sap.m.Tokenizer
.
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.Tokenizer
itself.
Fired when a token is deleted by clicking icon, pressing backspace or delete button.
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.Tokenizer
.
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.Tokenizer
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.Tokenizer
.
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 tokenDelete event of this sap.m.Tokenizer
.
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.Tokenizer
.
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.Tokenizer 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 |
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 tokenDelete to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object |
Parameters to pass along with the event |
|
tokens | sap.m.Token[] |
The array of tokens that are removed. |
|
keyCode | number |
Keycode of the key pressed for deletion (backspace or delete). |
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". |
Returns array of IDs of the elements which are the current targets of the association ariaDescribedBy.
Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.
Gets current value of property editable.
true if tokens shall be editable otherwise false
Default value is true
.
Gets the count of hidden tokens that will be used for the n-More indicator. If the count is 0, there is no n-More indicator shown.
Gets current value of property maxWidth.
Defines the maximum width of the Tokenizer.
Default value is "100%"
.
Gets current value of property renderMode.
Defines the mode that the Tokenizer will use:
sap.m.TokenizerRenderMode.Loose
mode shows all tokens, no matter the width of the Tokenizersap.m.TokenizerRenderMode.Narrow
mode forces the Tokenizer to show only as much tokens as possible in its width and add an n-More indicatorDefault value is RenderMode.Loose
.
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 |
Handle the focus event on the control.
Param | Type | DefaultValue | Description |
---|---|---|---|
oEvent | jQuery.Event |
The occuring event |
Removes all the controls from the aggregation tokens.
Additionally, it unregisters them from the hosting UIArea.
Function removes all validation callbacks
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 |
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 |
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 |
Function selects all tokens.
Param | Type | DefaultValue | Description |
---|---|---|---|
bSelect | boolean |
[optional] true for selecting, false for deselecting |
Sets a new value for property editable.
true if tokens shall be editable otherwise false
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 |
Sets the first token truncation.
Param | Type | DefaultValue | Description |
---|---|---|---|
bValue | boolean |
The value to set |
Sets a new value for property maxWidth.
Defines the maximum width of the Tokenizer.
When called with a value of null
or undefined
, the default value of the property will be restored.
Default value is "100%"
.
Param | Type | DefaultValue | Description |
---|---|---|---|
sMaxWidth | sap.ui.core.CSSSize | "100%" |
New value for property |
Function sets the tokenizer's width in pixels.
Param | Type | DefaultValue | Description |
---|---|---|---|
nWidth | number |
The new width in pixels |
Sets a new value for property renderMode.
Defines the mode that the Tokenizer will use:
sap.m.TokenizerRenderMode.Loose
mode shows all tokens, no matter the width of the Tokenizersap.m.TokenizerRenderMode.Narrow
mode forces the Tokenizer to show only as much tokens as possible in its width and add an n-More indicatorWhen called with a value of null
or undefined
, the default value of the property will be restored.
Default value is RenderMode.Loose
.
Param | Type | DefaultValue | Description |
---|---|---|---|
sRenderMode | string | RenderMode.Loose |
New value for property |
Sets a new value for property width.
Defines the width of the Tokenizer.
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 |