Base Class for Components. Components are independent and reusable parts of UI5 applications. They facilitate the encapsulation of closely related parts of an application, thus enabling developers to structure and maintain their applications more easily.
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#constructor 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.
new sap.ui.core.Component(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? | object | Optional object with initial settings for the new Component instance |
Method | Description |
---|---|
sap.ui.core.Component._createComponent |
Internal API to create a component with Component.create (async) or sap.ui.component (sync). In case a |
_enhanceWithUsageConfig |
Enhances the given config object with the manifest configuration of the given usage. The given object is not modified, but the final object will be returned. |
activate |
Activates the component and all descendant components. If this or any descendant component does not enabled keep alive, no component will be activated Activation includes following steps:
|
sap.ui.core.Component.create |
Asynchronously creates a new component instance from the given configuration. If the component class does not already exists, the component class is loaded and afterwards the new component instance is created. To optimize the loading process, additional If Components and/or libraries are listed in the A component can implement the sap.ui.core.IAsyncContentCreation interface. Please see the respective documentation for more information. |
createComponent |
Creates a nested component that is declared in the { [...] "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 oComponent.createComponent("myUsage").then(function(oComponent) { oComponent.doSomething(); }).catch(function(oError) { Log.error(oError); }); The following example shows how 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. |
deactivate |
Deactivates the component and all descendant components If this or any descendant component has not enabled keep alive, no component will be deactivated Deactivation includes following steps:
|
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. |
sap.ui.core.Component.extend |
Creates a new subclass of class sap.ui.core.Component with name
|
sap.ui.core.Component.get |
Returns an existing component instance, identified by its ID. |
getActiveTerminologies |
Returns the list of active terminologies. See the Component.create factory API documentation for more detail. |
getComponentData |
Returns user specific data object |
getEventBus |
Returns the event bus of this component. |
getInterface |
Components don't have a facade and therefore return themselves as their interface.
|
getManifest |
Returns the manifest defined in the metadata of the component. If not specified, the return value is null. |
getManifestEntry |
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: The configuration above can be accessed in the following ways:
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 (/). |
getManifestObject |
Returns the manifest object. |
getMetadata |
Returns the metadata for the specific class of the current instance. |
sap.ui.core.Component.getMetadata |
Returns the metadata for the Component class. |
sap.ui.core.Component.getOwnerComponentFor |
Returns the Component instance in whose "context" the given ManagedObject has been created or This is a convenience wrapper around Component.getOwnerIdFor. If the owner ID cannot be determined for reasons documented on |
sap.ui.core.Component.getOwnerIdFor |
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, 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. |
getService |
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": { "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 When creating a new instance of the service the Component context will be passed as { "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 This function will return a This is an example of how the oComponent.getService("myLocalServiceAlias").then(function(oService) { oService.doSomething(); }).catch(function(oError) { Log.error(oError); }); |
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. |
isActive |
Determines if the component is active |
isKeepAliveSupported |
Checks whether a component and its nested components support "keep-alive" or not. Returns |
sap.ui.core.Component.load |
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. When a manifest is referenced in To optimize the loading process, additional |
onActivate |
This method is called after the component is activated |
onConfigChange |
The hook which gets called when the static configuration of the component has been changed by some configuration extension. |
onDeactivate |
This method is called after the component is deactivated |
onWindowBeforeUnload |
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. |
onWindowError |
The window error hook. Override this method in your Component class implementation to listen to unhandled errors. |
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). |
runAsOwner |
Calls the function 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 |
Internal API to create a component with Component.create (async) or sap.ui.component (sync). In case a oOwnerComponent
is given, it will be created within the context of it.
Param | Type | DefaultValue | Description |
---|---|---|---|
mConfig | object |
Configuration object that creates the component |
|
oOwnerComponent | sap.ui.core.Component |
Owner component |
Enhances the given config object with the manifest configuration of the given usage. The given object is not modified, but the final object will be returned.
Param | Type | DefaultValue | Description |
---|---|---|---|
sUsageId | any |
ID of the component usage |
|
mConfig | any |
Configuration object for a component |
Activates the component and all descendant components.
If this or any descendant component does not enabled keep alive, no component will be activated
Activation includes following steps:
Asynchronously creates a new component instance from the given configuration.
If the component class does not already exists, the component class is loaded and afterwards the new component instance is created.
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.
A component can implement the sap.ui.core.IAsyncContentCreation interface. Please see the respective documentation for more information.
Param | Type | DefaultValue | Description |
---|---|---|---|
mOptions | object |
Configuration options |
|
name | string |
Name 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 ( |
|
url | string |
Alternative location from where to load the Component. If |
|
componentData | object |
Initial data of the Component, see sap.ui.core.Component#getComponentData. |
|
id | sap.ui.core.ID |
ID of the new Component |
|
activeTerminologies | string[] |
List of active terminologies. The order of the given active terminologies is significant. The ResourceBundle API documentation describes the processing behavior in more detail. Please have a look at this dev-guide chapter for general usage instructions: Text Verticalization. |
|
settings | object |
Settings of the new Component |
|
manifest | boolean string object | true |
Whether 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. If the manifest could not be loaded from a given URL, the Promise returned by the Component.create factory rejects. A non-null object value will be interpreted as manifest content. |
altManifestUrl | string |
@since 1.61.0 Alternative URL for the manifest.json. If |
|
handleValidation | string | false |
If set to |
asyncHints | object |
Hints for asynchronous loading. Beware: This parameter is only used internally by the UI5 framework and compatibility cannot be guaranteed. The parameter must not be used in productive code, except in code delivered by the UI5 teams. |
|
components | string[] object[] |
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 |
|
libs | string[] object[] |
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 |
|
preloadBundles | string[] object[] |
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 preload bundles, an object might be given that contains a mandatory |
|
waitFor | Promise 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) { 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.
Param | Type | DefaultValue | Description |
---|---|---|---|
vUsage | string object |
ID of the component usage or the configuration object that creates the component |
|
usage | string |
ID of component usage |
|
id | string |
ID of the nested component that is prefixed with |
|
async | boolean | true |
Indicates whether the component creation is done asynchronously (You should use synchronous creation only if really necessary, because this has a negative impact on performance.) |
settings | object |
Settings for the nested component like for {#link sap.ui.component} or the component constructor |
|
componentData | object |
Initial data of the component (@see sap.ui.core.Component#getComponentData) |
Deactivates the component and all descendant components
If this or any descendant component has not enabled keep alive, no component will be deactivated
Deactivation includes following steps:
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.
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.
Param | Type | DefaultValue | Description |
---|---|---|---|
sClassName | string |
Name of the class being created |
|
oClassInfo | object |
Object literal with information about the class |
|
FNMetaImpl | function |
Constructor function for the metadata object; if not given, it defaults to the metadata implementation used by this class |
Returns an existing component instance, identified by its ID.
Param | Type | DefaultValue | Description |
---|---|---|---|
sId | string |
ID of the component. |
Returns the list of active terminologies. See the Component.create factory API documentation for more detail.
Components don't have a facade and therefore return themselves as their interface.
References:
Returns the manifest defined in the metadata of the component. If not specified, the return value is 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:
oComponent.getManifestEntry("sap.ui5")
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 (/).
Param | Type | DefaultValue | Description |
---|---|---|---|
sKey | string |
Either the manifest section name (namespace) or a concrete path |
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.
Param | Type | DefaultValue | Description |
---|---|---|---|
oObject | sap.ui.base.ManagedObject |
Object to retrieve the owner Component for |
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.
Param | Type | DefaultValue | Description |
---|---|---|---|
oObject | sap.ui.base.ManagedObject |
Object to retrieve the owner ID for |
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) { Log.error(oError); });
Param | Type | DefaultValue | Description |
---|---|---|---|
sLocalServiceAlias | string |
Local service alias as defined in the manifest.json |
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.
Checks whether a component and its nested components support "keep-alive" or not. Returns false
, if at least one component does not support "keep-alive".
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.
Param | Type | DefaultValue | Description |
---|---|---|---|
mOptions | object |
Configuration options |
|
name | string |
Name of the Component to load, as a dot-separated name; Even when an alternative location is specified from which the manifest should be loaded ( |
|
url | string |
Alternative location from where to load the Component. If |
|
manifest | boolean string object | true |
Whether and from where to load the manifest.json for the Component. When set to a truthy value, the manifest will be loaded and evaluated before the Component controller. When set to a falsy value, the manifest will be loaded and evaluated after the Component controller. A non-empty string value will be interpreted as the URL to load the manifest from. This implies that the manifest is loaded and evaluated before the Component controller. A non-null object value will be interpreted as manifest content. |
altManifestUrl | string |
@since 1.61.0 Alternative URL for the manifest.json. If |
|
asyncHints | object |
Hints for asynchronous loading. Beware: This parameter is only used internally by the UI5 framework and compatibility cannot be guaranteed. The parameter must not be used in productive code, except in code delivered by the UI5 teams. |
|
components | string[] object[] |
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 |
|
libs | string[] object[] |
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 |
|
preloadBundles | string[] object[] |
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 preload bundles, an object might be given that contains a mandatory |
|
preloadOnly | boolean | false |
Whether only the preloads should be done, but not the loading of the Component controller class itself. |
The hook which gets called when the static configuration of the component has been changed by some configuration extension.
Param | Type | DefaultValue | Description |
---|---|---|---|
sConfigKey | string |
Error message. |
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.
The window error hook. Override this method in your Component class implementation to listen to unhandled errors.
Param | Type | DefaultValue | Description |
---|---|---|---|
sMessage | string |
The error message. |
|
sFile | string |
File where the error occurred |
|
iLine | int |
Line number of the error |
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).
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.
Param | Type | DefaultValue | Description |
---|---|---|---|
fn | function |
Function to execute |