class sap.ui.core.CustomData

Control sample: sap.ui.core.CustomData
Visiblity: public
UX Guidelines:
Implements:
Available since: N/A
Module: sap/ui/core/CustomData
Application Component: CA-UI5-COR

Contains a single key/value pair of custom data attached to an Element.

See method Element.prototype.data and the chapter Custom Data - Attaching Data Objects to Controls in the documentation.


Constructor

Constructor for a new CustomData element.

new sap.ui.core.CustomData(sId?, mSettings?)
Param Type Default Value Description
sId? string

ID for the new element, generated automatically if no ID is given

mSettings? object

initial settings for the new element


Properties

Name Type Default Value Description
key string

The key of the data in this CustomData object. When the data is just stored, it can be any string, but when it is to be written to HTML (writeToDom == true) then it must also be a valid HTML attribute name. It must conform to the sap.ui.core.ID type and may contain no colon. To avoid collisions, it also may not start with "sap-ui". When written to HTML, the key is prefixed with "data-". If any restriction is violated, a warning will be logged and nothing will be written to the DOM.

Visibility: public
value any

The data stored in this CustomData object. When the data is just stored, it can be any JS type, but when it is to be written to HTML (writeToDom == true) then it must be a string. If this restriction is violated, a warning will be logged and nothing will be written to the DOM.

Visibility: public
writeToDom boolean false

If set to "true" and the value is of type "string" and the key conforms to the documented restrictions, this custom data is written to the HTML root element of the control as a "data-*" attribute. If the key is "abc" and the value is "cde", the HTML will look as follows:

  <SomeTag ... data-abc="cde" ... >

Thus the application can provide stable attributes by data binding which can be used for styling or identification purposes.

ATTENTION: use carefully to not create huge attributes or a large number of them.

Since: 1.9.0.

Visibility: public

Borrowed Aggregations

Name Cardinality Type Description
customData 0..n sap.ui.core.CustomData

Custom Data, a data structure like a map containing arbitrary key value pairs.

dependents 0..n sap.ui.core.Element

Dependents are not rendered, but their databinding context and lifecycle are bound to the aggregating Element.

Since: 1.19.

dragDropConfig 0..n sap.ui.core.dnd.DragDropBase

Defines the drag-and-drop configuration. Note: This configuration might be ignored due to control metadata restrictions.

Since: 1.56.

layoutData 0..1 sap.ui.core.LayoutData

Defines the layout constraints for this control when it is used inside a Layout. LayoutData classes are typed classes and must match the embedding Layout. See VariantLayoutData for aggregating multiple alternative LayoutData instances to a single Element.

tooltip 0..1 sap.ui.core.TooltipBase

The tooltip that should be shown for this Element.

In the most simple case, a tooltip is a string that will be rendered by the control and displayed by the browser when the mouse pointer hovers over the control's DOM. In this variant, tooltip behaves like a simple control property.

Controls need to explicitly support this kind of tooltip as they have to render it, but most controls do. Exceptions will be documented for the corresponding controls (e.g. sap.ui.core.HTML does not support tooltips).

Alternatively, tooltip can act like a 0..1 aggregation and can be set to a tooltip control (an instance of a subclass of sap.ui.core.TooltipBase). In that case, the framework will take care of rendering the tooltip control in a popup-like manner. Such a tooltip control can display arbitrary content, not only a string.

UI5 currently does not provide a recommended implementation of TooltipBase as the use of content-rich tooltips is discouraged by the Fiori Design Guidelines. Existing subclasses of TooltipBase therefore have been deprecated. However, apps can still subclass from TooltipBase and create their own implementation when needed (potentially taking the deprecated implementations as a starting point).

See the section Using Tooltips in the Fiori Design Guideline.


Methods Overview

Method Description
sap.ui.core.CustomData.extend

Creates a new subclass of CustomData with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in Element.extend.

getKey

Gets current value of property key.

The key of the data in this CustomData object. When the data is just stored, it can be any string, but when it is to be written to HTML (writeToDom == true) then it must also be a valid HTML attribute name. It must conform to the sap.ui.core.ID type and may contain no colon. To avoid collisions, it also may not start with "sap-ui". When written to HTML, the key is prefixed with "data-". If any restriction is violated, a warning will be logged and nothing will be written to the DOM.

sap.ui.core.CustomData.getMetadata

Returns a metadata object for class sap.ui.core.CustomData.

getValue

Gets current value of property value.

