class sap.m.Tokenizer

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

Overview

A tokenizer is a container for Tokens. It also handles all actions associated with the tokens like adding, deleting, selecting and editing.

Structure

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.

Usage

When to use:

The tokenizer can only be used as part of MultiComboBox,MultiInput or ValueHelpDialog


Constructor

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


Properties

Name Type Default Value Description
editable boolean true

true if tokens shall be editable otherwise false

Visibility: public
hiddenTokensCount int 0

Defines the count of hidden tokens if any. If this property is set to 0, the n-More indicator will not be shown.

Visibility: hidden
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:

  • sap.m.TokenizerRenderMode.Loose mode shows all tokens, no matter the width of the Tokenizer
  • sap.m.TokenizerRenderMode.Narrow mode forces the Tokenizer to show only as much tokens as possible in its width and add an n-More indicator

Visibility: public
width sap.ui.core.CSSSize

Defines the width of the Tokenizer.

Visibility: public

Aggregations

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


Associations

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


Events Overview

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. Once the event is fired, application is responsible for removing / destroying the token from the aggregation.

Since: 1.82.

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 preventDefault method on the event object.

Since: 1.46.

tokenChange

Fired when the tokens aggregation changed (add / remove token)

replaced by <code>tokenDelete</code> event.
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".

tokenDelete

Fired when a token is deleted by clicking icon, pressing backspace or delete button. Once the event is fired, application is responsible for removing / destroying the token from the aggregation.

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

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 preventDefault method on the event object.

Since: 1.46.

replaced by <code>tokenDelete</code> event.
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".


Methods Overview

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

Since 1.82 replaced by <code>tokenDelete</code> event.
attachTokenDelete

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. Once the event is fired, application is responsible for removing / destroying the token from the aggregation.

attachTokenUpdate

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)

Since 1.82 replaced by <code>tokenDelete</code> event.
destroyTokens

Destroys all the tokens in the aggregation tokens.

detachTokenChange

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.

Since 1.82 replaced by <code>tokenDelete</code> event.
detachTokenDelete

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.

detachTokenUpdate

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.

Since 1.82 replaced by <code>tokenDelete</code> event.
sap.m.Tokenizer.extend

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.

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 preventDefault method on the event object. The return value of this method indicates whether the default action should be executed.

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

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 "100%".

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:

  • sap.m.TokenizerRenderMode.Loose mode shows all tokens, no matter the width of the Tokenizer
  • sap.m.TokenizerRenderMode.Narrow mode forces the Tokenizer to show only as much tokens as possible in its width and add an n-More indicator

Default value is RenderMode.Loose.

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 sap.m.Token in the aggregation tokens. and returns its index if found or -1 otherwise.

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 null or undefined, the default value of the property will be restored.

Default value is true.

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 null or undefined, the default value of the property will be restored.

Default value is "100%".

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:

  • sap.m.TokenizerRenderMode.Loose mode shows all tokens, no matter the width of the Tokenizer
  • sap.m.TokenizerRenderMode.Narrow mode forces the Tokenizer to show only as much tokens as possible in its width and add an n-More indicator

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

Default value is RenderMode.Loose.

setWidth

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.

_togglePopup

Toggles the popover.

addAriaDescribedBy

Adds some ariaDescribedBy into the association ariaDescribedBy.

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

The ariaDescribedBy to add; if empty, nothing is inserted

addAriaLabelledBy

Adds some ariaLabelledBy into the association ariaLabelledBy.

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

The ariaLabelledBy to add; if empty, nothing is inserted

addToken

Adds some token to the aggregation tokens.

Param Type DefaultValue Description
oToken sap.m.Token

The token to add; if empty, nothing is inserted

addValidateToken

Function validates the given text and adds a new token if validation was successful.

Since 1.81 replaced by {@link MultiInput.prototype.addValidator}
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

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}
Param Type DefaultValue Description
fValidator function

The validation function

attachTokenChange

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)

Since 1.82 replaced by <code>tokenDelete</code> 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.m.Tokenizer itself

attachTokenDelete

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. Once the event is fired, application is responsible for removing / destroying the token from the aggregation.

Param Type DefaultValue Description
oData object

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

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

The function to be called when the event occurs

oListener object

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

attachTokenUpdate

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)

Since 1.82 replaced by <code>tokenDelete</code> 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.m.Tokenizer itself

destroyTokens

Destroys all the tokens in the aggregation tokens.

detachTokenChange

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.

Since 1.82 replaced by <code>tokenDelete</code> event.
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

detachTokenDelete

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

detachTokenUpdate

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.

Since 1.82 replaced by <code>tokenDelete</code> event.
Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

sap.m.Tokenizer.extend

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

fireTokenChange

Fires event tokenChange to attached listeners.

Since 1.82 replaced by <code>tokenDelete</code> event.
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".

fireTokenDelete

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

fireTokenUpdate

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.

Since 1.82 replaced by <code>tokenDelete</code> event.
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".

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

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 "100%".

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 RenderMode.Loose.

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

insertToken

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 0-based index the token should be inserted at; for a negative value of iIndex, the token is inserted at position 0; for a value greater than the current size of the aggregation, the token is inserted at the last position

onclick

Handle the focus event on the control.

Param Type DefaultValue Description
oEvent jQuery.Event

The occuring event

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.

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

The ariaDescribedBy to be removed or its index or ID

removeAriaLabelledBy

Removes an ariaLabelledBy from the association named ariaLabelledBy.

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

The ariaLabelledBy to be removed or its index or ID

removeToken

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

removeValidator

Function removes a validation callback.

Since 1.81 replaced by {@link MultiInput.prototype.addValidator}
Param Type DefaultValue Description
fValidator function

The validation function

scrollToEnd

Function scrolls the tokens to the end.

scrollToStart

Function scrolls the tokens to the start.

selectAllTokens

Function selects all tokens.

Param Type DefaultValue Description
bSelect boolean

[optional] true for selecting, false for deselecting

setEditable

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 editable

setFirstTokenTruncated

Sets the first token truncation.

Param Type DefaultValue Description
bValue boolean

The value to set

setMaxWidth

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 maxWidth

setPixelWidth

Function sets the tokenizer's width in pixels.

Param Type DefaultValue Description
nWidth number

The new 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 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 renderMode

setWidth

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 width