class sap.m.Token

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

Overview

Tokens are small items of information (similar to tags) that mainly serve to visualize previously selected items. Tokens are manipulated by a Tokenizer.

Structure

The tokens store single text items or sometimes key-value pairs, such as "John Miller (ID1234567)". Each token also contains a delete icon, which is invisible if the token is in edit mode.

Usage

When to use:

Tokens can only be used with the Tokenizer as a container.


Constructor

Constructor for a new Token.

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.Token(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

Indicates the editable status of the token. If it is set to true, token displays a delete icon.

Visibility: public
editableParent boolean true

Indicates the editable status of the token's parent (Tokenizer). If it is set to true, the ARIA attributes of the token are updated accordingly.

Visibility: hidden
key string empty string

Key of the token.

Visibility: public
posinset int

Indicates the position of a token. Used for aria attributes.

Visibility: hidden
selected boolean false

Indicates the current selection status of the token.

Visibility: public
setsize int

Indicates the count of the token. Used for aria attributes.

Visibility: hidden
text string empty string

Displayed text of the token.

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

This property specifies the text directionality with enumerated options. By default, the control inherits text direction from the DOM.

Since: 1.28.0.

Visibility: public
truncated boolean false

Indicates if the token's text should be truncated.

Visibility: hidden

Aggregations

Default Aggregation:

Name Cardinality Type Description
deleteIcon 0..1 sap.ui.core.Icon

The delete icon.


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
delete

This event is fired if the user clicks the token's delete icon.

This event bubbles up the control hierarchy.

deselect

This event is fired when the token gets deselected.

press

This event is fired when the user clicks on the token.

select

This event is fired when the token gets selected.

delete

This event is fired if the user clicks the token's delete icon.

This event bubbles up the control hierarchy.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object

deselect

This event is fired when the token gets deselected.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object

press

This event is fired when the user clicks on the token.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object

select

This event is fired when the token gets selected.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object

Methods Overview

Method Description
addAriaDescribedBy

Adds some ariaDescribedBy into the association ariaDescribedBy.

addAriaLabelledBy

Adds some ariaLabelledBy into the association ariaLabelledBy.

attachDelete

Attaches event handler fnFunction to the delete event of this sap.m.Token.

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.Token itself.

This event is fired if the user clicks the token's delete icon.

attachDeselect

Attaches event handler fnFunction to the deselect event of this sap.m.Token.

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.Token itself.

This event is fired when the token gets deselected.

attachPress

Attaches event handler fnFunction to the press event of this sap.m.Token.

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.Token itself.

This event is fired when the user clicks on the token.

attachSelect

Attaches event handler fnFunction to the select event of this sap.m.Token.

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.Token itself.

This event is fired when the token gets selected.

detachDelete

Detaches event handler fnFunction from the delete event of this sap.m.Token.

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

detachDeselect

Detaches event handler fnFunction from the deselect event of this sap.m.Token.

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

detachPress

Detaches event handler fnFunction from the press event of this sap.m.Token.

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

detachSelect

Detaches event handler fnFunction from the select event of this sap.m.Token.

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

sap.m.Token.extend

Creates a new subclass of class sap.m.Token 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.

fireDelete

Fires event delete to attached listeners.

fireDeselect

Fires event deselect to attached listeners.

firePress

Fires event press to attached listeners.

fireSelect

Fires event select to attached listeners.

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.

Indicates the editable status of the token. If it is set to true, token displays a delete icon.

Default value is true.

getKey

Gets current value of property key.

Key of the token.

Default value is empty string.

sap.m.Token.getMetadata

Returns a metadata object for class sap.m.Token.

getSelected

Gets current value of property selected.

Indicates the current selection status of the token.

Default value is false.

getText

Gets current value of property text.

Displayed text of the token.

Default value is empty string.

getTextDirection

Gets current value of property textDirection.

This property specifies the text directionality with enumerated options. By default, the control inherits text direction from the DOM.

Default value is Inherit.

getTruncated

Returns the value of Token's truncated property.

removeAllAriaDescribedBy

Removes all the controls in the association named ariaDescribedBy.

removeAllAriaLabelledBy

Removes all the controls in the association named ariaLabelledBy.

removeAriaDescribedBy

Removes an ariaDescribedBy from the association named ariaDescribedBy.

removeAriaLabelledBy

Removes an ariaLabelledBy from the association named ariaLabelledBy.

setEditable

Sets a new value for property editable.

Indicates the editable status of the token. If it is set to true, token displays a delete icon.

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

Default value is true.

setKey

Sets a new value for property key.

Key of the token.

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

Default value is empty string.

setSelected

Sets a new value for property selected.

Indicates the current selection status of the token.

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

Default value is false.

setText

Sets a new value for property text.

Displayed text of the token.

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

Default value is empty string.

setTextDirection

Sets a new value for property textDirection.

This property specifies the text directionality with enumerated options. By default, the control inherits text direction from the DOM.

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

Default value is Inherit.

setTruncated

Sets the Token's truncated property.

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

attachDelete

Attaches event handler fnFunction to the delete event of this sap.m.Token.

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.Token itself.

This event is fired if the user clicks the token's delete icon.

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.Token itself

attachDeselect

Attaches event handler fnFunction to the deselect event of this sap.m.Token.

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.Token itself.

This event is fired when the token gets deselected.

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.Token itself

attachPress

Attaches event handler fnFunction to the press event of this sap.m.Token.

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.Token itself.

This event is fired when the user clicks on the 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 sap.m.Token itself

attachSelect

Attaches event handler fnFunction to the select event of this sap.m.Token.

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.Token itself.

This event is fired when the token gets selected.

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.Token itself

detachDelete

Detaches event handler fnFunction from the delete event of this sap.m.Token.

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

detachDeselect

Detaches event handler fnFunction from the deselect event of this sap.m.Token.

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

detachPress

Detaches event handler fnFunction from the press event of this sap.m.Token.

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

detachSelect

Detaches event handler fnFunction from the select event of this sap.m.Token.

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

Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

sap.m.Token.extend

Creates a new subclass of class sap.m.Token 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

fireDelete

Fires event delete to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

fireDeselect

Fires event deselect to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

firePress

Fires event press to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

fireSelect

Fires event select to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

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.

Indicates the editable status of the token. If it is set to true, token displays a delete icon.

Default value is true.

getKey

Gets current value of property key.

Key of the token.

Default value is empty string.

sap.m.Token.getMetadata

Returns a metadata object for class sap.m.Token.

getSelected

Gets current value of property selected.

Indicates the current selection status of the token.

Default value is false.

getText

Gets current value of property text.

Displayed text of the token.

Default value is empty string.

getTextDirection

Gets current value of property textDirection.

This property specifies the text directionality with enumerated options. By default, the control inherits text direction from the DOM.

Default value is Inherit.

getTruncated

Returns the value of Token's truncated property.

removeAllAriaDescribedBy

Removes all the controls in the association named ariaDescribedBy.

removeAllAriaLabelledBy

Removes all the controls in the association named ariaLabelledBy.

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

setEditable

Sets a new value for property editable.

Indicates the editable status of the token. If it is set to true, token displays a delete icon.

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

setKey

Sets a new value for property key.

Key of the token.

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
sKey string ""

New value for property key

setSelected

Sets a new value for property selected.

Indicates the current selection status of the token.

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
bSelected boolean false

New value for property selected

setText

Sets a new value for property text.

Displayed text of the token.

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
sText string ""

New value for property text

setTextDirection

Sets a new value for property textDirection.

This property specifies the text directionality with enumerated options. By default, the control inherits text direction from the DOM.

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

Default value is Inherit.

Param Type DefaultValue Description
sTextDirection sap.ui.core.TextDirection Inherit

New value for property textDirection

setTruncated

Sets the Token's truncated property.

Param Type DefaultValue Description
bValue boolean

The new property value.

bSkipInvalidation boolean

true if control invalidation should not happen.