Core Class of the SAP UI Library.
This class boots the Core framework and makes it available for the application via method sap.ui.getCore()
.
Example:
var oCore = sap.ui.getCore();
With methods of the Core framework you can execute code after the framework has been initialized. It provides access to the configuration and exposes events that an application or a control can register to (e.g. localizationChanged, parseError, validationError, formatError, validationSuccess).
Example:
oCore.attachInit(function() { if ( oCore.getConfiguration().getRTL() ) { ... } }); oCore.attachLocalizationChanged(function(oEvent) { ... });
Event | Description |
---|---|
formatError |
The This can happen when a value stored in the model cannot be formatted to be displayed in an element property. |
localizationChanged |
Fired when any of the localization relevant configuration settings has changed (e.g. language, rtl, formatLocale, datePattern, timePattern, numberSymbol, legacy formats). The parameter
The value for each property will be the new corresponding setting. |
parseError |
The |
ThemeChanged |
Fired after a theme has been applied. More precisely, this event is fired when any of the following conditions is met:
|
validationError |
The |
validationSuccess |
The |
The formatError
event is fired when a value formatting fails.
This can happen when a value stored in the model cannot be formatted to be displayed in an element property.
Param | Type | Description |
---|---|---|
oControlEvent | sap.ui.base.Event | |
getSource | sap.ui.base.EventProvider | |
getParameters | object | |
element | sap.ui.core.Element |
Element where the format error occurred |
property | string |
Name of the property of the element where the format error occurred |
type | sap.ui.model.Type |
Type of the property |
newValue | object |
Value of the property which was entered when the format error occurred |
oldValue | object |
Value of the property which was present before a new value was entered (before the format error) |
exception | object |
Exception object which occurred and has more information about the format error |
Fired when any of the localization relevant configuration settings has changed (e.g. language, rtl, formatLocale, datePattern, timePattern, numberSymbol, legacy formats).
The parameter changes
contains additional information about the change. It is a plain object that can contain one or more of the following properties
The value for each property will be the new corresponding setting.
Param | Type | Description |
---|---|---|
oEvent | sap.ui.base.Event | |
getSource | sap.ui.base.EventProvider | |
getParameters | object | |
changes | object |
a map of the changed localization properties |
The parseError
event is fired when input parsing fails.
Param | Type | Description |
---|---|---|
oControlEvent | sap.ui.base.Event | |
getSource | sap.ui.base.EventProvider | |
getParameters | object | |
element | sap.ui.core.Element |
Element where the parse error occurred |
property | string |
Name of the property of the element where the parse error occurred |
type | sap.ui.model.Type |
Type of the property |
newValue | object |
Value of the property which was entered when the parse error occurred |
oldValue | object |
Value of the property which was present before a new value was entered (before the parse error) |
exception | object |
Exception object which occurred and has more information about the parse error |
Fired after a theme has been applied.
More precisely, this event is fired when any of the following conditions is met:
sap.ui.getCore().loadLibrary(...)
and the current theme has been applied for itParam | Type | Description |
---|---|---|
oControlEvent | sap.ui.base.Event | |
getSource | sap.ui.base.EventProvider | |
getParameters | object | |
theme | string |
Theme name |
The validationError
event is fired when validation of the input fails.
Param | Type | Description |
---|---|---|
oControlEvent | sap.ui.base.Event | |
getSource | sap.ui.base.EventProvider | |
getParameters | object | |
element | sap.ui.core.Element |
Element where the validation error occurred |
property | string |
Property name of the element where the validation error occurred |
type | sap.ui.model.Type |
Type of the property |
newValue | object |
Value of the property which was entered when the validation error occurred |
oldValue | object |
Value of the property which was present before a new value was entered (before the validation error) |
exception | object |
Exception object which occurred and has more information about the validation error |
The validationSuccess
event is fired when a value validation was successfully completed.
Param | Type | Description |
---|---|---|
oControlEvent | sap.ui.base.Event | |
getSource | sap.ui.base.EventProvider | |
getParameters | object | |
element | sap.ui.core.Element |
Element where the successful validation occurred |
property | string |
Name of the property of the element where the successful validation occurred |
type | sap.ui.model.Type |
Type of the property |
newValue | object |
Value of the property which was entered when the validation occurred |
oldValue | object |
Value of the property which was present before a new value was entered (before the validation) |
Method | Description |
---|---|
applyChanges |
Enforces an immediate update of the visible UI (aka "rendering"). In general, applications should avoid calling this method and instead let the framework manage any necessary rendering. |
applyTheme |
Applies the theme with the given name (by loading the respective style sheets, which does not disrupt the application). By default, the theme files are expected to be located at path relative to the respective control library ([libraryLocation]/themes/[themeName]). Different locations can be configured by using the method setThemePath() or by using the second parameter "sThemeBaseUrl" of applyTheme(). Usage of this second parameter is a shorthand for setThemePath and internally calls setThemePath, so the theme location is then known. sThemeBaseUrl is a single URL to specify the default location of all theme files. This URL is the base folder below which the control library folders are located. E.g. if the CSS files are not located relative to the root location of UI5, but instead they are at locations like http://my.server/myapp/resources/sap/ui/core/themes/my_theme/library.css then the URL that needs to be given is: http://my.server/myapp/resources All theme resources are then loaded from below this folder - except if for a certain library a different location has been registered. If the theme resources are not all either below this base location or with their respective libraries, then setThemePath must be used to configure individual locations. |
attachControlEvent |
Registers a listener for control events. When called, the context of the listener (its |
attachFormatError |
Attaches event handler When called, the context of the listener (its Please note that this event is a bubbling event and may already be canceled before reaching the core. |
attachInit |
Registers a given function that is executed after the framework has been initialized. The given function will either be called as soon as the framework has been initialized or, if it has been initialized already, it will be called immediately. More information about the initialization process and the steps it consists of can be found in the documentation topic "Initialization Process". |
attachInitEvent |
Registers a given function that is executed after the framework has been initialized. The method is executed only once and only if the framework has not been initialized already. This could be checked by calling #isInitialized, but in most cases it is more convenient to use #attachInit instead. This guarantees that the given function is executed exactly once, independent of the state of the framework.
Since 1.13.2 Register with the more convenient {@link #attachInit} function instead
|
attachIntervalTimer |
Registers a listener to the central interval timer. When called, the context of the listener (its
Since 1.61 Use <code>IntervalTrigger.addListener()</code> from "sap/ui/core/IntervalTrigger" module.
|
attachLocalizationChanged |
Register a listener for the localizationChanged event. When called, the context of the listener (its |
attachParseError |
Attaches event handler When called, the context of the listener (its Please note that this event is a bubbling event and may already be canceled before reaching the core. |
attachThemeChanged |
Attaches event handler When called, the context of the event handler (its |
attachValidationError |
Attaches event handler When called, the context of the listener (its Please note that this event is a bubbling event and may already be canceled before reaching the core. |
attachValidationSuccess |
Attaches event handler When called, the context of the listener (its Please note that this event is a bubbling event and may already be canceled before reaching the core. |
byFieldGroupId |
Returns a list of all controls with a field group ID. See Control.prototype.checkFieldGroupIds for a description of the |
byId |
Returns the registered element with the given ID, if any. The ID must be the globally unique ID of an element, the same as returned by When the element has been created from a declarative source (e.g. XMLView), that source might have used a shorter, non-unique local ID. A search for such a local ID cannot be executed with this method. It can only be executed on the corresponding scope (e.g. on an XMLView instance), by using the View#byId method of that scope. |
createComponent |
Creates a component with the provided id and settings. When the optional parameter sap.ui.loader.config({ paths: { "lib/with/slashes": vUrl } });
Since 1.95 Please use {@link sap.ui.core.Component.create Component.create} instead.
|
createRenderManager |
Returns a new instance of the RenderManager for exclusive use by the caller. The caller must take care to destroy the render manager when it is no longer needed. Calling this method before the Core has been initialized, is not recommended. |
createUIArea |
Creates a new UIArea.
Since 1.1 use {@link sap.ui.core.Control#placeAt Control#placeAt} instead!
|
detachControlEvent |
Unregisters a listener for control events. The passed function and listener object must match the ones used for event registration. |
detachFormatError |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
detachIntervalTimer |
Unregisters a listener for the central interval timer. A listener will only be unregistered if the same function/context combination is given as in the
Since 1.61 Use <code>IntervalTrigger.removeListener()</code> from "sap/ui/core/IntervalTrigger" module.
|
detachLocalizationChanged |
Unregister a listener from the localizationChanged event. The listener will only be unregistered if the same function/context combination is given as in the call to |
detachParseError |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
detachThemeChanged |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
detachValidationError |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
detachValidationSuccess |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
sap.ui.core.Core.extend |
Creates a new subclass of class sap.ui.core.Core with name
|
fireFormatError |
Fires event formatError to attached listeners. |
fireParseError |
Fires event parseError to attached listeners. |
fireValidationError |
Fires event validationError to attached listeners. |
fireValidationSuccess |
Fires event validationSuccess to attached listeners. Expects following event parameters:
|
getApplication |
Returns the instance of the application (if exists).
Since 1.15.1 The Component class is enhanced to take care about the Application code.
|
getComponent |
Returns the registered component for the given id, if any.
Since 1.95 Please use {@link sap.ui.core.Component.get Component.get} instead.
|
getConfiguration |
Returns the Configuration of the Core. |
getControl |
Returns the registered element for the given ID, if any.
Since 1.1 use <code>sap.ui.core.Core.byId</code> instead!
|
getCurrentFocusedControlId |
Returns the Id of the control/element currently in focus. |
getElementById |
Returns the registered element for the given ID, if any.
Since 1.1 use <code>sap.ui.core.Core.byId</code> instead!
|
getEventBus |
Returns the event bus. |
getLibraryResourceBundle |
Retrieves a resource bundle for the given library and locale. If only one argument is given, it is assumed to be the libraryName. The locale then falls back to the current session locale. If no argument is given, the library also falls back to a default: "sap.ui.core". Configuration via App Descriptor When the App Descriptor for the library is available without further request (manifest.json has been preloaded) and when the App Descriptor is at least of version 1.9.0 or higher, then this method will evaluate the App Descriptor entry
CachingOnce a resource bundle for a library has been loaded, it will be cached by this method. Further calls for the same library and locale won't create new requests, but return the already loaded bundle. There's therefore no need for control code to cache the returned bundle for a longer period of time. Not further caching the result also prevents stale texts after a locale change. Asynchronous Loading The asynchronous variant of #loadLibrary will evaluate the same descriptor entry as described above. If it is not Due to this preload of the main bundle and the caching behavior of this method, controls in such a library still can use the synchronous variant of |
getLoadedLibraries |
Returns a map of library info objects for all currently loaded libraries, keyed by their names. The structure of the library info objects matches the structure of the info object that the #initLibrary method expects. Only property names documented with Note: The returned info objects must not be modified. They might be a living copy of the internal data (for efficiency reasons) and the framework is not prepared to handle modifications to these objects. |
getMessageManager |
Returns the active |
sap.ui.core.Core.getMetadata |
Returns a metadata object for class sap.ui.core.Core. |
getModel |
Get the model with the given model name. The name can be omitted to reference the default model or it must be a non-empty string. Note: to be compatible with future versions of this API, applications must not use the value |
getRenderManager |
Since 0.15.0 Replaced by <code>createRenderManager()</code>
|
getRootComponent |
Returns the instance of the root component (if exists).
Since 1.95 Please use {@link module:sap/ui/core/ComponentSupport} instead. See also {@link topic:82a0fcecc3cb427c91469bc537ebdddf Declarative API for Initial Components}.
|
getStaticAreaRef |
Returns the static, hidden area DOM element belonging to this core instance. It can be used e.g. for hiding elements like Popups, Shadow, Blocklayer etc. If it is not yet available, a DIV is created and appended to the body. |
getTemplate |
Returns the registered template for the given id, if any.
Since 1.29.1 Require 'sap/ui/core/tmpl/Template' and use {@link sap.ui.core.tmpl.Template.byId Template.byId} instead.
|
getUIArea |
Returns the UIArea with the given ID or that belongs to the given DOM element. |
getUIDirty |
Returns |
hasModel |
Check if a Model is set to the core |
includeLibraryTheme |
Includes a library theme into the current page (if a variant is specified it will include the variant library theme) |
initLibrary |
Provides the framework with information about a library. This method is intended to be called exactly once while the main module of a library (its When the Side EffectsWhile analyzing the
Last but not least, higher layer frameworks might want to include their own metadata for libraries. The property Relationship to Descriptor for Libraries (manifest.json)The information contained in When the |
isInitialized |
Returns true if the Core has already been initialized. This means that instances of RenderManager etc. do already exist and the init event has already been fired (and will not be fired again). |
isLocked |
Returns the locked state of the |
isMobile |
Check if the script is running on mobile |
isStaticAreaRef |
Used to find out whether a certain DOM element is the static area |
isThemeApplied |
Returns true, if the styles of the current theme are already applied, false otherwise. This function must not be used before the init event of the Core. If the styles are not yet applied a theme changed event will follow when the styles will be applied. |
loadLibraries |
Loads a set of libraries, preferably asynchronously. The module loading is still synchronous, so if a library loads additional modules besides its library.js file, those modules might be loaded synchronously by the library.js The async loading is only supported by the means of the library-preload.js(on) files, so if a library doesn't provide a preload or when the preload is deactivated (configuration, debug mode) then this API falls back to synchronous loading. However, the contract (Promise) remains valid and a Promise will be returned if async is specified - even when the real loading is done synchronously. |
loadLibrary |
Loads the given library and its dependencies and makes its content available to the application. What it doesWhen library preloads are not suppressed for the given library, then a library-preload bundle will be loaded for it. By default, the bundle will be loaded synchronously (for compatibility reasons). Only when the optional parameter After preloading the bundle, dependency information from the bundle is evaluated and any missing libraries are also preloaded. Only then the library entry module (named When the optional parameter sap.ui.loader.config({ paths: { "lib/with/slashes": vUrl } }); When the given library has been loaded already, no further action will be taken, especially, a given URL will not be registered! In the case of asynchronous loading, a Promise will be returned, but will be resolved immediately. When to useFor applications that follow the best practices and use components with component descriptors (manifest.json), the framework will load all declared mandatory libraries and their dependencies automatically before instantiating the application component. The same is true for libraries that are listed in the bootstrap configuration (e.g. with the attribute Only when an app declares a library to be a lazy library dependency or when code does not use descriptors at all, then an explicit call to For example, when an app uses a heavy-weight charting library that shouldn't be loaded during startup, it can declare it as "lazy" and load it just before it loads and displays a view that uses the charting library: sap.ui.getCore().loadLibrary("heavy.charting", {async: true}) .then(function() { View.create({ name: "myapp.views.HeavyChartingView", type: ViewType.XML }); }); |
lock |
Locks the Core. No browser events are dispatched to the controls. Lock should be called before and after the DOM is modified for rendering, roundtrips... Exceptions might be the case for asynchronous UI behavior |
notifyContentDensityChanged |
Triggers a realignment of controls This method should be called after changing the cozy/compact CSS class of a DOM element at runtime, for example at the |
registerPlugin |
Registers a Plugin to the Plugin object need to implement two methods:
Since 1.73 Plugins never have been meant as a public offering, but were intended for internal usage only. They unfortunately allow access to all internals of the Core and therefore break encapsulation and hinder evolution of the Core. The most common use case of accessing the set of all controls/elements or all components can now be addressed by using the APIs {@link sap.ui.core.Element.registry} or {@link sap.ui.core.Component.registry}, respectively. Future refactorings of the Core will only take existing plugins in the OpenUI5 repository into account.
|
setModel |
Sets or unsets a model for the given model name. The When Any change (new model, removed model) is propagated to all existing UIAreas and their descendants as long as a descendant doesn't have its own model set for the given name. Note: to be compatible with future versions of this API, applications must not use the value |
setRoot |
Implicitly creates a new
Since 1.1 use {@link sap.ui.core.Control#placeAt oControl.placeAt(oDomRef, "only")} instead.
|
setThemeRoot |
Defines the root directory from below which UI5 should load the theme with the given name. Optionally allows restricting the setting to parts of a theme covering specific control libraries. Example: sap.ui.getCore().setThemeRoot("my_theme", "https://mythemeserver.com/allThemes"); sap.ui.getCore().applyTheme("my_theme"); will cause the following file to be loaded (assuming that the bootstrap is configured to load libraries https://mythemeserver.com/allThemes/sap/ui/core/themes/my_theme/library.css https://mythemeserver.com/allThemes/sap/ui/layout/themes/my_theme/library.css https://mythemeserver.com/allThemes/sap/m/themes/my_theme/library.css If parts of the theme are at different locations (e.g. because you provide a standard theme like "sap_belize" for a custom control library and this self-made part of the standard theme is at a different location than the UI5 resources), you can also specify for which control libraries the setting should be used, by giving an array with the names of the respective control libraries as second parameter: sap.ui.getCore().setThemeRoot("sap_belize", ["my.own.library"], "https://mythemeserver.com/allThemes"); This will cause the Belize theme to be loaded from the UI5 location for all standard libraries. Resources for styling the https://openui5.hana.ondemand.com/resources/sap/ui/core/themes/sap_belize/library.css https://openui5.hana.ondemand.com/resources/sap/ui/layout/themes/sap_belize/library.css https://openui5.hana.ondemand.com/resources/sap/m/themes/sap_belize/library.css https://mythemeserver.com/allThemes/my/own/library/themes/sap_belize/library.css If the custom theme should be loaded initially (via bootstrap attribute), the |
unlock |
Unlocks the Core. Browser events are dispatched to the controls again after this method is called. |
unregisterPlugin |
Unregisters a Plugin out of the
Since 1.73 Plugins never have been meant as a public offering, but were intended for internal usage only. They unfortunately allow access to all internals of the Core and therefore break encapsulation and hinder evolution of the Core. The most common use case of accessing the set of all controls/elements or all components can now be addressed by using the APIs {@link sap.ui.core.Element.registry} or {@link sap.ui.core.Component.registry}, respectively. Future refactorings of the Core will only take existing plugins in the OpenUI5 repository into account.
|
Enforces an immediate update of the visible UI (aka "rendering").
In general, applications should avoid calling this method and instead let the framework manage any necessary rendering.
Applies the theme with the given name (by loading the respective style sheets, which does not disrupt the application).
By default, the theme files are expected to be located at path relative to the respective control library ([libraryLocation]/themes/[themeName]). Different locations can be configured by using the method setThemePath() or by using the second parameter "sThemeBaseUrl" of applyTheme(). Usage of this second parameter is a shorthand for setThemePath and internally calls setThemePath, so the theme location is then known.
sThemeBaseUrl is a single URL to specify the default location of all theme files. This URL is the base folder below which the control library folders are located. E.g. if the CSS files are not located relative to the root location of UI5, but instead they are at locations like http://my.server/myapp/resources/sap/ui/core/themes/my_theme/library.css then the URL that needs to be given is: http://my.server/myapp/resources All theme resources are then loaded from below this folder - except if for a certain library a different location has been registered.
If the theme resources are not all either below this base location or with their respective libraries, then setThemePath must be used to configure individual locations.
Param | Type | DefaultValue | Description |
---|---|---|---|
sThemeName | string |
the name of the theme to be loaded |
|
sThemeBaseUrl | string |
the (optional) base location of the theme |
Registers a listener for control events.
When called, the context of the listener (its this
) will be bound to oListener
if specified, otherwise it will be bound to a dummy event provider object.
Param | Type | DefaultValue | Description |
---|---|---|---|
fnFunction | function |
Callback to be called for each control event |
|
oListener | object |
Optional context object to call the callback on |
Attaches event handler fnFunction
to the formatError event of sap.ui.core.Core
.
When called, the context of the listener (its this
) will be bound to oListener
if specified, otherwise it will be bound to a dummy event provider object.
Please note that this event is a bubbling event and may already be canceled before reaching the core.
Param | Type | DefaultValue | Description |
---|---|---|---|
fnFunction | function |
The function to be called, when the event occurs |
|
oListener | object |
Context object to call the event handler with. Defaults to a dummy event provider object |
Registers a given function that is executed after the framework has been initialized.
The given function will either be called as soon as the framework has been initialized or, if it has been initialized already, it will be called immediately.
More information about the initialization process and the steps it consists of can be found in the documentation topic "Initialization Process".
Param | Type | DefaultValue | Description |
---|---|---|---|
fnFunction | function |
Function to be after initialization of the framework |
Registers a given function that is executed after the framework has been initialized.
The method is executed only once and only if the framework has not been initialized already. This could be checked by calling #isInitialized, but in most cases it is more convenient to use #attachInit instead. This guarantees that the given function is executed exactly once, independent of the state of the framework.
Param | Type | DefaultValue | Description |
---|---|---|---|
fnFunction | function |
Function that is called after initialization of the framework |
Registers a listener to the central interval timer.
When called, the context of the listener (its this
) will be bound to oListener
if specified, otherwise it will be bound to the interval timer instance.
Param | Type | DefaultValue | Description |
---|---|---|---|
fnFunction | function |
Callback to be called periodically |
|
oListener | object |
Optional context object to call the callback on |
Register a listener for the localizationChanged event.
When called, the context of the listener (its this
) will be bound to oListener
if specified, otherwise it will be bound to a dummy event provider object.
Param | Type | DefaultValue | Description |
---|---|---|---|
fnFunction | function |
Callback to be called when the event occurs |
|
oListener | object |
Context object to call the function on |
Attaches event handler fnFunction
to the parseError event of sap.ui.core.Core
.
When called, the context of the listener (its this
) will be bound to oListener
if specified, otherwise it will be bound to a dummy event provider object.
Please note that this event is a bubbling event and may already be canceled before reaching the core.
Param | Type | DefaultValue | Description |
---|---|---|---|
oData | object |
An application-specific payload object that will be passed to the event handler along with the event object when firing the event |
|
fnFunction | function |
The function to be called, when the event occurs |
|
oListener | object |
Context object to call the event handler with. Defaults to a dummy event provider object |
Attaches event handler fnFunction
to the ThemeChanged event of this sap.ui.core.Core
.
When called, the context of the event handler (its this
) will be bound to oListener
if specified, otherwise it will be bound to a dummy event provider object.
Param | Type | DefaultValue | Description |
---|---|---|---|
fnFunction | function |
The function to be called, when the event occurs |
|
oListener | object |
Context object to call the event handler with. Defaults to a dummy event provider object |
Attaches event handler fnFunction
to the validationError event of sap.ui.core.Core
.
When called, the context of the listener (its this
) will be bound to oListener
if specified, otherwise it will be bound to a dummy event provider object.
Please note that this event is a bubbling event and may already be canceled before reaching the core.
Param | Type | DefaultValue | Description |
---|---|---|---|
oData | object |
An application-specific payload object that will be passed to the event handler along with the event object when firing the event |
|
fnFunction | function |
The function to be called, when the event occurs |
|
oListener | object |
Context object to call the event handler with. Defaults to a dummy event provider object |
Attaches event handler fnFunction
to the validationSuccess event of sap.ui.core.Core
.
When called, the context of the listener (its this
) will be bound to oListener
if specified, otherwise it will be bound to a dummy event provider object.
Please note that this event is a bubbling event and may already be canceled before reaching the core.
Param | Type | DefaultValue | Description |
---|---|---|---|
oData | object |
The object, that should be passed along with the event-object when firing the event |
|
fnFunction | function |
The function to be called, when the event occurs |
|
oListener | object |
Context object to call the event handler with. Defaults to a dummy event provider object |
Returns a list of all controls with a field group ID. See Control.prototype.checkFieldGroupIds for a description of the vFieldGroupIds
parameter.
Param | Type | DefaultValue | Description |
---|---|---|---|
vFieldGroupIds | string string[] |
ID of the field group or an array of field group IDs to match |
Returns the registered element with the given ID, if any.
The ID must be the globally unique ID of an element, the same as returned by oElement.getId()
.
When the element has been created from a declarative source (e.g. XMLView), that source might have used a shorter, non-unique local ID. A search for such a local ID cannot be executed with this method. It can only be executed on the corresponding scope (e.g. on an XMLView instance), by using the View#byId method of that scope.
Param | Type | DefaultValue | Description |
---|---|---|---|
sId | sap.ui.core.ID null undefined |
ID of the element to search for |
Creates a component with the provided id and settings.
When the optional parameter sUrl
is given, then all request for resources of the library will be redirected to the given URL. This is convenience for a call to
sap.ui.loader.config({ paths: { "lib/with/slashes": vUrl } });
Param | Type | DefaultValue | Description |
---|---|---|---|
vComponent | string object |
name of the component to import or object containing all needed parameters |
|
name | string |
name of the component to import |
|
url | string |
URL to load the component from |
|
id | string |
ID for the component instance |
|
settings | object |
settings object for the component |
|
componentData | any |
user specific data which is available during the whole lifecycle of the component |
|
sUrl | string |
the URL to load the component from |
|
sId | string |
the ID for the component instance |
|
mSettings | object |
the settings object for the component |
Returns a new instance of the RenderManager for exclusive use by the caller.
The caller must take care to destroy the render manager when it is no longer needed. Calling this method before the Core has been initialized, is not recommended.
Creates a new UIArea.
Param | Type | DefaultValue | Description |
---|---|---|---|
oDomRef | string Element |
a DOM Element or ID string of the UIArea |
Unregisters a listener for control events.
The passed function and listener object must match the ones used for event registration.
Param | Type | DefaultValue | Description |
---|---|---|---|
fnFunction | function |
Function to unregister |
|
oListener | object |
Context object on which the given function had to be called |
Detaches event handler fnFunction
from the formatError event of sap.ui.core.Core
.
The passed function and listener object must match the ones used for event registration.
Param | Type | DefaultValue | Description |
---|---|---|---|
fnFunction | function |
The callback function to unregister |
|
oListener | object |
Context object on which the given function had to be called |
Unregisters a listener for the central interval timer.
A listener will only be unregistered if the same function/context combination is given as in the attachIntervalTimer
call.
Param | Type | DefaultValue | Description |
---|---|---|---|
fnFunction | function |
function to unregister |
|
oListener | object |
context object given during registration |
Unregister a listener from the localizationChanged event.
The listener will only be unregistered if the same function/context combination is given as in the call to attachLocalizationListener
.
Param | Type | DefaultValue | Description |
---|---|---|---|
fnFunction | function |
Callback to be deregistered |
|
oListener | object |
Context object on which the given function had to be called |
Detaches event handler fnFunction
from the parseError event of sap.ui.core.Core
.
The passed function and listener object must match the ones used for event registration.
Param | Type | DefaultValue | Description |
---|---|---|---|
fnFunction | function |
The callback function to unregister. |
|
oListener | object |
Context object on which the given function had to be called |
Detaches event handler fnFunction
from the ThemeChanged event of this sap.ui.core.Core
.
The passed function and listener object must match the ones used for event registration.
Param | Type | DefaultValue | Description |
---|---|---|---|
fnFunction | function |
The function to be called, when the event occurs |
|
oListener | object |
Object on which the given function had to be called. |
Detaches event handler fnFunction
from the validationError event of sap.ui.core.Core
.
The passed function and listener object must match the ones used for event registration.
Param | Type | DefaultValue | Description |
---|---|---|---|
fnFunction | function |
The callback function to unregister |
|
oListener | object |
Context object on which the given function had to be called |
Detaches event handler fnFunction
from the validationSuccess event of sap.ui.core.Core
.
The passed function and listener object must match the ones used for event registration.
Param | Type | DefaultValue | Description |
---|---|---|---|
fnFunction | function |
The function to be called, when the event occurs |
|
oListener | object |
Context object on which the given function had to be called |
Creates a new subclass of class sap.ui.core.Core 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.Object.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 |
Fires event formatError to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
oParameters | object |
Parameters to pass along with the event. |
|
element | sap.ui.core.Element |
Element where the format error occurred |
|
property | string |
Name of the property of the element where the format error occurred |
|
type | sap.ui.model.Type |
Type of the property |
|
newValue | any |
Value of the property which was entered when the format error occurred |
|
oldValue | any |
Value of the property which was present before a new value was entered (before the format error) |
|
exception | object |
Exception object which occurred and has more information about the format error |
Fires event parseError to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
oParameters | object |
Parameters to pass along with the event. |
|
element | sap.ui.core.Element |
Element where the parse error occurred |
|
property | string |
Name of the property of the element where the parse error occurred |
|
type | sap.ui.model.Type |
Type of the property |
|
newValue | object |
Value of the property which was entered when the parse error occurred |
|
oldValue | object |
Value of the property which was present before a new value was entered (before the parse error) |
|
exception | object |
Exception object which occurred and has more information about the parse error |
Fires event validationError to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
oParameters | object |
Parameters to pass along with the event. |
|
element | sap.ui.core.Element |
The Element where the validation error occurred |
|
property | string |
Property name of the element where the validation error occurred |
|
type | sap.ui.model.Type |
Type of the property |
|
newValue | object |
Value of the property which was entered when the validation error occurred |
|
oldValue | object |
Value of the property which was present before a new value was entered (before the validation error) |
|
exception | object |
Exception object which occurred and has more information about the validation error |
Fires event validationSuccess to attached listeners.
Expects following event parameters:
sap.ui.core.Element
string
string
object
object
Param | Type | DefaultValue | Description |
---|---|---|---|
oParameters | object |
Parameters to pass along with the event |
Returns the instance of the application (if exists).
Returns the registered component for the given id, if any.
Param | Type | DefaultValue | Description |
---|---|---|---|
sId | string |
Returns the registered element for the given ID, if any.
Param | Type | DefaultValue | Description |
---|---|---|---|
sId | sap.ui.core.ID null undefined |
ID of the control to retrieve |
Returns the registered element for the given ID, if any.
Param | Type | DefaultValue | Description |
---|---|---|---|
sId | sap.ui.core.ID null undefined |
ID of the element to retrieve |
Retrieves a resource bundle for the given library and locale.
If only one argument is given, it is assumed to be the libraryName. The locale then falls back to the current session locale. If no argument is given, the library also falls back to a default: "sap.ui.core".
When the App Descriptor for the library is available without further request (manifest.json has been preloaded) and when the App Descriptor is at least of version 1.9.0 or higher, then this method will evaluate the App Descriptor entry "sap.ui5" / "library" / "i18n"
.
true
, a bundle with the default name "messagebundle.properties" will be loadedfalse
, no bundle will be loaded and the result will be undefined
Once a resource bundle for a library has been loaded, it will be cached by this method. Further calls for the same library and locale won't create new requests, but return the already loaded bundle. There's therefore no need for control code to cache the returned bundle for a longer period of time. Not further caching the result also prevents stale texts after a locale change.
The asynchronous variant of #loadLibrary will evaluate the same descriptor entry as described above. If it is not false
, loading the main resource bundle of the library will become a subtask of the asynchronous loading of the library.
Due to this preload of the main bundle and the caching behavior of this method, controls in such a library still can use the synchronous variant of getLibraryResourceBundle
in their API, behavior and rendering code. Only when the bundle is needed at module execution time (by top level code in a control module), then the asynchronous variant of this method should be preferred.
Param | Type | DefaultValue | Description |
---|---|---|---|
sLibraryName | string | 'sap.ui.core' |
Name of the library to retrieve the bundle for |
sLocale | string |
Locale to retrieve the resource bundle for |
|
bAsync | boolean | false |
Whether the resource bundle is loaded asynchronously |
Returns a map of library info objects for all currently loaded libraries, keyed by their names.
The structure of the library info objects matches the structure of the info object that the #initLibrary method expects. Only property names documented with initLibrary
should be accessed, any additional properties might change or disappear in future. When a property does not exists, its default value (as documented with initLibrary
) should be assumed.
Note: The returned info objects must not be modified. They might be a living copy of the internal data (for efficiency reasons) and the framework is not prepared to handle modifications to these objects.
Get the model with the given model name.
The name can be omitted to reference the default model or it must be a non-empty string.
Note: to be compatible with future versions of this API, applications must not use the value null
, the empty string ""
or the string literals "null"
or "undefined"
as model name.
Param | Type | DefaultValue | Description |
---|---|---|---|
sName | string |
name of the model to be retrieved |
Returns the instance of the root component (if exists).
Returns the static, hidden area DOM element belonging to this core instance.
It can be used e.g. for hiding elements like Popups, Shadow, Blocklayer etc.
If it is not yet available, a DIV is created and appended to the body.
Returns the registered template for the given id, if any.
Param | Type | DefaultValue | Description |
---|---|---|---|
sId | string |
Returns the UIArea with the given ID or that belongs to the given DOM element.
Param | Type | DefaultValue | Description |
---|---|---|---|
o | string Element |
DOM element or ID of the UIArea |
Returns true
if there are any pending rendering tasks or when such rendering tasks are currently being executed.
Includes a library theme into the current page (if a variant is specified it will include the variant library theme)
Param | Type | DefaultValue | Description |
---|---|---|---|
sLibName | string |
the name of the UI library |
|
sVariant | string |
the variant to include (optional) |
|
sQuery | string |
to be used only by the Core |
Provides the framework with information about a library.
This method is intended to be called exactly once while the main module of a library (its library.js
module) is executing, typically at its begin. The single parameter oLibInfo
is an info object that describes the content of the library.
When the oLibInfo
has been processed, a normalized version of it will be kept and will be returned as library information in later calls to #getLoadedLibraries. Finally, initLibrary
fires (the currently private) #event:LibraryChanged event with operation 'add' for the newly loaded library.
While analyzing the oLibInfo
, the framework takes some additional actions:
interfaces
, they will be registered with the sap.ui.base.DataType class to make them available as aggregation types in managed objects.controls
or elements
, lazy stubs will be created for their constructor as well as for their static extend
and getMetadata
methods.noLibraryCSS
property, the library can be marked as 'theming-free'. Otherwise, the framework will add a <link> tag to the page's head, pointing to the library's theme-specific stylesheet. The creation of such a <link> tag can be suppressed with the global configuration option preloadLibCss
. It can contain a list of library names for which no stylesheet should be included. This is e.g. useful when an application merges the CSS for multiple libraries and already loaded the resulting stylesheet.dependencies
is specified in the info object, those libraries will be loaded synchronously by initLibrary
.library.js
module, the library should be additionally listed in the AMD dependencies.Last but not least, higher layer frameworks might want to include their own metadata for libraries. The property extensions
might contain such additional metadata. Its structure is not defined by the framework, but it is strongly suggested that each extension only occupies a single property in the extensions
object and that the name of that property contains some namespace information (e.g. library name that introduces the feature) to avoid conflicts with other extensions. The framework won't touch the content of extensions
but will make it available in the library info objects returned by #getLoadedLibraries.
The information contained in oLibInfo
is partially redundant to the content of the descriptor for the same library (its manifest.json
file). Future versions of UI5 might ignore the information provided in oLibInfo
and might evaluate the descriptor file instead. Library developers therefore should keep the information in both files in sync.
When the manifest.json
is generated from the .library
file (which is the default for UI5 libraries built with Maven), then the content of the .library
and library.js
files must be kept in sync.
Param | Type | DefaultValue | Description |
---|---|---|---|
oLibInfo | object |
Info object for the library |
|
name | string |
Name of the library; when given it must match the name by which the library has been loaded |
|
version | string |
Version of the library |
|
dependencies | string[] | [] |
List of libraries that this library depends on; names are in dot notation (e.g. "sap.ui.core") |
types | string[] | [] |
List of names of types that this library provides; names are in dot notation (e.g. "sap.ui.core.CSSSize") |
interfaces | string[] | [] |
List of names of interface types that this library provides; names are in dot notation (e.g. "sap.ui.core.PopupInterface") |
controls | string[] | [] |
Names of control types that this library provides; names are in dot notation (e.g. "sap.ui.core.ComponentContainer") |
elements | string[] | [] |
Names of element types that this library provides (excluding controls); names are in dot notation (e.g. "sap.ui.core.Item") |
noLibraryCSS | boolean | false |
Indicates whether the library doesn't provide / use theming. When set to true, no library.css will be loaded for this library |
extensions | object |
Potential extensions of the library metadata; structure not defined by the UI5 core framework. |
Returns true if the Core has already been initialized. This means that instances of RenderManager etc. do already exist and the init event has already been fired (and will not be fired again).
Used to find out whether a certain DOM element is the static area
Param | Type | DefaultValue | Description |
---|---|---|---|
oDomRef | object |
Returns true, if the styles of the current theme are already applied, false otherwise.
This function must not be used before the init event of the Core. If the styles are not yet applied a theme changed event will follow when the styles will be applied.
Loads a set of libraries, preferably asynchronously.
The module loading is still synchronous, so if a library loads additional modules besides its library.js file, those modules might be loaded synchronously by the library.js The async loading is only supported by the means of the library-preload.js(on) files, so if a library doesn't provide a preload or when the preload is deactivated (configuration, debug mode) then this API falls back to synchronous loading. However, the contract (Promise) remains valid and a Promise will be returned if async is specified - even when the real loading is done synchronously.
Param | Type | DefaultValue | Description |
---|---|---|---|
aLibraries | string[] |
set of libraries that should be loaded |
|
mOptions | object |
configuration options |
|
async | boolean | true |
whether to load the libraries async (default) |
preloadOnly | boolean | false |
whether to preload the libraries only (default is to require them as well) |
Loads the given library and its dependencies and makes its content available to the application.
When library preloads are not suppressed for the given library, then a library-preload bundle will be loaded for it. By default, the bundle will be loaded synchronously (for compatibility reasons). Only when the optional parameter vUrl
is given as true
or as a configuration object with a property of async:true
, then the bundle will be loaded asynchronously and a Promise
will be returned (preferred usage).
After preloading the bundle, dependency information from the bundle is evaluated and any missing libraries are also preloaded.
Only then the library entry module (named your/lib/library.js
) will be required and executed. The module is supposed to call sap.ui.getCore().initLibrary(...)
providing the framework with additional metadata about the library, e.g. its version, the set of contained enums, types, interfaces, controls and elements and whether the library requires CSS. If the library requires CSS, a <link> will be added to the page referring to the corresponding library.css
stylesheet for the library and the current theme.
When the optional parameter vUrl
is given as a string or when a configuration object is given with a non-empty, string-valued property url
, then that URL will be registered for the namespace of the library and all resources will be loaded from that location. This is convenience for a call like
sap.ui.loader.config({ paths: { "lib/with/slashes": vUrl } });
When the given library has been loaded already, no further action will be taken, especially, a given URL will not be registered! In the case of asynchronous loading, a Promise will be returned, but will be resolved immediately.
For applications that follow the best practices and use components with component descriptors (manifest.json), the framework will load all declared mandatory libraries and their dependencies automatically before instantiating the application component.
The same is true for libraries that are listed in the bootstrap configuration (e.g. with the attribute data-sap-ui-libs
). They will be loaded before the init
event of the UI5 Core is fired.
Only when an app declares a library to be a lazy library dependency or when code does not use descriptors at all, then an explicit call to loadLibrary
becomes necessary. The call should be made before artifacts (controls, elements, types, helpers, modules etc.) from the library are used or required. This allows the framework to optimize access to those artifacts.
For example, when an app uses a heavy-weight charting library that shouldn't be loaded during startup, it can declare it as "lazy" and load it just before it loads and displays a view that uses the charting library:
sap.ui.getCore().loadLibrary("heavy.charting", {async: true}) .then(function() { View.create({ name: "myapp.views.HeavyChartingView", type: ViewType.XML }); });
Param | Type | DefaultValue | Description |
---|---|---|---|
sLibrary | string |
Name of the library to load |
|
vUrl | string boolean object |
URL to load the library from or the async flag or a complex configuration object |
|
async | boolean |
Whether to load the library asynchronously |
|
url | string |
URL to load the library from |
Locks the Core. No browser events are dispatched to the controls.
Lock should be called before and after the DOM is modified for rendering, roundtrips... Exceptions might be the case for asynchronous UI behavior
Triggers a realignment of controls
This method should be called after changing the cozy/compact CSS class of a DOM element at runtime, for example at the <body>
tag. Controls can listen to the themeChanged event to realign their appearance after changing the theme. Changing the cozy/compact CSS class should then also be handled as a theme change. In more simple scenarios where the cozy/compact CSS class is added to a DOM element which contains only a few controls it might not be necessary to trigger the realigment of all controls placed in the DOM, for example changing the cozy/compact CSS class at a single control
Registers a Plugin to the sap.ui.core.Core
, which lifecycle will be managed (start and stop).
Plugin object need to implement two methods:
startPlugin(oCore)
: will be invoked, when the Plugin should start (as parameter the reference to the Core will be providedstopPlugin()
: will be invoked, when the Plugin should stopParam | Type | DefaultValue | Description |
---|---|---|---|
oPlugin | object |
reference to a Plugin object |
Sets or unsets a model for the given model name.
The sName
must either be undefined
(or omitted) or a non-empty string. When the name is omitted, the default model is set/unset.
When oModel
is null
or undefined
, a previously set model with that name is removed from the Core.
Any change (new model, removed model) is propagated to all existing UIAreas and their descendants as long as a descendant doesn't have its own model set for the given name.
Note: to be compatible with future versions of this API, applications must not use the value null
, the empty string ""
or the string literals "null"
or "undefined"
as model name.
Param | Type | DefaultValue | Description |
---|---|---|---|
oModel | sap.ui.model.Model |
the model to be set or |
|
sName | string |
the name of the model or |
Implicitly creates a new UIArea
(or reuses an exiting one) for the given DOM reference and adds the given control reference to the UIAreas content (existing content will be removed).
Param | Type | DefaultValue | Description |
---|---|---|---|
oDomRef | string Element |
a DOM Element or Id (string) of the UIArea |
|
oControl | sap.ui.base.Interface sap.ui.core.Control |
the Control that should be the added to the |
Defines the root directory from below which UI5 should load the theme with the given name. Optionally allows restricting the setting to parts of a theme covering specific control libraries.
Example:
sap.ui.getCore().setThemeRoot("my_theme", "https://mythemeserver.com/allThemes"); sap.ui.getCore().applyTheme("my_theme");
will cause the following file to be loaded (assuming that the bootstrap is configured to load libraries sap.m
and sap.ui.layout
):
https://mythemeserver.com/allThemes/sap/ui/core/themes/my_theme/library.css https://mythemeserver.com/allThemes/sap/ui/layout/themes/my_theme/library.css https://mythemeserver.com/allThemes/sap/m/themes/my_theme/library.css
If parts of the theme are at different locations (e.g. because you provide a standard theme like "sap_belize" for a custom control library and this self-made part of the standard theme is at a different location than the UI5 resources), you can also specify for which control libraries the setting should be used, by giving an array with the names of the respective control libraries as second parameter:
sap.ui.getCore().setThemeRoot("sap_belize", ["my.own.library"], "https://mythemeserver.com/allThemes");
This will cause the Belize theme to be loaded from the UI5 location for all standard libraries. Resources for styling the my.own.library
controls will be loaded from the configured location:
https://openui5.hana.ondemand.com/resources/sap/ui/core/themes/sap_belize/library.css https://openui5.hana.ondemand.com/resources/sap/ui/layout/themes/sap_belize/library.css https://openui5.hana.ondemand.com/resources/sap/m/themes/sap_belize/library.css https://mythemeserver.com/allThemes/my/own/library/themes/sap_belize/library.css
If the custom theme should be loaded initially (via bootstrap attribute), the themeRoots
property of the window["sap-ui-config"]
object must be used instead of calling sap.ui.getCore().setThemeRoot(...)
in order to configure the theme location early enough.
Param | Type | DefaultValue | Description |
---|---|---|---|
sThemeName | string |
Name of the theme for which to configure the location |
|
aLibraryNames | string[] |
Optional library names to which the configuration should be restricted |
|
sThemeBaseUrl | string |
Base URL below which the CSS file(s) will be loaded from |
|
bForceUpdate | boolean | false |
Force updating URLs of currently loaded theme |
Unlocks the Core.
Browser events are dispatched to the controls again after this method is called.
Unregisters a Plugin out of the sap.ui.core.Core
Param | Type | DefaultValue | Description |
---|---|---|---|
oPlugin | object |
reference to a Plugin object |