The data stored in this CustomData object. When the data is just stored, it can be any JS type, but when it is to be written to HTML (writeToDom == true) then it must be a string. If this restriction is violated, a warning will be logged and nothing will be written to the DOM.

getWriteToDom

Gets current value of property writeToDom.

If set to "true" and the value is of type "string" and the key conforms to the documented restrictions, this custom data is written to the HTML root element of the control as a "data-*" attribute. If the key is "abc" and the value is "cde", the HTML will look as follows:

  <SomeTag ... data-abc="cde" ... >

Thus the application can provide stable attributes by data binding which can be used for styling or identification purposes.

ATTENTION: use carefully to not create huge attributes or a large number of them.

Default value is false.

setKey

Sets a new value for property key.

The key of the data in this CustomData object. When the data is just stored, it can be any string, but when it is to be written to HTML (writeToDom == true) then it must also be a valid HTML attribute name. It must conform to the sap.ui.core.ID type and may contain no colon. To avoid collisions, it also may not start with "sap-ui". When written to HTML, the key is prefixed with "data-". If any restriction is violated, a warning will be logged and nothing will be written to the DOM.

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

setValue

Sets a new value for property value.

The data stored in this CustomData object. When the data is just stored, it can be any JS type, but when it is to be written to HTML (writeToDom == true) then it must be a string. If this restriction is violated, a warning will be logged and nothing will be written to the DOM.

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

setWriteToDom

Sets a new value for property writeToDom.

If set to "true" and the value is of type "string" and the key conforms to the documented restrictions, this custom data is written to the HTML root element of the control as a "data-*" attribute. If the key is "abc" and the value is "cde", the HTML will look as follows:

  <SomeTag ... data-abc="cde" ... >

Thus the application can provide stable attributes by data binding which can be used for styling or identification purposes.

ATTENTION: use carefully to not create huge attributes or a large number of them.

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

Default value is false.

sap.ui.core.CustomData.extend

Creates a new subclass of CustomData with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in Element.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 sap.ui.core.ElementMetadata

getKey

Gets current value of property key.

The key of the data in this CustomData object. When the data is just stored, it can be any string, but when it is to be written to HTML (writeToDom == true) then it must also be a valid HTML attribute name. It must conform to the sap.ui.core.ID type and may contain no colon. To avoid collisions, it also may not start with "sap-ui". When written to HTML, the key is prefixed with "data-". If any restriction is violated, a warning will be logged and nothing will be written to the DOM.

sap.ui.core.CustomData.getMetadata

Returns a metadata object for class sap.ui.core.CustomData.

getValue

Gets current value of property value.

The data stored in this CustomData object. When the data is just stored, it can be any JS type, but when it is to be written to HTML (writeToDom == true) then it must be a string. If this restriction is violated, a warning will be logged and nothing will be written to the DOM.

getWriteToDom

Gets current value of property writeToDom.

If set to "true" and the value is of type "string" and the key conforms to the documented restrictions, this custom data is written to the HTML root element of the control as a "data-*" attribute. If the key is "abc" and the value is "cde", the HTML will look as follows:

  <SomeTag ... data-abc="cde" ... >

Thus the application can provide stable attributes by data binding which can be used for styling or identification purposes.

ATTENTION: use carefully to not create huge attributes or a large number of them.

Default value is false.

setKey

Sets a new value for property key.

The key of the data in this CustomData object. When the data is just stored, it can be any string, but when it is to be written to HTML (writeToDom == true) then it must also be a valid HTML attribute name. It must conform to the sap.ui.core.ID type and may contain no colon. To avoid collisions, it also may not start with "sap-ui". When written to HTML, the key is prefixed with "data-". If any restriction is violated, a warning will be logged and nothing will be written to the DOM.

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

Param Type DefaultValue Description
sKey string

New value for property key

setValue

Sets a new value for property value.

The data stored in this CustomData object. When the data is just stored, it can be any JS type, but when it is to be written to HTML (writeToDom == true) then it must be a string. If this restriction is violated, a warning will be logged and nothing will be written to the DOM.

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

Param Type DefaultValue Description
oValue any

New value for property value

setWriteToDom

Sets a new value for property writeToDom.

If set to "true" and the value is of type "string" and the key conforms to the documented restrictions, this custom data is written to the HTML root element of the control as a "data-*" attribute. If the key is "abc" and the value is "cde", the HTML will look as follows:

  <SomeTag ... data-abc="cde" ... >

Thus the application can provide stable attributes by data binding which can be used for styling or identification purposes.

ATTENTION: use carefully to not create huge attributes or a large number of them.

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

New value for property writeToDom