abstract class sap.ui.core.Element

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

Base Class for UI Elements.

Element is the most basic building block for UI5 UIs. An Element has state like a ManagedObject, it has a unique ID by which the framework remembers it. It can have associated DOM, but it can't render itself. Only Controls can render themselves and also take care of rendering Elements that they aggregate as children. If an Element has been rendered, its related DOM gets the same ID as the Element and thereby can be retrieved via API. When the state of an Element changes, it informs its parent Control which usually re-renders then.

Dispatching Events

The UI5 framework already registers generic listeners for common browser events, such as click or keydown. When called, the generic listener first determines the corresponding target element using jQuery#control. Then it checks whether the element has an event handler method for the event. An event handler method by convention has the same name as the event, but prefixed with "on": Method onclick is the handler for the click event, method onkeydown the handler for the keydown event and so on. If there is such a method, it will be called with the original event as the only parameter. If the element has a list of delegates registered, their handler functions will be called the same way, where present. The set of implemented handlers might differ between element and delegates. Not each handler implemented by an element has to be implemented by its delegates, and delegates can implement handlers that the corresponding element doesn't implement.

A list of browser events that are handled that way can be found in module:sap/ui/events/ControlEvents. Additionally, the framework dispatches pseudo events (module:sap/ui/events/PseudoEvents) using the same naming convention. Last but not least, some framework events are also dispatched that way, e.g. BeforeRendering, AfterRendering (only for controls) and ThemeChanged.

If further browser events are needed, controls can register listeners on the DOM using native APIs in their onAfterRendering handler. If needed, they can do this for their aggregated elements as well. If events might fire often (e.g. mousemove), it is best practice to register them only while needed, and deregister afterwards. Anyhow, any registered listeners must be cleaned up in the onBeforeRendering listener and before destruction in the exit hook.


Constructor

Constructs and initializes a UI Element with the given sId and settings.

Uniqueness of IDs

Each Element must have an ID. If no sId or mSettings.id is given at construction time, a new ID will be created automatically. The IDs of all elements that exist at the same time in the same window must be different. Providing an ID which is already used by another element throws an error.

When an element is created from a declarative source (e.g. XMLView), then an ID defined in that declarative source needs to be unique only within the declarative source. Declarative views will prefix that ID with their own ID (and some separator) before constructing the element. Programmatically created views (JSViews) can do the same with the sap.ui.core.mvc.View#createId API. Similarly, UIComponents can prefix the IDs of elements created in their context with their own ID. Also see UIComponent#getAutoPrefixId.

Settings

If the optional mSettings are given, they must be a JSON-like object (object literal) that defines values for properties, aggregations, associations or events keyed by their name.

Valid Names:

The property (key) names supported in the object literal are exactly the (case sensitive) names documented in the JSDoc for the properties, aggregations, associations and events of the control and its base classes. Note that for 0..n aggregations and associations this usually is the plural name, whereas it is the singular name in case of 0..1 relations.

Each subclass should document the set of supported names in its constructor documentation.

Valid Values:

Special aggregation dependents is connected to the lifecycle management and databinding, but not rendered automatically and can be used for popups or other dependent controls or elements. This allows the definition of popup controls in declarative views and enables propagation of model and context information to them.

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.ui.core.Element(sId?, mSettings?)
Param Type Default Value Description
sId? string

id for the new control; generated automatically if no non-empty id is given Note: this can be omitted, no matter whether mSettings will be given or not!

mSettings? object

optional map/JSON-object with initial property values, aggregated objects etc. for the new element


Aggregations

Default Aggregation:

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
$

Returns the best suitable DOM node that represents this Element wrapped as jQuery object. I.e. the element returned by sap.ui.core.Element#getDomRef is wrapped and returned.

If an ID suffix is given, the ID of this Element is concatenated with the suffix (separated by a single dash) and the DOM node with that compound ID will be wrapped by jQuery. This matches the UI5 naming convention for named inner DOM nodes of a control.

_attachMediaContainerWidthChange

Registers the given event handler to change events of the screen width/closest media container width, based on the range set with the given sName.

_detachMediaContainerWidthChange

Removes a previously attached event handler from the change events of the screen width/closest media container width.

_getCurrentMediaContainerRange

Returns the current media range of the Device or the closest media container

_getMediaContainerWidth

Returns the contextual width of an element, if set, or undefined otherwise

sap.ui.core.Element._interceptEvent

Intercepts an event. This method is meant for private usages. Apps are not supposed to used it. It is created for an experimental purpose. Implementation should be injected by outside.

addCustomData

