abstract class sap.ui.core.UIComponent

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

Base Class for UIComponent.

If you are extending a UIComponent make sure you read the #.extend documentation since the metadata is special.


Constructor

Creates and initializes a new UIComponent with the given sId and settings.

The set of allowed entries in the mSettings object depends on the concrete subclass and is described there. See sap.ui.core.Component for a general description of this argument.

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

Optional 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 settings for the new component instance


Aggregations

Default Aggregation:

Name Cardinality Type Description
rootControl 0..1 sap.ui.core.Control

The root control of the UIComponent.

The root control should be created inside the function sap.ui.core.UIComponent#createContent.


Methods Overview

Method Description
_getRouterClassName

Determines the router class name by checking the "routing" configuration manifest entry. Override to change the criteria for determining the router class.

byId

Returns an element by its ID in the context of the component.

createContent

Hook method to create the content (UI Control Tree) of this component.

The default implementation in this class reads the name (and optionally type) of a root view from the descriptor for this component (path /sap.ui5/rootView) or, for backward compatibility, just the name from static component metadata (property rootView). When no type is specified, it defaults to XML. The method then calls the view factory to instantiate the root view and returns the result.

When there is no root view configuration, null will be returned.

This method can be overwritten by subclasses if the default implementation doesn't fit their needs. Subclasses are not limited to views as return type but may return any control, but only a single control (can be the root of a larger control tree, however).

A sap.ui.core.UIComponent subclass can additionally implement the sap.ui.core.IAsyncContentCreation interface. When implementing this interface the loading and processing of an asynchronous rootView will be chained into the result Promise of the Component.create factory. An additional async flag can be omitted. See Sample 1 below.

Samples 2 and 3 show how subclasses can overwrite the createContent function to run asynchronously. To create the root control asynchronously, the subclass has to define the sap.ui.core.IAsyncContentCreation interface in the metadata.

createId

Convert the given component local element ID to a globally unique ID by prefixing it with the component ID.

sap.ui.core.UIComponent.extend

Creates a new subclass of class sap.ui.core.UIComponent 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.Component.extend.

getAutoPrefixId

A method to be implemented by UIComponents, returning the flag whether to prefix the IDs of controls automatically or not if the controls are created inside the sap.ui.core.UIComponent#createContent function. By default this feature is not activated.

You can overwrite this function and return true to activate the automatic prefixing. In addition the default behavior can be configured in the manifest by specifying the entry sap.ui5/autoPrefixId.

getEventingParent

Returns the parent in the eventing hierarchy of this object which will be the UIArea of the containing ComponentContainer or null.

References:

  • sap.ui.base.EventProvider#getEventingParent

getLocalId

Returns the local ID of an element by removing the component ID prefix or null if the ID does not contain a prefix.

sap.ui.core.UIComponent.getMetadata

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

getRootControl

Returns the content of sap.ui.core.UIComponent#createContent. If you specified a rootView in your metadata or in the descriptor file (manifest.json), you will get the instance of the root view. This getter will only return something if the sap.ui.core.UIComponent#init function was invoked. If createContent is not implemented, and there is no root view, it will return null. Here is an example:

         var MyExtension = UIComponent.extend("my.Component", {
              metadata: {
                   rootView: "my.View"
              },
              init: function () {
                   this.getRootControl(); // returns null
                   UIComponent.prototype.init.apply(this, arguments);
                   this.getRootControl(); // returns the view "my.View"
              }
         });
    

getRouter

Returns the reference to the router instance which has been created by the UIComponent once the routes in the routing metadata has been defined.

sap.ui.core.UIComponent.getRouterFor

Returns the reference to the router instance.

The passed controller or view has to be created in the context of a UIComponent to return the router instance. Otherwise this function will return undefined. You may define the routerClass property in the config section of the routing to make the Component create your router extension.

Example:

