Class sap.ui.core.ElementModule: sap/ui/core/Element


Base Class for Elements.
Constructor Summary
new sap.ui.core.Element(sId?, mSettings?)Constructs and initializes a UI Element with the given sId and settings.
Method Summary
sap.ui.core.Element.extend(sClassName, oClassInfo?, FNMetaImpl?)Creates a new subclass of class sap.ui.core.Element with name sClassName and enriches it with the information contained in oClassInfo.
sap.ui.core.Element.getMetadata()Returns a metadata object for class sap.ui.core.Element.
$(sSuffix?)Returns the best suitable DOM node that represents this Element wrapped as jQuery object.
addCustomData(oCustomData)Adds some customData to the aggregation customData.
addDependent(oDependent)Adds some dependent to the aggregation dependents.
addEventDelegate(oDelegate, oThis?)Adds a delegate that listens to the events that are fired on this element (as opposed to events which are fired BY this element).
applyFocusInfo(oFocusInfo)Applies the focus info.
bindElement(vPath, mParameters?)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.
clone(sIdSuffix?, aLocalIds?)Create a clone of this Element.
data()Attaches custom data to an Element or retrieves attached data.
destroy(bSuppressInvalidate?)Cleans up the resources associated with this element and all its children.
destroyCustomData()Destroys all the customData in the aggregation customData.
destroyDependents()Destroys all the dependents in the aggregation dependents.
destroyLayoutData()Destroys the layoutData in the aggregation layoutData.
destroyTooltip()Destroys the tooltip in the aggregation named tooltip.
enhanceAccessibilityState(oElement, mAriaProps)Allows the parent of a control to enhance the aria information during rendering.
exit()Cleans up the element instance before destruction.
findElements(bRecursive)Searches and returns an array of child elements and controls which are referenced within an aggregation or aggregations of child elements/controls.
fireEvent(sEventId, mParameters)Fires the given event and notifies all listeners.
focus()Sets the focus to the stored focus DOM reference
getCustomData()Gets content of aggregation customData.
getDependents()Gets content of aggregation dependents.
getDomRef(sSuffix?)Returns the best suitable DOM Element that represents this UI5 Element.
getElementBinding(sModelName)Get the element binding object for a specific model
getFocusDomRef()Returns the DOM Element that should get the focus.
getFocusInfo()Returns an object representing the serialized focus information To be overwritten by the specific control method
getLayoutData()Gets content of aggregation layoutData.
getMetadata()Returns the runtime metadata for this UI element.
getTooltip()Returns the tooltip for this element if any or an undefined value.
getTooltip_AsString()Returns the tooltip for this element but only if it is a simple string.
getTooltip_Text()Returns the main text for the current tooltip or undefined if there is no such text.
indexOfCustomData(oCustomData)Checks for the provided sap.ui.core.CustomData in the aggregation customData.
indexOfDependent(oDependent)Checks for the provided sap.ui.core.Element in the aggregation dependents.
init()Initializes the element instance after creation.
insertCustomData(oCustomData, iIndex)Inserts a customData into the aggregation customData.
insertDependent(oDependent, iIndex)Inserts a dependent into the aggregation dependents.
removeAllCustomData()Removes all the controls from the aggregation customData.
removeAllDependents()Removes all the controls from the aggregation dependents.
removeCustomData(vCustomData)Removes a customData from the aggregation customData.
removeDependent(vDependent)Removes a dependent from the aggregation dependents.
removeEventDelegate(oDelegate)Removes the given delegate from this element.
rerender()This triggers immediate rerendering of its parent and thus of itself and its children.
setLayoutData(oLayoutData)Sets the sap.ui.core.LayoutData defining the layout constraints for this control when it is used inside a layout.
setTooltip(vTooltip)Sets a new tooltip for this object.
toString()Returns a simple string representation of this element.
unbindElement(sModelName)Removes the defined binding context of this object, all bindings will now resolve relative to the parent context again.
sap.ui.core.Element.create(vData, oKeyInfo?)Creates a new Element from the given data.
sap.ui.core.Element.defineClass(sClassName, oStaticInfo, fnMetaImpl?)Creates metadata for a UI Element by extending the Object Metadata.
prop(sPropertyName, oValue?)This function either calls set[sPropertyName] or get[sPropertyName] with the specified property name depending if an oValue is provided or not.
Constructor Detail
new sap.ui.core.Element(sId?, mSettings?)

