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.create(mOptions)Asynchronously creates a new component instance from the given configuration.
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.get(sId)Returns an existing component instance, identified by its ID.
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.
sap.ui.core.Component.load(mOptions)Asynchronously loads a component class without instantiating it; returns a promise on the loaded class.
createComponent(vUsage)Creates a nested component that is declared in the sap.ui5/componentUsages section of the descriptor (manifest.json).
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.
Methods borrowed from class sap.ui.base.Object
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:
stringsId?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!
objectmSettings?Optional object with initial settings for the new Component instance
Method Detail
sap.ui.core.Component.create(mOptions): Promise.<sap.ui.core.Component>

Asynchronously creates a new component instance from the given configuration.

To optimize the loading process, additional asyncHints can be provided. The structure of these hints and how they impact the loading of components is an internal feature of this API and reserved for UI5 internal use only. Code that wants to be safe wrt. version updates, should not use the asyncHints property.

If Components and/or libraries are listed in the asyncHints, all the corresponding preload files will be requested in parallel, loading errors (404s) will be ignored. The constructor class will only be required after all preloads have been rejected or resolved. Only then, the new instance will be created.

Component.create({
    name: "my.comp",
    url: "find/my/comp/here",
    id: "myCompId1"
  }).then(function(oComponent) {
    ...
  });
Parameters:
objectmOptionsConfiguration options
stringmOptions.nameName of the component to load, this is the dot-separated name of the package that contains the Component.js module; Even when an alternative location is specified from which the manifest should be loaded (mOptions.manifest is set to a non-empty string), then the name specified in that manifest will be ignored and this name will be used instead to determine the module to be loaded.
stringmOptions.url?Alternative location from where to load the Component. If mOptions.manifest is set to a non-empty string, this URL specifies the location of the final component defined via that manifest, otherwise it specifies the location of the component defined via its name mOptions.name.
objectmOptions.componentData?Initial data of the Component, see sap.ui.core.Component#getComponentData.
sap.ui.core.IDmOptions.id?ID of the new Component
objectmOptions.settings?Settings of the new Component
boolean|string|objectmOptions.manifest?, Default: trueWhether and from where to load the manifest.json for the Component. When set to any truthy value, the manifest will be loaded and evaluated before the Component controller. If it is set to a falsy value, the manifest will not be evaluated before the controller. It might still be loaded synchronously if declared in the Component metadata. A non-empty string value will be interpreted as the URL to load the manifest from. A non-null object value will be interpreted as manifest content.
stringmOptions.handleValidation?, Default: falseIf set to true validation of the component is handled by the MessageManager
objectmOptions.asyncHints?Hints for asynchronous loading
string[]|object[]mOptions.asyncHints.components?a list of components needed by the current component and its subcomponents The framework will try to preload these components (their Component-preload.js) asynchronously, errors will be ignored. Please note that the framework has no knowledge about whether a Component provides a preload file or whether it is bundled in some library preload. If Components are listed in the hints section, they will be preloaded. Instead of specifying just the names of components, an object might be given that contains a mandatory name property and optionally, an url that will be used for a registerModulePath, and/or a lazy property. When lazy is set to a truthy value, only a necessary registerModulePath will be executed, but the corresponding component won't be preloaded.
string[]|object[]mOptions.asyncHints.libs?libraries needed by the Component and its subcomponents These libraries should be (pre-)loaded before the Component. The framework will asynchronously load those libraries, if they're not loaded yet. Instead of specifying just the names of libraries, an object might be given that contains a mandatory name property and optionally, an url that will be used for a registerModulePath, and/or a lazy property. When lazy is set to a truthy value, only a necessary registerModulePath will be executed, but the corresponding library won't be preloaded.
string[]|object[]mOptions.asyncHints.preloadBundles?a list of additional preload bundles The framework will try to load these bundles asynchronously before requiring the Component, errors will be ignored. The named modules must only represent preload bundles. If they are normal modules, their dependencies will be loaded with the normal synchronous request mechanism and performance might degrade. Instead of specifying just the names of components, an object might be given that contains a mandatory name property and optionally, an url that will be used for a registerModulePath.
Promise|Promise[]mOptions.asyncHints.waitFor?Promise or array of Promises for which the Component instantiation should wait
Returns:
Promise.<sap.ui.core.Component>A Promise that resolves with the newly created component instance
Throws:
TypeErrorWhen mOptions is null or not an object.
Experimental API:
Since 1.56.0. Support for asyncHints is still experimental and might be modified or removed completely again. It must not be used in productive code, except in code delivered by the UI5 teams.
Since:
1.56.0
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:
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.Component.get(sId): sap.ui.core.Component
Returns an existing component instance, identified by its ID.
Parameters:
stringsIdID of the component.
Returns:
sap.ui.core.ComponentComponent instance or undefined when no component with the given ID exists.
Since:
1.56.0
sap.ui.core.Component.getMetadata(): sap.ui.core.ComponentMetadata
Returns the metadata for the Component class.
Returns:
sap.ui.core.ComponentMetadataMetadata 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.ManagedObjectoObjectObject to retrieve the owner Component for
Returns:
sap.ui.core.Componentthe owner Component or undefined.
Since:
1.25.1
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 a 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.ManagedObjectoObjectObject to retrieve the owner ID for
Returns:
stringID of the owner or undefined
Since:
1.15.1
sap.ui.core.Component.load(mOptions): Promise.<function()>

