Abstract Class sap.ui.core.ComponentModule: sap/ui/core/Component

known direct subclasses: Application, UIComponent

Base Class for Component.


Since: 1.9.2.
Constructor Summary
new sap.ui.core.Component(sId?, mSettings?)Creates and initializes a new Component with the given sId and settings.
Method Summary
sap.ui.core.Component.extend(sClassName, oClassInfo?, FNMetaImpl?)Creates a new subclass of class sap.ui.core.Component with name sClassName and enriches it with the information contained in oClassInfo.
sap.ui.core.Component.getMetadata()Returns the metadata for the Component class.
sap.ui.core.Component.getOwnerComponentFor(oObject)Returns the Component instance in whose "context" the given ManagedObject has been created or undefined.
sap.ui.core.Component.getOwnerIdFor(oObject)Returns the ID of the object in whose "context" the given ManagedObject has been created.
exit()Cleans up the Component instance before destruction.
getComponentData()Returns user specific data object
getEventBus()Returns the event bus of this component.
getManifest()Returns the manifest defined in the metadata of the component.
getManifestEntry(sKey)Returns the configuration of a manifest section or the value for a specific path.
getManifestObject()Returns the manifest object.
getMetadata()Returns the metadata for the specific class of the current instance.
getService(sLocalServiceAlias)Returns a service interface for the Service declared in the descriptor for components (manifest.json).
init()Initializes the Component instance after creation.
onConfigChange(sConfigKey)The hook which gets called when the static configuration of the component has been changed by some configuration extension.
onWindowBeforeUnload()The window before unload hook.
onWindowError(sMessage, sFile, iLine)The window error hook.
onWindowUnload()The window unload hook.
runAsOwner(fn)Calls the function fn once and marks all ManagedObjects created during that call as "owned" by this Component.
Constructor Detail
new sap.ui.core.Component(sId?, mSettings?)
Creates and initializes a new Component 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 for a general description of the syntax of the settings object.

This class does not have its own settings, but all settings applicable to the base type sap.ui.base.ManagedObject can be used.

Parameters:
{string}sId? Optional ID for the new control; generated automatically if no non-empty ID is given. Note: this can be omitted, no matter whether mSettings are given or not!
{object}mSettings? Optional map or JSON-object with initial settings for the new Component instance
Method Detail
sap.ui.core.Component.extend(sClassName, oClassInfo?, FNMetaImpl?): function
Creates a new subclass of class sap.ui.core.Component 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:
{string}sClassName Name of the class being created
{object}oClassInfo? Object literal with information about the class
{function}FNMetaImpl? Constructor function for the metadata object; if not given, it defaults to sap.ui.core.ElementMetadata
Returns:
{function} Created class / constructor function
sap.ui.core.Component.getMetadata(): sap.ui.core.ComponentMetadata
Returns the metadata for the Component class.
Returns:
{sap.ui.core.ComponentMetadata} Metadata for the Component class.
sap.ui.core.Component.getOwnerComponentFor(oObject): sap.ui.core.Component
Returns the Component instance in whose "context" the given ManagedObject has been created or undefined.

This is a convenience wrapper around Component.getOwnerIdFor. If the owner ID cannot be determined for reasons documented on getOwnerForId or when the Component for the determined ID no longer exists, undefined will be returned.

Parameters:
{sap.ui.base.ManagedObject}oObject Object to retrieve the owner Component for
Since:
1.25.1
Returns:
{sap.ui.core.Component} the owner Component or undefined.
sap.ui.core.Component.getOwnerIdFor(oObject): string
Returns the ID of the object in whose "context" the given ManagedObject has been created.

For objects that are not ManagedObjects or for which the owner is unknown, undefined will be returned as owner ID.

Note: Ownership for objects is only checked by the framework at the time when they are created. It is not checked or updated afterwards. And it can only be detected while the Component.runAsOwner function is executing. Without further action, this is only the case while the content of an UIComponent is constructed or when a Router creates a new View and its content.

Note: This method does not guarantee that the returned owner ID belongs to a Component. Currently, it always does. But future versions of UI5 might introduce a more fine grained ownership concept, e.g. taking Views into account. Callers that want to deal only with components as owners, should use the following method: Component.getOwnerComponentFor. It guarantees that the returned object (if any) will be a Component.

Further note that only the ID of the owner is recorded. In rare cases, when the lifecycle of a ManagedObject is not bound to the lifecycle of its owner, (e.g. by the means of aggregations), then the owner might have been destroyed already whereas the ManagedObject is still alive. So even the existence of an owner ID is not a guarantee for the existence of the corresponding owner.