Constructs and initializes a UI Element with the given sId and 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.

If a key name is ambiguous for a specific control class (e.g. a property has the same name as an event), then this method prefers property, aggregation, association and event in that order. To resolve such ambiguities, the keys can be prefixed with aggregation:, association: or event:. In that case the keys must be quoted due to the ':'.

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

Valid Values:

  • for normal properties, the value has to be of the correct simple type (no type conversion occurs)
  • for 0..1 aggregations, the value has to be an instance of the aggregated control or element type
  • for 0..n aggregations, the value has to be an array of instances of the aggregated type
  • for 0..1 associations, an instance of the associated type or an id (string) is accepted
  • 0..n associations are not supported yet
  • for events either a function (event handler) is accepted or an array of length 2 where the first element is a function and the 2nd element is an object to invoke the method on.

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 for a general description of the syntax of the settings object.

The supported settings are:

In addition, all settings applicable to the base type sap.ui.base.ManagedObject can be used as well.

Parameters:
stringsId?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!
objectmSettings?optional map/JSON-object with initial property values, aggregated objects etc. for the new element
Method Detail
sap.ui.core.Element.extend(sClassName, oClassInfo?, FNMetaImpl?): function

Creates a new subclass of class sap.ui.core.Element 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.base.ManagedObject.extend.

Parameters:
stringsClassNameName of the class being created
objectoClassInfo?Object literal with information about the class
functionFNMetaImpl?Constructor function for the metadata object; if not given, it defaults to sap.ui.core.ElementMetadata
Returns:
functionCreated class / constructor function
sap.ui.core.Element.getMetadata(): sap.ui.base.Metadata
Returns a metadata object for class sap.ui.core.Element.
Returns:
sap.ui.base.MetadataMetadata object describing this class
$(sSuffix?): jQuery

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.

Parameters:
stringsSuffix?ID suffix to get a jQuery object for
Returns:
jQueryThe jQuery wrapped element's DOM reference
addCustomData(oCustomData): sap.ui.core.Element
Adds some customData to the aggregation customData.
Parameters:
sap.ui.core.CustomDataoCustomDatathe customData to add; if empty, nothing is inserted
Returns:
sap.ui.core.ElementReference to this in order to allow method chaining
addDependent(oDependent): sap.ui.core.Element
Adds some dependent to the aggregation dependents.
Parameters:
sap.ui.core.ElementoDependentthe dependent to add; if empty, nothing is inserted
Returns:
sap.ui.core.ElementReference to this in order to allow method chaining
Since:
1.19
addEventDelegate(oDelegate, oThis?): sap.ui.core.Element

Adds a delegate that listens to the events that are fired on this element (as opposed to events which are fired BY this element).

When this element is cloned, the same delegate will be added to all clones. 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 which does not clone delegates by default may be more suitable, as typically each control instance takes care of its own delegates.

To avoid double registrations, all registrations of the given delegate are first removed and then the delegate is added.

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

Parameters:
objectoDelegatethe delegate object
objectoThis?if given, this object will be the "this" context in the listener methods; default is the delegate object itself
Returns:
sap.ui.core.ElementReturns this to allow method chaining
Since:
1.9.0
applyFocusInfo(oFocusInfo)

Applies the focus info.

To be overwritten by the specific control method.

Parameters:
objectoFocusInfo
bindElement(vPath, mParameters?): sap.ui.core.Element
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 is no difference between sap.ui.core.Element#bindElement and sap.ui.base.ManagedObject#bindObject.
Parameters:
string|objectvPaththe binding path or an object with more detailed binding options
stringvPath.paththe binding path
objectvPath.parameters?map of additional parameters for this binding
stringvPath.model?name of the model
objectvPath.events?map of event listeners for the binding events
objectmParameters?map of additional parameters for this binding (only taken into account when vPath is a string in that case the properties described for vPath above are valid here). The supported parameters are listed in the corresponding model-specific implementation of sap.ui.model.ContextBinding.
Returns:
sap.ui.core.Elementreference to the instance itself
clone(sIdSuffix?, aLocalIds?): sap.ui.base.ManagedObject