Adds some customData to the aggregation customData.

addDependent

Adds some dependent to the aggregation dependents.

addDragDropConfig

Adds some dragDropConfig to the aggregation dragDropConfig.

addEventDelegate

Adds a delegate that can listen to the browser-, pseudo- and framework events that are handled by this Element (as opposed to events which are fired by this Element).

Delegates are simple objects that can have an arbitrary number of event handler methods. See the section "Handling of Events" in the #constructor documentation to learn how events will be dispatched and how event handler methods have to be named to be found.

If multiple delegates are registered for the same element, they will be called in the order of their registration. Double registrations are prevented. Before a delegate is added, all registrations of the same delegate (no matter what value for oThis was used for their registration) are removed and only then the delegate is added. Note that this might change the position of the delegate in the list of delegates.

When an element is cloned, all its event delegates will be added to the clone. This behavior is well-suited for applications which want to add delegates that also work with templates in aggregation bindings. For control development, the internal addDelegate method may be more suitable. Delegates added via that method are not cloned automatically, as typically each control instance takes care of adding its own delegates.

Important: If event delegates were added, the delegate will still be called even if the event was processed and/or cancelled via preventDefault by the Element or another event delegate. preventDefault only prevents the event from bubbling. It should be checked e.g. in the event delegate's listener whether an Element is still enabled via getEnabled. Additionally there might be other things that delegates need to check depending on the event (e.g. not adding a key twice to an output string etc.).

See Event Handler Methods for a general explanation of event handling in controls.

applyFocusInfo

Applies the focus info.

To be overwritten by the specific control method.

bindElement

Bind the object to the referenced entity in the model, which is used as the binding context to resolve bound properties or aggregations of the object itself and all of its children relatively to the given path.

If a relative binding path is used, this will be applied whenever the parent context changes.

There's no difference between bindElement and sap.ui.base.ManagedObject#bindObject.

References:

clone

Create a clone of this Element.

Calls sap.ui.base.ManagedObject#clone and additionally clones event delegates.

sap.ui.core.Element.create

Creates a new Element from the given data.

If vData is an Element already, that element is returned. If vData is an object (literal), then a new element is created with vData as settings. The type of the element is either determined by a property named Type in the vData or by a type information in the oKeyInfo object

Since 1.44 use the more flexible {@link sap.ui.base.ManagedObject.create}.
data

Retrieves, modifies or removes custom data attached to an Element.

Usages:

Setting the value for a single key

   data("myKey", myData)
Attaches myData (which can be any JS data type, e.g. a number, a string, an object, or a function) to this element, under the given key "myKey". If the key already exists,the value will be updated.

Setting a value for a single key (rendered to the DOM)

   data("myKey", myData, writeToDom)
Attaches myData to this element, under the given key "myKey" and (if writeToDom is true) writes key and value to the HTML. If the key already exists,the value will be updated. While oValue can be any JS data type to be attached, it must be a string to be also written to DOM. The key must also be a valid HTML attribute name (it must conform to sap.ui.core.ID and may contain no colon) and may not start with "sap-ui". When written to HTML, the key is prefixed with "data-".

Getting the value for a single key

   data("myKey")
Retrieves whatever data has been attached to this element (using the key "myKey") before.

Removing the value for a single key

   data("myKey", null)
Removes whatever data has been attached to this element (using the key "myKey") before.

Removing all custom data for all keys

   data(null)

Getting all custom data values as a plain object

   data()
Returns all data, as a map-like object, property names are keys, property values are values.

Setting multiple key/value pairs in a single call

   data({"myKey1": myData, "myKey2": null})