Asynchronously loads a component class without instantiating it; returns a promise on the loaded class.

Beware: "Asynchronous component loading" doesn't necessarily mean that no more synchronous loading occurs. Both the framework as well as component implementations might still execute synchronous requests. Component.load just allows to use async calls internally.

When a manifest is referenced in mOptions, this manifest is not automatically used for instances of the Component class that are created after loading. The manifest or the manifest url must be provided for every instance explicitly.

To optimize the loading process, additional asyncHints can be provided. If components and/or libraries are listed in the asyncHints, all the corresponding preload files will be requested in parallel, loading errors (404s) will be ignored. The constructor class will only be required after all preloads have been rejected or resolved. The structure of the hints and how they impact the loading of components is an internal feature of this API and reserved for UI5 internal use only. Code that wants to be safe wrt. version updates, should not use the asyncHints property.

Parameters:
objectmOptionsConfiguration options
stringmOptions.nameName of the Component to load, as a dot-separated name; Even when an alternative location is specified from which the manifest should be loaded (mOptions.manifest is set to a non-empty string), then the name specified in that manifest will be ignored and this name will be used instead to determine the module to be loaded.
stringmOptions.url?Alternative location from where to load the Component. If mOptions.manifest is set to a non-empty string, this URL specifies the location of the final component defined via that manifest, otherwise it specifies the location of the component defined via its name mOptions.name.
boolean|string|objectmOptions.manifest?, Default: trueWhether and from where to load the manifest.json for the Component. When set to any truthy value, the manifest will be loaded and evaluated before the Component controller. If it is set to a falsy value, the manifest will not be evaluated before the controller. It might still be loaded synchronously if declared in the Component metadata. A non-empty string value will be interpreted as the URL to load the manifest from. A non-null object value will be interpreted as manifest content.
objectmOptions.asyncHints?Hints for asynchronous loading
string[]|object[]mOptions.asyncHints.components?a list of components needed by the current component and its subcomponents The framework will try to preload these components (their Component-preload.js) asynchronously, errors will be ignored. Please note that the framework has no knowledge about whether a Component provides a preload file or whether it is bundled in some library preload. If Components are listed in the hints section, they will be preloaded. Instead of specifying just the names of components, an object might be given that contains a mandatory name property and optionally, an url that will be used for a registerModulePath, and/or a lazy property. When lazy is set to a truthy value, only a necessary registerModulePath will be executed, but the corresponding component won't be preloaded.
string[]|object[]mOptions.asyncHints.libs?libraries needed by the Component and its subcomponents These libraries should be (pre-)loaded before the Component. The framework will asynchronously load those libraries, if they're not loaded yet. Instead of specifying just the names of libraries, an object might be given that contains a mandatory name property and optionally, an url that will be used for a registerModulePath, and/or a lazy property. When lazy is set to a truthy value, only a necessary registerModulePath will be executed, but the corresponding library won't be preloaded.
string[]|object[]mOptions.asyncHints.preloadBundles?a list of additional preload bundles The framework will try to load these bundles asynchronously before requiring the component, errors will be ignored. The named modules must only represent preload bundles. If they are normal modules, their dependencies will be loaded with the standard module loading mechanism and performance might degrade. Instead of specifying just the names of components, an object might be given that contains a mandatory name property and, optionally, a url that will be used for a registerModulePath.
booleanmOptions.asyncHints.preloadOnly?, Default: falseWhether only the preloads should be done, but not the loading of the Component controller class itself.
Returns:
Promise.<function()>A Promise that resolves with the loaded component class or undefined in case mOptions.asyncHints.preloadOnly is set to true
Experimental API:
Since 1.56.0. Support for asyncHints is still experimental and might be modified or removed completely again. It must not be used in productive code, except in code delivered by the UI5 teams.
Since:
1.56.0
createComponent(vUsage): sap.ui.core.Component|Promise