Create a clone of this Element.

Calls ManagedObject#clone and additionally clones event delegates.

Parameters:
stringsIdSuffix?Suffix to be appended to the cloned element ID
string[]aLocalIds?Array of local IDs within the cloned hierarchy (internally used)
Returns:
sap.ui.base.ManagedObjectreference to the newly created clone
data()

Attaches custom data to an Element or retrieves attached data.

Usage:

   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.

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

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

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

   data(null)
Removes all data

   data()
Returns all data, as a map

destroy(bSuppressInvalidate?)

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.

Parameters:
booleanbSuppressInvalidate?if true, the UI element is not marked for redraw
destroyCustomData(): sap.ui.core.Element
Destroys all the customData in the aggregation customData.
Returns:
sap.ui.core.ElementReference to this in order to allow method chaining
destroyDependents(): sap.ui.core.Element
Destroys all the dependents in the aggregation dependents.
Returns:
sap.ui.core.ElementReference to this in order to allow method chaining
Since:
1.19
destroyLayoutData(): sap.ui.core.Element
Destroys the layoutData in the aggregation layoutData.
Returns:
sap.ui.core.ElementReference to this in order to allow method chaining
destroyTooltip(): sap.ui.core.Element
Destroys the tooltip in the aggregation named tooltip.
Returns:
sap.ui.core.Elementthis to allow method chaining
enhanceAccessibilityState(oElement, mAriaProps): object

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

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

Parameters:
sap.ui.core.ElementoElementthe Control/Element for which aria properties are rendered
objectmAriaPropsmap of aria properties keyed by there name (without prefix "aria-")
Returns:
objectmap of enhanced aria properties
exit()

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

findElements(bRecursive): sap.ui.core.Element[]

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.

Parameters:
booleanbRecursivetrue, if all nested children should be returned.
Returns:
sap.ui.core.Element[]array of child elements and controls
fireEvent(sEventId, mParameters): sap.ui.core.Element
Fires the given event and notifies all listeners. Listeners must not change the content of the event.
Parameters:
stringsEventIdthe event id
objectmParametersthe parameter map
Returns:
sap.ui.core.ElementReturns this to allow method chaining
focus()
Sets the focus to the stored focus DOM reference
getCustomData(): sap.ui.core.CustomData[]

Gets content of aggregation customData.

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

Returns:
sap.ui.core.CustomData[]
getDependents(): sap.ui.core.Element[]

Gets content of aggregation dependents.

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

Returns:
sap.ui.core.Element[]
Since:
1.19
getDomRef(sSuffix?): Element

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.

Parameters:
stringsSuffix?ID suffix to get the DOMRef for
Returns:
ElementThe Element's DOM Element sub DOM Element or null
getElementBinding(sModelName): sap.ui.model.Binding
Get the element binding object for a specific model
Parameters:
stringsModelNamethe name of the model
Returns:
sap.ui.model.Bindingthe element binding for the given model name
getFocusDomRef(): Element

Returns the DOM Element that should get the focus.

To be overwritten by the specific control method.

Returns:
ElementReturns the DOM Element that should get the focus
getFocusInfo()
Returns an object representing the serialized focus information To be overwritten by the specific control method
getLayoutData(): sap.ui.core.LayoutData

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.

Returns:
sap.ui.core.LayoutData
getMetadata(): object

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.

Returns:
objectruntime metadata
getTooltip(): string|sap.ui.core.TooltipBase

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.