Attaches myData (using the key "myKey1" and removes any data that had been attached for key "myKey2".

References:

sap.ui.core.Element.defineClass

Creates metadata for a UI Element by extending the Object Metadata.

Since 1.3.1 Use the static <code>extend</code> method of the desired base class (e.g. {@link sap.ui.core.Element.extend})
destroy

Cleans up the resources associated with this element and all its children.

After an element has been destroyed, it can no longer be used in the UI!

Applications should call this method if they don't need the element any longer.

destroyCustomData

Destroys all the customData in the aggregation customData.

destroyDependents

Destroys all the dependents in the aggregation dependents.

destroyDragDropConfig

Destroys all the dragDropConfig in the aggregation dragDropConfig.

destroyLayoutData

Destroys the layoutData in the aggregation layoutData.

destroyTooltip

Destroys the tooltip in the aggregation named tooltip.

enhanceAccessibilityState

Allows the parent of a control to enhance the ARIA information during rendering.

This function is called by the RenderManager's accessibilityState and writeAccessibilityState methods for the parent of the currently rendered control - if the parent implements it.

exit

Hook method for cleaning up the element instance before destruction.

Applications must not call this hook method directly, it is called by the framework when the element is destroyed.

Subclasses of Element should override this hook to implement any necessary cleanup.

exit: function() {
    // ... do any further cleanups of your subclass e.g. detach events...
    this.$().off("click", this.handleClick);

    if (Element.prototype.exit) {
        Element.prototype.exit.apply(this, arguments);
    }
}

For a more detailed description how to to use the exit hook, see Section exit() Method in the documentation.

sap.ui.core.Element.extend

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

oClassInfo can contain the same information that sap.ui.base.ManagedObject.extend already accepts, plus the following dnd property to configure drag-and-drop behavior in the metadata object literal:

Example:

Element.extend('sap.mylib.MyElement', {
  metadata : {
    library : 'sap.mylib',
    properties : {
      value : 'string',
      width : 'sap.ui.core.CSSSize'
    },
    dnd : { draggable: true, droppable: false },
    aggregations : {
      items : { type: 'sap.ui.core.Control', multiple : true, dnd : {draggable: false, dropppable: true, layout: "Horizontal" } },
      header : {type : "sap.ui.core.Control", multiple : false, dnd : true },
    }
  }
});

dnd key as a metadata property

dnd: object|boolean
Defines draggable and droppable configuration of the element. The following keys can be provided via dnd object literal to configure drag-and-drop behavior of the element:

  • [draggable=false]: boolean Defines whether the element is draggable or not. The default value is false.
  • [droppable=false]: boolean Defines whether the element is droppable (it allows being dropped on by a draggable element) or not. The default value is false.
If dnd property is of type Boolean, then the draggable and droppable configuration are set to this Boolean value.

dnd key as an aggregation metadata property

dnd: object|boolean
In addition to draggable and droppable configuration, the layout of the aggregation can be defined as a hint at the drop position indicator.

  • [layout="Vertical"]: The arrangement of the items in this aggregation. This setting is recommended for the aggregation with multiplicity 0..n (multiple: true). Possible values are Vertical (e.g. rows in a table) and Horizontal (e.g. columns in a table). It is recommended to use Horizontal layout if the arrangement is multidimensional.

findElements

Searches and returns an array of child elements and controls which are referenced within an aggregation or aggregations of child elements/controls. This can be either done recursive or not.

Take care: this operation might be expensive.

focus

Sets the focus to the stored focus DOM reference.

getCustomData

Gets content of aggregation customData.

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

getDependents

Gets content of aggregation dependents.

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

getDomRef

Returns the best suitable DOM Element that represents this UI5 Element. By default the DOM Element with the same ID as this Element is returned. Subclasses should override this method if the lookup via id is not sufficient.

Note that such a DOM Element does not necessarily exist in all cases. Some elements or controls might not have a DOM representation at all (e.g. a naive FlowLayout) while others might not have one due to their current state (e.g. an initial, not yet rendered control).

If an ID suffix is given, the ID of this Element is concatenated with the suffix (separated by a single dash) and the DOM node with that compound ID will be returned. This matches the UI5 naming convention for named inner DOM nodes of a control.

getDomRefForSetting

Returns a DOM Element representing the given property or aggregation of this Element.

Check the documentation for the selector metadata setting in sap.ui.base.ManagedObject.extend for details about its syntax or its expected result.

The default implementation of this method will return null in any of the following cases:

  • no setting (property or aggregation) with the given name exists in the class of this Element
  • the setting has no selector defined in its metadata
  • this.getDomRef() returns no DOM Element for this Element or the returned DOM Element has no parentNode
  • the selector does not match anything in the context of this.getDomRef().parentNode
If more than one DOM Element within the element matches the selector, the first occurrence is returned.

Subclasses can override this method to handle more complex cases which can't be described by a CSS selector.

getDragDropConfig

Gets content of aggregation dragDropConfig.

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

getElementBinding

Get the context binding object for a specific model name.

Note: to be compatible with future versions of this API, you must not use the following model names:

  • null
  • empty string ""
  • string literals "null" or "undefined"
Omitting the model name (or using the value undefined) is explicitly allowed and refers to the default model.

getFocusDomRef

Returns the DOM Element that should get the focus.

To be overwritten by the specific control method.

getFocusInfo

Returns an object representing the serialized focus information.

To be overwritten by the specific control method.

getInterface

Elements don't have a facade and therefore return themselves as their interface.

References:

  • sap.ui.base.Object#getInterface

getLayoutData

Gets content of aggregation 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.

getMetadata

Returns the runtime metadata for this UI element.

When using the defineClass method, this function is automatically created and returns a runtime representation of the design time metadata.

sap.ui.core.Element.getMetadata

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

getTooltip

Returns the tooltip for this element if any or an undefined value. The tooltip can either be a simple string or a subclass of sap.ui.core.TooltipBase.

Callers that are only interested in tooltips of type string (e.g. to render them as a title attribute), should call the convenience method #getTooltip_AsString instead. If they want to get a tooltip text no matter where it comes from (be it a string tooltip or the text from a TooltipBase instance) then they could call #getTooltip_Text instead.

getTooltip_AsString

Returns the tooltip for this element but only if it is a simple string. Otherwise an undefined value is returned.

getTooltip_Text

Returns the main text for the current tooltip or undefined if there is no such text. If the tooltip is an object derived from sap.ui.core.Tooltip, then the text property of that object is returned. Otherwise the object itself is returned (either a string or undefined or null).

indexOfCustomData

Checks for the provided sap.ui.core.CustomData in the aggregation customData. and returns its index if found or -1 otherwise.

indexOfDependent

Checks for the provided sap.ui.core.Element in the aggregation dependents. and returns its index if found or -1 otherwise.

indexOfDragDropConfig

Checks for the provided sap.ui.core.dnd.DragDropBase in the aggregation dragDropConfig. and returns its index if found or -1 otherwise.

init

Initializes the element instance after creation.

Applications must not call this hook method directly, it is called by the framework while the constructor of an element is executed.

Subclasses of Element should override this hook to implement any necessary initialization.

insertCustomData

Inserts a customData into the aggregation customData.

insertDependent

Inserts a dependent into the aggregation dependents.

insertDragDropConfig

Inserts a dragDropConfig into the aggregation dragDropConfig.

prop

This function either calls set[sPropertyName] or get[sPropertyName] with the specified property name depending if an oValue is provided or not.

Since 1.28.0 The contract of this method is not fully defined and its write capabilities overlap with applySettings
removeAllCustomData

Removes all the controls from the aggregation customData.

Additionally, it unregisters them from the hosting UIArea.

removeAllDependents

Removes all the controls from the aggregation dependents.

Additionally, it unregisters them from the hosting UIArea.

removeAllDragDropConfig

Removes all the controls from the aggregation dragDropConfig.

Additionally, it unregisters them from the hosting UIArea.

removeCustomData

Removes a customData from the aggregation customData.

removeDependent

Removes a dependent from the aggregation dependents.

removeDragDropConfig

Removes a dragDropConfig from the aggregation dragDropConfig.

removeEventDelegate

Removes the given delegate from this element.

This method will remove all registrations of the given delegate, not only one.

rerender

This triggers immediate rerendering of its parent and thus of itself and its children.

As sap.ui.core.Element "bubbles up" the rerender, changes to child-Elements will also result in immediate rerendering of the whole sub tree.

setLayoutData

Sets the sap.ui.core.LayoutData defining the layout constraints for this control when it is used inside a layout.

setTooltip

Sets a new tooltip for this object.

The tooltip can either be a simple string (which in most cases will be rendered as the title attribute of this Element) or an instance of sap.ui.core.TooltipBase.

If a new tooltip is set, any previously set tooltip is deactivated.

toString

Returns a simple string representation of this element.

Mainly useful for tracing purposes.

unbindElement

Removes the defined binding context of this object, all bindings will now resolve relative to the parent context again.

$

Returns the best suitable DOM node that represents this Element wrapped as jQuery object. I.e. the element returned by sap.ui.core.Element#getDomRef is wrapped and returned.

If an ID suffix is given, the ID of this Element is concatenated with the suffix (separated by a single dash) and the DOM node with that compound ID will be wrapped by jQuery. This matches the UI5 naming convention for named inner DOM nodes of a control.

Param Type DefaultValue Description
sSuffix string

ID suffix to get a jQuery object for

_attachMediaContainerWidthChange

Registers the given event handler to change events of the screen width/closest media container width, based on the range set with the given sName.

Param Type DefaultValue Description
fnFunction function

The handler function to call when the event occurs. This function will be called in the context of the oListener instance (if present) or on the element instance.

oListener object

The object that wants to be notified when the event occurs (this context within the handler function). If it is not specified, the handler function is called in the context of the element.

sName string

The name of the desired range set

_detachMediaContainerWidthChange

Removes a previously attached event handler from the change events of the screen width/closest media container width.

Param Type DefaultValue Description
fnFunction function

The handler function to call when the event occurs. This function will be called in the context of the oListener instance (if present) or on the element instance.

oListener object

The object that wants to be notified when the event occurs (this context within the handler function). If it is not specified, the handler function is called in the context of the element.

sName string

The name of the desired range set

_getCurrentMediaContainerRange

Returns the current media range of the Device or the closest media container

Param Type DefaultValue Description
sName string Device.media.RANGESETS.SAP_STANDARD

The name of the range set

_getMediaContainerWidth

Returns the contextual width of an element, if set, or undefined otherwise

sap.ui.core.Element._interceptEvent

Intercepts an event. This method is meant for private usages. Apps are not supposed to used it. It is created for an experimental purpose. Implementation should be injected by outside.

Param Type DefaultValue Description
sEventId string

the name of the event

oElement sap.ui.core.Element

the element itself

mParameters object

The parameters which complement the event. Hooks must not modify the parameters.

addCustomData

Adds some customData to the aggregation customData.

Param Type DefaultValue Description
oCustomData sap.ui.core.CustomData

The customData to add; if empty, nothing is inserted

addDependent

Adds some dependent to the aggregation dependents.

Param Type DefaultValue Description
oDependent sap.ui.core.Element

The dependent to add; if empty, nothing is inserted

addDragDropConfig

Adds some dragDropConfig to the aggregation dragDropConfig.

Param Type DefaultValue Description
oDragDropConfig sap.ui.core.dnd.DragDropBase

The dragDropConfig to add; if empty, nothing is inserted

addEventDelegate

Adds a delegate that can listen to the browser-, pseudo- and framework events that are handled by this Element (as opposed to events which are fired by this Element).

Delegates are simple objects that can have an arbitrary number of event handler methods. See the section "Handling of Events" in the #constructor documentation to learn how events will be dispatched and how event handler methods have to be named to be found.

If multiple delegates are registered for the same element, they will be called in the order of their registration. Double registrations are prevented. Before a delegate is added, all registrations of the same delegate (no matter what value for oThis was used for their registration) are removed and only then the delegate is added. Note that this might change the position of the delegate in the list of delegates.

When an element is cloned, all its event delegates will be added to the clone. This behavior is well-suited for applications which want to add delegates that also work with templates in aggregation bindings. For control development, the internal addDelegate method may be more suitable. Delegates added via that method are not cloned automatically, as typically each control instance takes care of adding its own delegates.

Important: If event delegates were added, the delegate will still be called even if the event was processed and/or cancelled via preventDefault by the Element or another event delegate. preventDefault only prevents the event from bubbling. It should be checked e.g. in the event delegate's listener whether an Element is still enabled via getEnabled. Additionally there might be other things that delegates need to check depending on the event (e.g. not adding a key twice to an output string etc.).

See Event Handler Methods for a general explanation of event handling in controls.

Param Type DefaultValue Description
oDelegate object

The delegate object which consists of the event handler names and the corresponding event handler functions

oThis object oDelegate

If given, this object will be the "this" context in the listener methods; default is the delegate object itself

applyFocusInfo

Applies the focus info.

To be overwritten by the specific control method.

Param Type DefaultValue Description
oFocusInfo object

Focus info object as returned by #getFocusInfo

preventScroll boolean false

@since 1.60 if it's set to true, the focused element won't be shifted into the viewport if it's not completely visible before the focus is set

bindElement

Bind the object to the referenced entity in the model, which is used as the binding context to resolve bound properties or aggregations of the object itself and all of its children relatively to the given path.

If a relative binding path is used, this will be applied whenever the parent context changes.

There's no difference between bindElement and sap.ui.base.ManagedObject#bindObject.

References:

Param Type DefaultValue Description
vPath string object

the binding path or an object with more detailed binding options

path string

the binding path

parameters object

map of additional parameters for this binding

model string

name of the model

events object

map of event listeners for the binding events

mParameters object

map of additional parameters for this binding (only taken into account when vPath is a string in that case it corresponds to vPath.parameters). The supported parameters are listed in the corresponding model-specific implementation of sap.ui.model.ContextBinding.

clone

Create a clone of this Element.

Calls sap.ui.base.ManagedObject#clone and additionally clones event delegates.

Param Type DefaultValue Description
sIdSuffix string

Suffix to be appended to the cloned element ID

aLocalIds string[]

Array of local IDs within the cloned hierarchy (internally used)

sap.ui.core.Element.create

Creates a new Element from the given data.

If vData is an Element already, that element is returned. If vData is an object (literal), then a new element is created with vData as settings. The type of the element is either determined by a property named Type in the vData or by a type information in the oKeyInfo object

Since 1.44 use the more flexible {@link sap.ui.base.ManagedObject.create}.
Param Type DefaultValue Description
vData sap.ui.core.Element object

Data to create the element from

oKeyInfo object

An entity information (e.g. aggregation info)

type string

Type info for the entity

data

Retrieves, modifies or removes custom data attached to an Element.

Usages:

Setting the value for a single key

   data("myKey", myData)
Attaches myData (which can be any JS data type, e.g. a number, a string, an object, or a function) to this element, under the given key "myKey". If the key already exists,the value will be updated.

Setting a value for a single key (rendered to the DOM)

   data("myKey", myData, writeToDom)
Attaches myData to this element, under the given key "myKey" and (if writeToDom is true) writes key and value to the HTML. If the key already exists,the value will be updated. While oValue can be any JS data type to be attached, it must be a string to be also written to DOM. The key must also be a valid HTML attribute name (it must conform to sap.ui.core.ID and may contain no colon) and may not start with "sap-ui". When written to HTML, the key is prefixed with "data-".

Getting the value for a single key

   data("myKey")
Retrieves whatever data has been attached to this element (using the key "myKey") before.

Removing the value for a single key

   data("myKey", null)
Removes whatever data has been attached to this element (using the key "myKey") before.

Removing all custom data for all keys

   data(null)

Getting all custom data values as a plain object

   data()
Returns all data, as a map-like object, property names are keys, property values are values.

Setting multiple key/value pairs in a single call

   data({"myKey1": myData, "myKey2": null})
Attaches myData (using the key "myKey1" and removes any data that had been attached for key "myKey2".

References:

Param Type DefaultValue Description
vKeyOrData string Object<string,any> null

Single key to set or remove, or an object with key/value pairs or null to remove all custom data

vValue string any

Value to set or null to remove the corresponding custom data

bWriteToDom boolean false

Whether this custom data entry should be written to the DOM during rendering

sap.ui.core.Element.defineClass

Creates metadata for a UI Element by extending the Object Metadata.

Since 1.3.1 Use the static <code>extend</code> method of the desired base class (e.g. {@link sap.ui.core.Element.extend})
Param Type DefaultValue Description
sClassName string

name of the class to build the metadata for

oStaticInfo object

static information used to build the metadata

fnMetaImpl function sap.ui.core.ElementMetadata

constructor to be used for the metadata

destroy

Cleans up the resources associated with this element and all its children.

After an element has been destroyed, it can no longer be used in the UI!

Applications should call this method if they don't need the element any longer.

Param Type DefaultValue Description
bSuppressInvalidate boolean false

If true, this ManagedObject and all its ancestors won't be invalidated.
This flag should be used only during control development to optimize invalidation procedures. It should not be used by any application code.

destroyCustomData

Destroys all the customData in the aggregation customData.

destroyDependents

Destroys all the dependents in the aggregation dependents.

destroyDragDropConfig

Destroys all the dragDropConfig in the aggregation dragDropConfig.

destroyLayoutData

Destroys the layoutData in the aggregation layoutData.

destroyTooltip

Destroys the tooltip in the aggregation named tooltip.

enhanceAccessibilityState

Allows the parent of a control to enhance the ARIA information during rendering.

This function is called by the RenderManager's accessibilityState and writeAccessibilityState methods for the parent of the currently rendered control - if the parent implements it.

Param Type DefaultValue Description
oElement sap.ui.core.Element

The Control/Element for which ARIA properties are collected

mAriaProps object

Map of ARIA properties keyed by their name (without prefix "aria-"); the method implementation can enhance this map in any way (add or remove properties, modify values)

exit

Hook method for cleaning up the element instance before destruction.

Applications must not call this hook method directly, it is called by the framework when the element is destroyed.

Subclasses of Element should override this hook to implement any necessary cleanup.

exit: function() {
    // ... do any further cleanups of your subclass e.g. detach events...
    this.$().off("click", this.handleClick);

    if (Element.prototype.exit) {
        Element.prototype.exit.apply(this, arguments);
    }
}

For a more detailed description how to to use the exit hook, see Section exit() Method in the documentation.

sap.ui.core.Element.extend

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

oClassInfo can contain the same information that sap.ui.base.ManagedObject.extend already accepts, plus the following dnd property to configure drag-and-drop behavior in the metadata object literal:

Example:

Element.extend('sap.mylib.MyElement', {
  metadata : {
    library : 'sap.mylib',
    properties : {
      value : 'string',
      width : 'sap.ui.core.CSSSize'
    },
    dnd : { draggable: true, droppable: false },
    aggregations : {
      items : { type: 'sap.ui.core.Control', multiple : true, dnd : {draggable: false, dropppable: true, layout: "Horizontal" } },
      header : {type : "sap.ui.core.Control", multiple : false, dnd : true },
    }
  }
});

dnd key as a metadata property

dnd: object|boolean
Defines draggable and droppable configuration of the element. The following keys can be provided via dnd object literal to configure drag-and-drop behavior of the element:

If dnd property is of type Boolean, then the draggable and droppable configuration are set to this Boolean value.

dnd key as an aggregation metadata property

dnd: object|boolean
In addition to draggable and droppable configuration, the layout of the aggregation can be defined as a hint at the drop position indicator.

Param Type DefaultValue Description
sClassName string

Name of the class to be 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.

findElements

Searches and returns an array of child elements and controls which are referenced within an aggregation or aggregations of child elements/controls. This can be either done recursive or not.

Take care: this operation might be expensive.

Param Type DefaultValue Description
bRecursive boolean

true, if all nested children should be returned.

focus

Sets the focus to the stored focus DOM reference.

Param Type DefaultValue Description
oFocusInfo object {}

Options for setting the focus

preventScroll boolean false

@since 1.60 if it's set to true, the focused element won't be shifted into the viewport if it's not completely visible before the focus is set

getCustomData

Gets content of aggregation customData.

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

getDependents

Gets content of aggregation dependents.

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

getDomRef

Returns the best suitable DOM Element that represents this UI5 Element. By default the DOM Element with the same ID as this Element is returned. Subclasses should override this method if the lookup via id is not sufficient.

Note that such a DOM Element does not necessarily exist in all cases. Some elements or controls might not have a DOM representation at all (e.g. a naive FlowLayout) while others might not have one due to their current state (e.g. an initial, not yet rendered control).

If an ID suffix is given, the ID of this Element is concatenated with the suffix (separated by a single dash) and the DOM node with that compound ID will be returned. This matches the UI5 naming convention for named inner DOM nodes of a control.

Param Type DefaultValue Description
sSuffix string

ID suffix to get the DOMRef for

getDomRefForSetting

Returns a DOM Element representing the given property or aggregation of this Element.

Check the documentation for the selector metadata setting in sap.ui.base.ManagedObject.extend for details about its syntax or its expected result.

The default implementation of this method will return null in any of the following cases:

If more than one DOM Element within the element matches the selector, the first occurrence is returned.

Subclasses can override this method to handle more complex cases which can't be described by a CSS selector.

Param Type DefaultValue Description
sSettingsName string

Name of the property or aggregation

getDragDropConfig

Gets content of aggregation dragDropConfig.

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

getElementBinding

Get the context binding object for a specific model name.

Note: to be compatible with future versions of this API, you must not use the following model names:

Omitting the model name (or using the value undefined) is explicitly allowed and refers to the default model.

Param Type DefaultValue Description
sModelName string

Name of the model or undefined

getFocusDomRef

Returns the DOM Element that should get the focus.

To be overwritten by the specific control method.

getFocusInfo

Returns an object representing the serialized focus information.

To be overwritten by the specific control method.

getInterface

Elements don't have a facade and therefore return themselves as their interface.

References:

getLayoutData

Gets content of aggregation 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.

getMetadata

Returns the runtime metadata for this UI element.

When using the defineClass method, this function is automatically created and returns a runtime representation of the design time metadata.

sap.ui.core.Element.getMetadata

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

getTooltip

Returns the tooltip for this element if any or an undefined value. The tooltip can either be a simple string or a subclass of sap.ui.core.TooltipBase.

Callers that are only interested in tooltips of type string (e.g. to render them as a title attribute), should call the convenience method #getTooltip_AsString instead. If they want to get a tooltip text no matter where it comes from (be it a string tooltip or the text from a TooltipBase instance) then they could call #getTooltip_Text instead.

getTooltip_AsString

Returns the tooltip for this element but only if it is a simple string. Otherwise an undefined value is returned.

getTooltip_Text

Returns the main text for the current tooltip or undefined if there is no such text. If the tooltip is an object derived from sap.ui.core.Tooltip, then the text property of that object is returned. Otherwise the object itself is returned (either a string or undefined or null).

indexOfCustomData

Checks for the provided sap.ui.core.CustomData in the aggregation customData. and returns its index if found or -1 otherwise.

Param Type DefaultValue Description
oCustomData sap.ui.core.CustomData

The customData whose index is looked for

indexOfDependent

Checks for the provided sap.ui.core.Element in the aggregation dependents. and returns its index if found or -1 otherwise.

Param Type DefaultValue Description
oDependent sap.ui.core.Element

The dependent whose index is looked for

indexOfDragDropConfig

Checks for the provided sap.ui.core.dnd.DragDropBase in the aggregation dragDropConfig. and returns its index if found or -1 otherwise.

Param Type DefaultValue Description
oDragDropConfig sap.ui.core.dnd.DragDropBase

The dragDropConfig whose index is looked for

init

Initializes the element instance after creation.

Applications must not call this hook method directly, it is called by the framework while the constructor of an element is executed.

Subclasses of Element should override this hook to implement any necessary initialization.

insertCustomData

Inserts a customData into the aggregation customData.

Param Type DefaultValue Description
oCustomData sap.ui.core.CustomData

The customData to insert; if empty, nothing is inserted

iIndex int

The 0-based index the customData should be inserted at; for a negative value of iIndex, the customData is inserted at position 0; for a value greater than the current size of the aggregation, the customData is inserted at the last position

insertDependent

Inserts a dependent into the aggregation dependents.

Param Type DefaultValue Description
oDependent sap.ui.core.Element

The dependent to insert; if empty, nothing is inserted

iIndex int

The 0-based index the dependent should be inserted at; for a negative value of iIndex, the dependent is inserted at position 0; for a value greater than the current size of the aggregation, the dependent is inserted at the last position

insertDragDropConfig

Inserts a dragDropConfig into the aggregation dragDropConfig.

Param Type DefaultValue Description
oDragDropConfig sap.ui.core.dnd.DragDropBase

The dragDropConfig to insert; if empty, nothing is inserted

iIndex int

The 0-based index the dragDropConfig should be inserted at; for a negative value of iIndex, the dragDropConfig is inserted at position 0; for a value greater than the current size of the aggregation, the dragDropConfig is inserted at the last position

prop

This function either calls set[sPropertyName] or get[sPropertyName] with the specified property name depending if an oValue is provided or not.

Since 1.28.0 The contract of this method is not fully defined and its write capabilities overlap with applySettings
Param Type DefaultValue Description
sPropertyName string

name of the property to set

oValue any

value to set the property to

removeAllCustomData

Removes all the controls from the aggregation customData.

Additionally, it unregisters them from the hosting UIArea.

removeAllDependents

Removes all the controls from the aggregation dependents.

Additionally, it unregisters them from the hosting UIArea.

removeAllDragDropConfig

Removes all the controls from the aggregation dragDropConfig.

Additionally, it unregisters them from the hosting UIArea.

removeCustomData

Removes a customData from the aggregation customData.

Param Type DefaultValue Description
vCustomData int string sap.ui.core.CustomData

The customData to remove or its index or id

removeDependent

Removes a dependent from the aggregation dependents.

Param Type DefaultValue Description
vDependent int string sap.ui.core.Element

The dependent to remove or its index or id

removeDragDropConfig

Removes a dragDropConfig from the aggregation dragDropConfig.

Param Type DefaultValue Description
vDragDropConfig int string sap.ui.core.dnd.DragDropBase

The dragDropConfig to remove or its index or id

removeEventDelegate

Removes the given delegate from this element.

This method will remove all registrations of the given delegate, not only one.

Param Type DefaultValue Description
oDelegate object

The delegate object which consists of the event handler names and the corresponding event handler functions

rerender

This triggers immediate rerendering of its parent and thus of itself and its children.

As sap.ui.core.Element "bubbles up" the rerender, changes to child-Elements will also result in immediate rerendering of the whole sub tree.

setLayoutData

Sets the sap.ui.core.LayoutData defining the layout constraints for this control when it is used inside a layout.

Param Type DefaultValue Description
oLayoutData sap.ui.core.LayoutData

which should be set

setTooltip

Sets a new tooltip for this object.

The tooltip can either be a simple string (which in most cases will be rendered as the title attribute of this Element) or an instance of sap.ui.core.TooltipBase.

If a new tooltip is set, any previously set tooltip is deactivated.

Param Type DefaultValue Description
vTooltip string sap.ui.core.TooltipBase

New tooltip

toString

Returns a simple string representation of this element.

Mainly useful for tracing purposes.

unbindElement

Removes the defined binding context of this object, all bindings will now resolve relative to the parent context again.

Param Type DefaultValue Description
sModelName string