Creates a nested component that is declared in the sap.ui5/componentUsages section of the descriptor (manifest.json). The following snippet shows the declaration:

{
  [...]
  "sap.ui5": {
    "componentUsages": {
      "myUsage": {
        "name": "my.useful.Component"
      }
    }
  }
  [...]
}
The syntax of the configuration object of the component usage matches the configuration object of the {#link sap.ui.component} factory function.

This is an example of how the createComponent function can be used for asynchronous scenarios:

oComponent.createComponent("myUsage").then(function(oComponent) {
  oComponent.doSomething();
}).catch(function(oError) {
  jQuery.sap.log.error(oError);
});

The following example shows how createComponent can be used to create a nested component by providing specific properties like id, async, settings, or componentData:

var oComponent = oComponent.createComponent({
  usage: "myUsage",
  id: "myId",
  settings: { ... },
  componentData: { ... }
});
The allowed list of properties are defined in the parameter documentation of this function.

The properties can also be defined in the descriptor. These properties can be overwritten by the local properties of that function.

Parameters:
string|objectvUsageID of the component usage or the configuration object that creates the component
stringvUsage.usageID of component usage
stringvUsage.id?ID of the nested component that is prefixed with autoPrefixId
booleanvUsage.async?, Default: trueIndicates whether the component creation is done asynchronously (You should use synchronous creation only if really necessary, because this has a negative impact on performance.)
objectvUsage.settings?Settings for the nested component like for {#link sap.ui.component} or the component constructor
objectvUsage.componentData?Initial data of the component (@see sap.ui.core.Component#getComponentData)
Returns:
sap.ui.core.Component|PromiseComponent instance or Promise which will be resolved with the component instance (defaults to Promise / asynchronous behavior)
Since:
1.47.0
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
Returns:
objectcomponentData
Since:
1.15.0
getEventBus(): sap.ui.core.EventBus
Returns the event bus of this component.
Returns:
sap.ui.core.EventBusthe event bus
Since:
1.20.0
getManifest(): object
Returns the manifest defined in the metadata of the component. If not specified, the return value is null.
Returns:
objectmanifest.
Since:
1.33.0
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:
stringsKeyEither the manifest section name (namespace) or a concrete path
Returns:
any|nullValue of the manifest section or the key (could be any kind of value)
Since:
1.33.0
getManifestObject(): sap.ui.core.Manifest
Returns the manifest object.
Returns:
sap.ui.core.Manifestmanifest.
Since:
1.33.0
Returns the metadata for the specific class of the current instance.
Returns:
sap.ui.core.ComponentMetadataMetadata 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:
stringsLocalServiceAliasLocal service alias as defined in the manifest.json
Returns:
PromisePromise which will be resolved with the Service interface
Since:
1.37.0
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 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:
stringsConfigKeyError 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.
Returns:
stringa string if a prompt should be displayed to the user confirming closing the Component (e.g. when the Component is not yet saved).
Since:
1.15.1
onWindowError(sMessage, sFile, iLine)
The window error hook. Override this method in your Component class implementation to listen to unhandled errors.
Parameters:
stringsMessageThe error message.
stringsFileFile where the error occurred
intiLineLine 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:
functionfnFunction to execute
Returns:
anyresult of function fn
Since:
1.25.1