Parameters:
{sap.ui.base.ManagedObject}oObject Object to retrieve the owner ID for
Since:
1.15.1
Returns:
{string} ID of the owner or undefined
exit()
Cleans up the Component instance before destruction.

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

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

getComponentData(): object
Returns user specific data object
Since:
1.15.0
Returns:
{object} componentData
getEventBus(): sap.ui.core.EventBus
Returns the event bus of this component.
Since:
1.20.0
Returns:
{sap.ui.core.EventBus} the event bus
getManifest(): object
Returns the manifest defined in the metadata of the component. If not specified, the return value is null.
Since:
1.33.0
Returns:
{object} manifest.
getManifestEntry(sKey): any|null
Returns the configuration of a manifest section or the value for a specific path. If no section or key is specified, the return value is null.

Example: { "sap.ui5": { "dependencies": { "libs": { "sap.m": {} }, "components": { "my.component.a": {} } } });

The configuration above can be accessed in the following ways:

  • By section/namespace: oComponent.getManifestEntry("sap.ui5")
  • By path: oComponent.getManifestEntry("/sap.ui5/dependencies/libs")

By section/namespace returns the configuration for the specified manifest section and by path allows to specify a concrete path to a dedicated entry inside the manifest. The path syntax always starts with a slash (/).

Parameters:
{string}sKey Either the manifest section name (namespace) or a concrete path
Since:
1.33.0
Returns:
{any|null} Value of the manifest section or the key (could be any kind of value)
getManifestObject(): sap.ui.core.Manifest
Returns the manifest object.
Since:
1.33.0
Returns:
{sap.ui.core.Manifest} manifest.
Returns the metadata for the specific class of the current instance.
Returns:
{sap.ui.core.ComponentMetadata} Metadata for the specific class of the current instance.
getService(sLocalServiceAlias): Promise
Returns a service interface for the Service declared in the descriptor for components (manifest.json). The declaration needs to be done in the sap.ui5/services section as follows:
{
  [...]
  "sap.ui5": {
    "services": {
      "myLocalServiceAlias": {
        "factoryName": "my.ServiceFactory",
        ["optional": true]
      }
    }
  }
  [...]
}
The service declaration is used to define a mapping between the local alias for the service that can be used in the Component and the name of the service factory which will be used to create a service instance.

The getService function will look up the service factory and will create a new instance by using the service factory function createInstance The optional property defines that the service is not mandatory and the usage will not depend on the availability of this service. When requesting an optional service the getService function will reject but there will be no error logged in the console.

When creating a new instance of the service the Component context will be passed as oServiceContext as follows:

{
  "scopeObject": this,     // the Component instance
  "scopeType": "component" // the stereotype of the scopeObject
}

The service will be created only once per Component and reused in future calls to the getService function.

This function will return a Promise which provides the service interface when resolved. If the factoryName could not be found in the Service Factory Registry or the service declaration in the descriptor for components (manifest.json) is missing the Promise will reject.

This is an example of how the getService function can be used:

oComponent.getService("myLocalServiceAlias").then(function(oService) {
  oService.doSomething();
}).catch(function(oError) {
  jQuery.sap.log.error(oError);
});
Parameters:
{string}sLocalServiceAlias Local service alias as defined in the manifest.json
Since:
1.37.0
Returns:
{Promise} Promise which will be resolved with the Service interface
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 an Component is executed.

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

onConfigChange(sConfigKey)
The hook which gets called when the static configuration of the component has been changed by some configuration extension.
Parameters:
{string}sConfigKey Error message.
Since:
1.15.1
onWindowBeforeUnload(): string
The window before unload hook. Override this method in your Component class implementation, to handle cleanup before the real unload or to prompt a question to the user, if the component should be exited.
Since:
1.15.1
Returns:
{string} a string if a prompt should be displayed to the user confirming closing the Component (e.g. when the Component is not yet saved).
onWindowError(sMessage, sFile, iLine)
The window error hook. Override this method in your Component class implementation to listen to unhandled errors.
Parameters:
{string}sMessage The error message.
{string}sFile File where the error occurred
{number}iLine Line number of the error
Since:
1.15.1
onWindowUnload()
The window unload hook. Override this method in your Component class implementation, to handle cleanup of the component once the window will be unloaded (e.g. closed).
Since:
1.15.1
runAsOwner(fn): any
Calls the function fn once and marks all ManagedObjects created during that call as "owned" by this Component.

Nested calls of this method are supported (e.g. inside a newly created, nested component). The currently active owner Component will be remembered before executing fn and restored afterwards.

Parameters:
{function}fn Function to execute
Since:
1.25.1
Returns:
{any} result of function fn