routing: {
	config: {
		routerClass : myAppNamespace.MyRouterClass
		...
}
...

getTargets

Returns the reference to the Targets instance which has been created by the UIComponent once the targets in the routing metadata has been defined. If routes have been defined, it will be the Targets instance created and used by the router.

getUIArea

Returns the reference to the UIArea of the container.

hasNativeRouter

Determines if the router instance is created by the component and not overriden by overridding the sap.ui.core.UIComponent#getRouter method.

init

Initializes the component instance after creation.

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

Subclasses of UIComponent should override this hook to implement any necessary initialization. When overriding this function make sure to invoke the init function of the UIComponent as well!

onAfterRendering

Function is called when the rendering of the ComponentContainer is completed.

Applications must not call this hook method directly, it is called from ComponentContainer.

Subclasses of UIComponent override this hook to implement any necessary actions after the rendering.

onBeforeRendering

Function is called when the rendering of the ComponentContainer is started.

Applications must not call this hook method directly, it is called from ComponentContainer.

Subclasses of UIComponent override this hook to implement any necessary actions before the rendering.

render

Renders the root control of the UIComponent.

rootControlLoaded

Returns a Promise representing the loading state of the root control.

For UIComponents implementing the sap.ui.core.IAsyncContentCreation interface, there are two possible cases:

  1. The UIComponent overwrites the sap.ui.core.UIComponent#createContent function and returns a Promise. The rootControlLoaded function will then return the same Promise.
  2. The UIComponent defines a root view via its manifest. The root view is then automatically created asynchronously, and the rootControlLoaded function returns a Promise which resolves with the fully loaded and processed root view instance.

For synchronous root control creation the Promise resolves immediately with the root control instance or null if none was created.

setContainer

Sets the reference to the ComponentContainer - later required for the determination of the UIArea for the UIComponent.

_getRouterClassName

Determines the router class name by checking the "routing" configuration manifest entry. Override to change the criteria for determining the router class.

byId

Returns an element by its ID in the context of the component.

Param Type DefaultValue Description
sId string

Component local ID of the element

createContent

Hook method to create the content (UI Control Tree) of this component.

The default implementation in this class reads the name (and optionally type) of a root view from the descriptor for this component (path /sap.ui5/rootView) or, for backward compatibility, just the name from static component metadata (property rootView). When no type is specified, it defaults to XML. The method then calls the view factory to instantiate the root view and returns the result.

When there is no root view configuration, null will be returned.

This method can be overwritten by subclasses if the default implementation doesn't fit their needs. Subclasses are not limited to views as return type but may return any control, but only a single control (can be the root of a larger control tree, however).

A sap.ui.core.UIComponent subclass can additionally implement the sap.ui.core.IAsyncContentCreation interface. When implementing this interface the loading and processing of an asynchronous rootView will be chained into the result Promise of the Component.create factory. An additional async flag can be omitted. See Sample 1 below.

Samples 2 and 3 show how subclasses can overwrite the createContent function to run asynchronously. To create the root control asynchronously, the subclass has to define the sap.ui.core.IAsyncContentCreation interface in the metadata.

createId

Convert the given component local element ID to a globally unique ID by prefixing it with the component ID.

Param Type DefaultValue Description
sId string

Component local ID of the element

sap.ui.core.UIComponent.extend

Creates a new subclass of class sap.ui.core.UIComponent 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.Component.extend.

Param Type DefaultValue Description
sClassName string

Qualified name of the newly created class

oClassInfo object

Object literal with information about the class

metadata object

See sap.ui.core.Element.extend for the values allowed in every extend.

routing sap.ui.core.UIComponent.RoutingMetadata

Since 1.16. An object containing the routing-relevant configurations, routes, targets, config.

After creating a component instance, you can retrieve the router with #getRouter to register a callback to be notified when routes have matched etc. You can also retrieve targets with #getTargets to display views without changing the hash.

Note: Configuring the routing in the metadata in the source code is deprecated. Better create an application descriptor (manifest.json) instead for your component.

FNMetaImpl function sap.ui.core.ComponentMetadata

Constructor function for the metadata object. If not given, it defaults to an internal subclass of sap.ui.core.ComponentMetadata.

getAutoPrefixId

A method to be implemented by UIComponents, returning the flag whether to prefix the IDs of controls automatically or not if the controls are created inside the sap.ui.core.UIComponent#createContent function. By default this feature is not activated.

You can overwrite this function and return true to activate the automatic prefixing. In addition the default behavior can be configured in the manifest by specifying the entry sap.ui5/autoPrefixId.

getEventingParent

Returns the parent in the eventing hierarchy of this object which will be the UIArea of the containing ComponentContainer or null.

References:

getLocalId

Returns the local ID of an element by removing the component ID prefix or null if the ID does not contain a prefix.

Param Type DefaultValue Description
sId string

Prefixed ID

sap.ui.core.UIComponent.getMetadata

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

getRootControl

Returns the content of sap.ui.core.UIComponent#createContent. If you specified a rootView in your metadata or in the descriptor file (manifest.json), you will get the instance of the root view. This getter will only return something if the sap.ui.core.UIComponent#init function was invoked. If createContent is not implemented, and there is no root view, it will return null. Here is an example:

         var MyExtension = UIComponent.extend("my.Component", {
              metadata: {
                   rootView: "my.View"
              },
              init: function () {
                   this.getRootControl(); // returns null
                   UIComponent.prototype.init.apply(this, arguments);
                   this.getRootControl(); // returns the view "my.View"
              }
         });
    

getRouter

Returns the reference to the router instance which has been created by the UIComponent once the routes in the routing metadata has been defined.

sap.ui.core.UIComponent.getRouterFor

Returns the reference to the router instance.

The passed controller or view has to be created in the context of a UIComponent to return the router instance. Otherwise this function will return undefined. You may define the routerClass property in the config section of the routing to make the Component create your router extension.

Example:

routing: {
	config: {
		routerClass : myAppNamespace.MyRouterClass
		...
}
...

Param Type DefaultValue Description
oControllerOrView sap.ui.core.mvc.View sap.ui.core.mvc.Controller

either a view or controller

getTargets

Returns the reference to the Targets instance which has been created by the UIComponent once the targets in the routing metadata has been defined. If routes have been defined, it will be the Targets instance created and used by the router.

getUIArea

Returns the reference to the UIArea of the container.

hasNativeRouter

Determines if the router instance is created by the component and not overriden by overridding the sap.ui.core.UIComponent#getRouter method.

init

Initializes the component instance after creation.

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

Subclasses of UIComponent should override this hook to implement any necessary initialization. When overriding this function make sure to invoke the init function of the UIComponent as well!

onAfterRendering

Function is called when the rendering of the ComponentContainer is completed.

Applications must not call this hook method directly, it is called from ComponentContainer.

Subclasses of UIComponent override this hook to implement any necessary actions after the rendering.

onBeforeRendering

Function is called when the rendering of the ComponentContainer is started.

Applications must not call this hook method directly, it is called from ComponentContainer.

Subclasses of UIComponent override this hook to implement any necessary actions before the rendering.

render

Renders the root control of the UIComponent.

Param Type DefaultValue Description
oRenderManager sap.ui.core.RenderManager

a RenderManager instance

rootControlLoaded

Returns a Promise representing the loading state of the root control.

For UIComponents implementing the sap.ui.core.IAsyncContentCreation interface, there are two possible cases:

  1. The UIComponent overwrites the sap.ui.core.UIComponent#createContent function and returns a Promise. The rootControlLoaded function will then return the same Promise.
  2. The UIComponent defines a root view via its manifest. The root view is then automatically created asynchronously, and the rootControlLoaded function returns a Promise which resolves with the fully loaded and processed root view instance.

For synchronous root control creation the Promise resolves immediately with the root control instance or null if none was created.

setContainer

Sets the reference to the ComponentContainer - later required for the determination of the UIArea for the UIComponent.

Param Type DefaultValue Description
oContainer sap.ui.core.ComponentContainer

reference to a ComponentContainer