Returns:
string|sap.ui.core.TooltipBaseThe tooltip for this Element.
getTooltip_AsString(): string
Returns the tooltip for this element but only if it is a simple string. Otherwise an undefined value is returned.
Returns:
stringstring tooltip or undefined
getTooltip_Text(): string
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).
Returns:
stringtext of the current tooltip or undefined
indexOfCustomData(oCustomData): int
Checks for the provided sap.ui.core.CustomData in the aggregation customData. and returns its index if found or -1 otherwise.
Parameters:
sap.ui.core.CustomDataoCustomDataThe customData whose index is looked for
Returns:
intThe index of the provided control in the aggregation if found, or -1 otherwise
indexOfDependent(oDependent): int
Checks for the provided sap.ui.core.Element in the aggregation dependents. and returns its index if found or -1 otherwise.
Parameters:
sap.ui.core.ElementoDependentThe dependent whose index is looked for
Returns:
intThe index of the provided control in the aggregation if found, or -1 otherwise
Since:
1.19
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(oCustomData, iIndex): sap.ui.core.Element
Inserts a customData into the aggregation customData.
Parameters:
sap.ui.core.CustomDataoCustomDatathe customData to insert; if empty, nothing is inserted
intiIndexthe 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
Returns:
sap.ui.core.ElementReference to this in order to allow method chaining
insertDependent(oDependent, iIndex): sap.ui.core.Element
Inserts a dependent into the aggregation dependents.
Parameters:
sap.ui.core.ElementoDependentthe dependent to insert; if empty, nothing is inserted
intiIndexthe 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
Returns:
sap.ui.core.ElementReference to this in order to allow method chaining
Since:
1.19
removeAllCustomData(): sap.ui.core.CustomData[]

Removes all the controls from the aggregation customData.

Additionally, it unregisters them from the hosting UIArea.

Returns:
sap.ui.core.CustomData[]An array of the removed elements (might be empty)
removeAllDependents(): sap.ui.core.Element[]

Removes all the controls from the aggregation dependents.

Additionally, it unregisters them from the hosting UIArea.

Returns:
sap.ui.core.Element[]An array of the removed elements (might be empty)
Since:
1.19
removeCustomData(vCustomData): sap.ui.core.CustomData
Removes a customData from the aggregation customData.
Parameters:
int|string|sap.ui.core.CustomDatavCustomDataThe customData to remove or its index or id
Returns:
sap.ui.core.CustomDataThe removed customData or null
removeDependent(vDependent): sap.ui.core.Element
Removes a dependent from the aggregation dependents.
Parameters:
int|string|sap.ui.core.ElementvDependentThe dependent to remove or its index or id
Returns:
sap.ui.core.ElementThe removed dependent or null
Since:
1.19
removeEventDelegate(oDelegate): sap.ui.core.Element

Removes the given delegate from this element.

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

Parameters:
objectoDelegatethe delegate object
Returns:
sap.ui.core.ElementReturns this to allow method chaining
Since:
1.9.0
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(oLayoutData)
Sets the sap.ui.core.LayoutData defining the layout constraints for this control when it is used inside a layout.
Parameters:
sap.ui.core.LayoutDataoLayoutData
setTooltip(vTooltip)

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.

Parameters:
string|sap.ui.core.TooltipBasevTooltip
toString(): string

Returns a simple string representation of this element.

Mainly useful for tracing purposes.

Returns:
stringa string description of this element
unbindElement(sModelName): sap.ui.base.ManagedObject
Removes the defined binding context of this object, all bindings will now resolve relative to the parent context again.
Parameters:
stringsModelName
Returns:
sap.ui.base.ManagedObjectreference to the instance itself
sap.ui.core.Element.create(vData, oKeyInfo?)

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

Parameters:
sap.ui.core.Element|objectvDataData to create the element from
objectoKeyInfo?An entity information (e.g. aggregation info)
stringoKeyInfo.type?Type info for the entity
Deprecated API:
As of 1.44, use the more flexible sap.ui.base.ManagedObject.create.
sap.ui.core.Element.defineClass(sClassName, oStaticInfo, fnMetaImpl?): object
Creates metadata for a UI Element by extending the Object Metadata.
Parameters:
stringsClassNamename of the class to build the metadata for
objectoStaticInfostatic information used to build the metadata
functionfnMetaImpl?constructor to be used for the metadata
Returns:
objectthe created metadata
Deprecated API:
Since 1.3.1. Use the static extend method of the desired base class (e.g. sap.ui.core.Element.extend)
prop(sPropertyName, oValue?): any|sap.ui.core.Element
This function either calls set[sPropertyName] or get[sPropertyName] with the specified property name depending if an oValue is provided or not.
Parameters:
stringsPropertyNamename of the property to set
anyoValue?value to set the property to
Returns:
any|sap.ui.core.ElementReturns this to allow method chaining in case of setter and the property value in case of getter
Deprecated API:
Since 1.28.0 The contract of this method is not fully defined and its write capabilities overlap with applySettings