Final Class sap.ui.core.CoreModule: sap/ui/core/Core

extends Object

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) {
    ...
  });

Constructor Summary
Event Summary
formatError(oControlEvent)The 'formatError' event is fired when a value formatting fails.
localizationChanged(oEvent)Fired when any of the localization relevant configuration settings has changed (e.g.
parseError(oControlEvent)The 'parseError' event is fired when input parsing fails.
ThemeChanged(oControlEvent)Fired after a theme has been applied.
validationError(oControlEvent)The 'validationError' event is fired when validation of the input fails.
validationSuccess(oControlEvent)The 'validationSuccess' event is fired when a value validation was successfully completed.
Method Summary
sap.ui.core.Core.extend(sClassName, oClassInfo?, FNMetaImpl?)Creates a new subclass of class sap.ui.core.Core with name sClassName and enriches it with the information contained in oClassInfo.
sap.ui.core.Core.getMetadata()Returns a metadata object for class sap.ui.core.Core.
applyChanges()Enforces an immediate update of the visible UI (aka "rendering").
applyTheme(sThemeName, sThemeBaseUrl?)Applies the theme with the given name (by loading the respective style sheets, which does not disrupt the application).
attachControlEvent(fnFunction, oListener?)Registers a listener for control events.
attachFormatError(fnFunction, oListener?)Attach event-handler fnFunction to the 'formatError' event of sap.ui.core.Core.
attachInit(fnFunction)Registers a given function that is executed after the framework has been initialized.
attachIntervalTimer(fnFunction, oListener?)Registers a listener to the central interval timer.
attachLocalizationChanged(fnFunction, oListener)Register a listener for the localizationChanged event.
attachParseError(oData?, fnFunction, oListener?)Attach event-handler fnFunction to the 'parseError' event of sap.ui.core.Core.
attachThemeChanged(fnFunction, oListener?)Attach event-handler fnFunction to the ThemeChanged event of this sap.ui.core.Core.
attachValidationError(oData?, fnFunction, oListener?)Attach event-handler fnFunction to the 'validationError' event of sap.ui.core.Core.
attachValidationSuccess(oData?, fnFunction, oListener?)Attach event-handler fnFunction to the 'validationSuccess' event of sap.ui.core.Core.
byFieldGroupId(vFieldGroupIds?)Returns a list of all controls with a field group ID.
byId(sId)Returns the registered element for the given id, if any.
createComponent(vComponent, sUrl?, sId?, mSettings?)Creates a component with the provided id and settings.
createRenderManager()Returns a new instance of the RenderManager for exclusive use by the caller.
detachControlEvent(fnFunction, oListener?)Unregisters a listener for control events.
detachFormatError(fnFunction, oListener)Detach event-handler fnFunction from the 'formatError' event of sap.ui.core.Core.
detachIntervalTimer(fnFunction, oListener?)Unregisters a listener for the central interval timer.
detachLocalizationChanged(fnFunction, oListener)Unregister a listener from the localizationChanged event.
detachParseError(fnFunction, oListener)Detach event-handler fnFunction from the 'parseError' event of sap.ui.core.Core.
detachThemeChanged(fnFunction, oListener?)Detach event-handler fnFunction from the ThemeChanged event of this sap.ui.core.Core.
detachValidationError(fnFunction, oListener)Detach event-handler fnFunction from the 'validationError' event of sap.ui.core.Core.
detachValidationSuccess(fnFunction, oListener)Detach event-handler fnFunction from the 'validationSuccess' event of sap.ui.core.Core.
fireFormatError(mArguments?)Fire event formatError to attached listeners.
fireParseError(mArguments?)Fire event parseError to attached listeners.
fireThemeChanged(mParameters?)Fire event ThemeChanged to attached listeners.
fireValidationError(mArguments?)Fire event validationError to attached listeners.
fireValidationSuccess(mArguments?)Fire event validationSuccess to attached listeners.
getComponent(sId)Returns the registered component for the given id, if any.
getConfiguration()Returns the Configuration of the Core.
getCurrentFocusedControlId()Returns the Id of the control/element currently in focus.
getEventBus()Returns the event bus.
getLibraryResourceBundle(sLibraryName?, sLocale?)Retrieves a resource bundle for the given library and locale.
getLoadedLibraries()Returns a map of library info objects for all currently loaded libraries, keyed by their names.
getMessageManager()Returns the active MessageManager instance.
getModel(sName?)Get the model with the given model name.
getRootComponent()Returns the instance of the root component (if exists).
getStaticAreaRef()Returns the static, hidden area DOM element belonging to this core instance.
getUIArea(o)Returns a UIArea if the given ID/Element belongs to one.
getUIDirty()Returns true if there are any pending rendering tasks or when such rendering tasks are currently being executed.
hasModel()Check if a Model is set to the core
includeLibraryTheme(sLibName, sVariant?, sQuery?)Includes a library theme into the current page (if a variant is specified it will include the variant library theme)
initLibrary(oLibInfo)Provides the framework with information about a library.
isInitialized()Returns true if the Core has already been initialized.
isLocked()Returns the locked state of the sap.ui.core.Core
isMobile()Check if the script is running on mobile
isStaticAreaRef(oDomRef)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.
loadLibrary(sLibrary, vUrl?)Loads the given library and its dependencies and makes it available to the application.
lock()Locks the Core.
registerPlugin(oPlugin)Registers a Plugin to the sap.ui.core.Core, which lifecycle will be managed (start and stop).
setModel(oModel, sName?)Sets or unsets a model for the given model name.
setThemeRoot(sThemeName, aLibraryNames?, sThemeBaseUrl)Defines the root directory from below which UI5 should load the theme with the given name.
unlock()Unlocks the Core.
unregisterPlugin(oPlugin)Unregisters a Plugin out of the sap.ui.core.Core
attachInitEvent(fnFunction)Registers a given function that is executed after the framework has been initialized.
createUIArea(oDomRef)Creates a new sap.ui.core.UIArea.
getApplication()Returns the instance of the application (if exists).
getControl(sId)Returns the registered element for the given ID, if any.
getElementById(sId)Returns the registered element for the given ID, if any.
getTemplate(sId)Returns the registered template for the given id, if any.
setRoot(oDomRef, oControl)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).
Methods borrowed from class sap.ui.base.Object
Constructor Detail
new sap.ui.core.Core()
Event Detail
formatError(oControlEvent)
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.
Parameters:
sap.ui.base.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.getParameters
sap.ui.core.ElementoControlEvent.getParameters.elementThe Element where the format error occurred
stringoControlEvent.getParameters.propertyThe property name of the element where the format error occurred
sap.ui.model.TypeoControlEvent.getParameters.typeThe type of the property
objectoControlEvent.getParameters.newValueThe value of the property which was entered when the format error occurred
objectoControlEvent.getParameters.oldValueThe value of the property which was present before a new value was entered (before the format error)
objectoControlEvent.getParameters.exceptionThe exception object which occurred and has more information about the format error
localizationChanged(oEvent)

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

  • language - the language setting has changed
  • rtl - the character orientation mode (aka 'LTR/RTL mode') has changed
  • formatLocale - the format locale has changed

(there might be other, currently undocumented settings)

The value for each property will be the new corresponding setting.

Parameters:
sap.ui.base.EventoEvent
sap.ui.base.EventProvideroEvent.getSource
objectoEvent.getParameters
objectoEvent.getParameters.changesa map of the changed localization properties
parseError(oControlEvent)
The 'parseError' event is fired when input parsing fails.
Parameters:
sap.ui.base.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.getParameters
sap.ui.core.ElementoControlEvent.getParameters.elementThe Element where the parse error occurred
stringoControlEvent.getParameters.propertyThe property name of the element where the parse error occurred
sap.ui.model.TypeoControlEvent.getParameters.typeThe type of the property
objectoControlEvent.getParameters.newValueThe value of the property which was entered when the parse error occurred
objectoControlEvent.getParameters.oldValueThe value of the property which was present before a new value was entered (before the parse error)
objectoControlEvent.getParameters.exceptionThe exception object which occurred and has more information about the parse error
ThemeChanged(oControlEvent)

Fired after a theme has been applied.

More precisely, this event is fired when any of the following conditions is met:

  • the initially configured theme has been applied after core init
  • the theme has been changed and is now applied (see applyTheme)
  • a library has been loaded dynamically after core init (e.g. with sap.ui.getCore().loadLibrary(...) and the current theme has been applied for it
Parameters:
sap.ui.base.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.getParameters
stringoControlEvent.getParameters.themeTheme name
validationError(oControlEvent)
The 'validationError' event is fired when validation of the input fails.
Parameters:
sap.ui.base.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.getParameters
sap.ui.core.ElementoControlEvent.getParameters.elementThe Element where the validation error occurred
stringoControlEvent.getParameters.propertyThe property name of the element where the validation error occurred
sap.ui.model.TypeoControlEvent.getParameters.typeThe type of the property
objectoControlEvent.getParameters.newValueThe value of the property which was entered when the validation error occurred
objectoControlEvent.getParameters.oldValueThe value of the property which was present before a new value was entered (before the validation error)
objectoControlEvent.getParameters.exceptionThe exception object which occurred and has more information about the validation error
validationSuccess(oControlEvent)
The 'validationSuccess' event is fired when a value validation was successfully completed.
Parameters:
sap.ui.base.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.getParameters
sap.ui.core.ElementoControlEvent.getParameters.elementThe Element where the successful validation occurred
stringoControlEvent.getParameters.propertyThe property name of the element where the successfull validation occurred
sap.ui.model.TypeoControlEvent.getParameters.typeThe type of the property
objectoControlEvent.getParameters.newValueThe value of the property which was entered when the validation occurred
objectoControlEvent.getParameters.oldValueThe value of the property which was present before a new value was entered (before the validation)
Method Detail
sap.ui.core.Core.extend(sClassName, oClassInfo?, FNMetaImpl?): function

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.

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.Core.getMetadata(): sap.ui.base.Metadata
Returns a metadata object for class sap.ui.core.Core.
Returns:
sap.ui.base.MetadataMetadata object describing this class
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(sThemeName, sThemeBaseUrl?)

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.

Parameters:
stringsThemeNamethe name of the theme to be loaded
stringsThemeBaseUrl?the (optional) base location of the theme
attachControlEvent(fnFunction, oListener?)
Registers a listener for control events.
Parameters:
functionfnFunctioncallback to be called for each control event
objectoListener?optional context object to call the callback on.
attachFormatError(fnFunction, oListener?): sap.ui.core.Core
Attach event-handler fnFunction to the 'formatError' event of sap.ui.core.Core.
Please note that this event is a bubbling event and may already be canceled before reaching the core.
Parameters:
functionfnFunctionThe function to call, when the event occurs. This function will be called on the oListener-instance (if present) or in a 'static way'.
objectoListener?Object on which to call the given function. If empty, this Model is used.
Returns:
sap.ui.core.Corethis to allow method chaining
attachInit(fnFunction)

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.

Parameters:
functionfnFunctionFunction to be after initialization of the framework
Since:
1.13.2
attachIntervalTimer(fnFunction, oListener?)
Registers a listener to the central interval timer.
Parameters:
functionfnFunctioncallback to be called periodically
objectoListener?optional context object to call the callback on.
Since:
1.16.0
attachLocalizationChanged(fnFunction, oListener)
Register a listener for the localizationChanged event.
Parameters:
functionfnFunctioncallback to be called
objectoListenercontext object to cal lthe function on.
attachParseError(oData?, fnFunction, oListener?): sap.ui.core.Core
Attach event-handler fnFunction to the 'parseError' event of sap.ui.core.Core.
Please note that this event is a bubbling event and may already be canceled before reaching the core.
Parameters:
objectoData?The object, that should be passed along with the event-object when firing the event
functionfnFunctionThe function to call, when the event occurs. This function will be called on the oListener-instance (if present) or in a 'static way'.
objectoListener?Object on which to call the given function. If empty, this Model is used.
Returns:
sap.ui.core.Corethis to allow method chaining
attachThemeChanged(fnFunction, oListener?)
Attach event-handler fnFunction to the ThemeChanged event of this sap.ui.core.Core.
Parameters:
functionfnFunctionThe function to call, when the event occurs. This function will be called on the oListener-instance (if present) or in a 'static way'.
objectoListener?Object on which to call the given function.
attachValidationError(oData?, fnFunction, oListener?): sap.ui.core.Core
Attach event-handler fnFunction to the 'validationError' event of sap.ui.core.Core.
Please note that this event is a bubbling event and may already be canceled before reaching the core.
Parameters:
objectoData?The object, that should be passed along with the event-object when firing the event
functionfnFunctionThe function to call, when the event occurs. This function will be called on the oListener-instance (if present) or in a 'static way'.
objectoListener?Object on which to call the given function. If empty, this Model is used.
Returns:
sap.ui.core.Corethis to allow method chaining
attachValidationSuccess(oData?, fnFunction, oListener?): sap.ui.core.Core
Attach event-handler fnFunction to the 'validationSuccess' event of sap.ui.core.Core.
Please note that this event is a bubbling event and may already be canceled before reaching the core.
Parameters:
objectoData?The object, that should be passed along with the event-object when firing the event
functionfnFunctionThe function to call, when the event occurs. This function will be called on the oListener-instance (if present) or in a 'static way'.
objectoListener?Object on which to call the given function. If empty, this Model is used.
Returns:
sap.ui.core.Corethis to allow method chaining
byFieldGroupId(vFieldGroupIds?): sap.ui.core.Control[]
Returns a list of all controls with a field group ID. See Control.prototype.checkFieldGroupIds for a description of the vFieldGroupIds parameter.
Parameters:
string|string[]vFieldGroupIds?ID of the field group or an array of field group IDs to match
Returns:
sap.ui.core.Control[]The list of controls with matching field group IDs
Returns the registered element for the given id, if any.
Parameters:
stringsId
Returns:
sap.ui.core.Elementthe element for the given id
createComponent(vComponent, sUrl?, sId?, mSettings?)

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

  jQuery.sap.registerModulePath(sName, sUrl);

Parameters:
string|objectvComponentname of the component to import or object containing all needed parameters
stringvComponent.name?name of the component to import
stringvComponent.url?URL to load the component from
stringvComponent.id?ID for the component instance
objectvComponent.settings?settings object for the component
stringvComponent.componentData?user specific data which is available during the whole lifecycle of the component
stringsUrl?the URL to load the component from
stringsId?the ID for the component instance
objectmSettings?the settings object for the component
createRenderManager(): sap.ui.core.RenderManager

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.

Returns:
sap.ui.core.RenderManagerNew instance of the RenderManager
detachControlEvent(fnFunction, oListener?)

Unregisters a listener for control events.

A listener will only be unregistered if the same function/context combination is given as in the attachControlEvent call.

Parameters:
functionfnFunctionfunction to unregister
objectoListener?context object given during registration
detachFormatError(fnFunction, oListener): sap.ui.core.Core

Detach event-handler fnFunction from the 'formatError' event of sap.ui.core.Core.

The passed function and listener object must match the ones previously used for event registration.

Parameters:
functionfnFunctionThe callback function to unregister
objectoListenerObject on which the given function had to be called.
Returns:
sap.ui.core.Corethis to allow method chaining
detachIntervalTimer(fnFunction, oListener?)

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.

Parameters:
functionfnFunctionfunction to unregister
objectoListener?context object given during registration
Since:
1.16.0
detachLocalizationChanged(fnFunction, oListener)

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.

Parameters:
functionfnFunctioncallback to be deregistered
objectoListenercontext object given in a previous call to attachLocalizationChanged.
detachParseError(fnFunction, oListener): sap.ui.core.Core

Detach event-handler fnFunction from the 'parseError' event of sap.ui.core.Core.

The passed function and listener object must match the ones previously used for event registration.

Parameters:
functionfnFunctionThe callback function to unregister.
objectoListenerObject on which the given function had to be called.
Returns:
sap.ui.core.Corethis to allow method chaining
detachThemeChanged(fnFunction, oListener?)

Detach event-handler fnFunction from the ThemeChanged event of this sap.ui.core.Core.

The passed function and listener object must match the ones previously used for event registration.

Parameters:
functionfnFunctionThe function to call, when the event occurs.
objectoListener?Object on which the given function had to be called.
detachValidationError(fnFunction, oListener): sap.ui.core.Core

Detach event-handler fnFunction from the 'validationError' event of sap.ui.core.Core.

The passed function and listener object must match the ones previously used for event registration.

Parameters:
functionfnFunctionThe callback function to unregister
objectoListenerObject on which the given function had to be called.
Returns:
sap.ui.core.Corethis to allow method chaining
detachValidationSuccess(fnFunction, oListener): sap.ui.core.Core

Detach event-handler fnFunction from the 'validationSuccess' event of sap.ui.core.Core.

The passed function and listener object must match the ones previously used for event registration.

Parameters:
functionfnFunctionThe function to call, when the event occurs.
objectoListenerObject on which the given function had to be called.
Returns:
sap.ui.core.Corethis to allow method chaining
fireFormatError(mArguments?): sap.ui.core.Core

Fire event formatError to attached listeners.

Expects following event parameters:

  • 'element' of type sap.ui.core.Element
  • 'property' of type string
  • 'type' of type string
  • 'newValue' of type object
  • 'oldValue' of type object
  • 'exception' of type object
Parameters:
MapmArguments?the arguments to pass along with the event.
Returns:
sap.ui.core.Corethis to allow method chaining
fireParseError(mArguments?): sap.ui.core.Core

Fire event parseError to attached listeners.

Expects following event parameters:

  • 'element' of type sap.ui.core.Element
  • 'property' of type string
  • 'type' of type string
  • 'newValue' of type object
  • 'oldValue' of type object
  • 'exception' of type object
Parameters:
MapmArguments?the arguments to pass along with the event.
Returns:
sap.ui.core.Corethis to allow method chaining
fireThemeChanged(mParameters?)
Fire event ThemeChanged to attached listeners.
Parameters:
objectmParameters?Parameters to pass along with the event
objectmParameters.theme?Theme name
fireValidationError(mArguments?): sap.ui.core.Core

Fire event validationError to attached listeners.

Expects following event parameters:

  • 'element' of type sap.ui.core.Element
  • 'property' of type string
  • 'type' of type string
  • 'newValue' of type object
  • 'oldValue' of type object
  • 'exception' of type object
Parameters:
MapmArguments?the arguments to pass along with the event.
Returns:
sap.ui.core.Corethis to allow method chaining
fireValidationSuccess(mArguments?): sap.ui.core.Core

Fire event validationSuccess to attached listeners.

Expects following event parameters:

  • 'element' of type sap.ui.core.Element
  • 'property' of type string
  • 'type' of type string
  • 'newValue' of type object
  • 'oldValue' of type object
Parameters:
MapmArguments?the arguments to pass along with the event.
Returns:
sap.ui.core.Corethis to allow method chaining
getComponent(sId): sap.ui.core.Component
Returns the registered component for the given id, if any.
Parameters:
stringsId
Returns:
sap.ui.core.Componentthe component for the given id
getConfiguration(): sap.ui.core.Configuration
Returns the Configuration of the Core.
Returns:
sap.ui.core.Configurationthe Configuration of the current Core.
getCurrentFocusedControlId(): string
Returns the Id of the control/element currently in focus.
Returns:
stringthe Id of the control/element currently in focus.
getEventBus(): sap.ui.core.EventBus
Returns the event bus.
Returns:
sap.ui.core.EventBusthe event bus
Since:
1.8.0
getLibraryResourceBundle(sLibraryName?, sLocale?): jQuery.sap.util.ResourceBundle

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".

Parameters:
stringsLibraryName?, Default: 'sap.ui.core'name of the library to retrieve the bundle for
stringsLocale?locale to retrieve the resource bundle for
Returns:
jQuery.sap.util.ResourceBundlethe best matching resource bundle for the given parameters or undefined
getLoadedLibraries(): map

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.

Returns:
mapMap of library info objects keyed by the library names.
Returns the active MessageManager instance.
Returns:
sap.ui.core.message.MessageManager
Since:
1.33.0
getModel(sName?): sap.ui.model.Model

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.

Parameters:
string|undefinedsName?name of the model to be retrieved
Returns:
sap.ui.model.ModeloModel
getRootComponent(): sap.ui.core.Component
Returns the instance of the root component (if exists).
Returns:
sap.ui.core.Componentinstance of the current root component
getStaticAreaRef(): Element

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:
Elementthe static, hidden area DOM element belonging to this core instance.
Throws:
Erroran Error if the document is not yet ready
getUIArea(o): sap.ui.core.UIArea
Returns a UIArea if the given ID/Element belongs to one.
Parameters:
string|Elementoa DOM Element or ID string of the UIArea
Returns:
sap.ui.core.UIAreaa UIArea with a given id or dom ref.
getUIDirty(): boolean
Returns true if there are any pending rendering tasks or when such rendering tasks are currently being executed.
Returns:
booleantrue if there are pending (or executing) rendering tasks.
hasModel(): boolean
Check if a Model is set to the core
Returns:
booleantrue or false
includeLibraryTheme(sLibName, sVariant?, sQuery?)
Includes a library theme into the current page (if a variant is specified it will include the variant library theme)
Parameters:
stringsLibNamethe name of the UI library
stringsVariant?the variant to include (optional)
stringsQuery?to be used only by the Core
initLibrary(oLibInfo)

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.

Side Effects

While analyzing the oLibInfo, the framework takes some additional actions:

  • If the info object contains a list of interfaces, they will be registered with the sap.ui.base.DataType class to make them available as aggregation types in managed objects.
  • If the object contains a list of controls or elements, lazy stubs will be created for their constructor as well as for their static extend and getMetadata methods.
    Note: Future versions might abandon the concept of lazy stubs as it requires synchronous XMLHttpRequests which have been deprecated (see http://xhr.spec.whatwg.org). To be on the safe side, productive applications should always require any modules that they directly depend on.
  • With the 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 optionpreloadLibCss. 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.
  • If a list of library dependencies is specified in the info object, those libraries will be loaded synchronously by initLibrary.
    Note: Dependencies between libraries don't have to be modeled as AMD dependencies. Only when enums or types from an additional library are used in the coding of the 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.

Relationship to Descriptor for Libraries (manifest.json)

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.

Parameters:
objectoLibInfoInfo object for the library
stringoLibInfo.name?Name of the library; when given it must match the name by which the library has been loaded
stringoLibInfo.versionVersion of the library
string[]oLibInfo.dependencies?, Default: []List of libraries that this library depends on; names are in dot notation (e.g. "sap.ui.core")
string[]oLibInfo.types?, Default: []List of names of types that this library provides; names are in dot notation (e.g. "sap.ui.core.CSSSize")
string[]oLibInfo.interfaces?, Default: []List of names of interface types that this library provides; names are in dot notation (e.g. "sap.ui.core.PopupInterface")
string[]oLibInfo.controls?, Default: []Names of control types that this library provides; names are in dot notation (e.g. "sap.ui.core.ComponentContainer")
string[]oLibInfo.elements?, Default: []Names of element types that this library provides (excluding controls); names are in dot notation (e.g. "sap.ui.core.Item")
booleanoLibInfo.noLibraryCSS?, Default: falseIndicates whether the library doesn't provide / use theming. When set to true, no library.css will be loaded for this library
objectoLibInfo.extensions?Potential extensions of the library metadata; structure not defined by the UI5 core framework.
isInitialized(): boolean
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).
Returns:
booleanwhether the Core has already been initialized
isLocked(): boolean
Returns the locked state of the sap.ui.core.Core
Returns:
booleanlocked state
isMobile(): boolean
Check if the script is running on mobile
Returns:
booleantrue or false
isStaticAreaRef(oDomRef): boolean
Used to find out whether a certain DOM element is the static area
Parameters:
objectoDomRef
Returns:
booleanwhether the given DomRef is the StaticAreaRef
isThemeApplied(): boolean

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.

Returns:
booleanwhether the styles of the current theme are already applied
loadLibrary(sLibrary, vUrl?): Object|Promise

Loads the given library and its dependencies and makes it 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

  jQuery.sap.registerModulePath(sLibrary, vUrl); // or vUrl.url resp.

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.

Parameters:
stringsLibraryname of the library to load
string|boolean|objectvUrl?URL to load the library from or the async flag or a complex configuration object
stringvUrl.url?URL to load the library from
booleanvUrl.async?Whether to load the library asynchronously
Returns:
Object|PromiseAn info object for the library (sync) or a Promise (async)
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

registerPlugin(oPlugin)

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 provided
  • stopPlugin(): will be invoked, when the Plugin should stop
Parameters:
objectoPluginreference to a Plugin object
setModel(oModel, sName?): sap.ui.core.Core

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.

Parameters:
sap.ui.model.ModeloModelthe model to be set or null or undefined
stringsName?the name of the model or undefined
Returns:
sap.ui.core.Corethis to allow method chaining
setThemeRoot(sThemeName, aLibraryNames?, sThemeBaseUrl): sap.ui.core.Core

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 libs. 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.

Parameters:
stringsThemeNameName of the theme for which to configure the location
string[]aLibraryNames?Optional library names to which the configuration should be restricted
stringsThemeBaseUrlBase URL below which the CSS file(s) will be loaded from
Returns:
sap.ui.core.Corethe Core, to allow method chaining
Since:
1.10
unlock()

Unlocks the Core.

Browser events are dispatched to the controls again after this method is called.

unregisterPlugin(oPlugin)
Unregisters a Plugin out of the sap.ui.core.Core
Parameters:
objectoPluginreference to a Plugin object
attachInitEvent(fnFunction)

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.

Parameters:
functionfnFunctionFunction that is called after initialization of the framework
Deprecated API:
since 1.13.2 Register with the more convenient attachInit function instead
createUIArea(oDomRef): sap.ui.core.UIArea
Creates a new sap.ui.core.UIArea.
Parameters:
string|ElementoDomRefa DOM Element or ID string of the UIArea
Returns:
sap.ui.core.UIAreaa new UIArea
Deprecated API:
Use setRoot() instead!
getApplication(): sap.ui.app.Application
Returns the instance of the application (if exists).
Returns:
sap.ui.app.Applicationinstance of the current application
Deprecated API:
Since 1.15.1. The Component class is enhanced to take care about the Application code.
getControl(sId): sap.ui.core.Element
Returns the registered element for the given ID, if any.
Parameters:
stringsId
Returns:
sap.ui.core.Elementthe element for the given id
Deprecated API:
use sap.ui.core.Core.byId instead!
getElementById(sId): sap.ui.core.Element
Returns the registered element for the given ID, if any.
Parameters:
stringsId
Returns:
sap.ui.core.Elementthe element for the given id
Deprecated API:
use sap.ui.core.Core.byId instead!
getRenderManager()
Deprecated API:
Since version 0.15.0. Replaced by createRenderManager()
getTemplate(sId): sap.ui.core.Component
Returns the registered template for the given id, if any.
Parameters:
stringsId
Returns:
sap.ui.core.Componentthe template for the given id
Deprecated API:
Since 1.29.1 Require 'sap/ui/core/tmpl/Template' and use Template.byId instead.
setRoot(oDomRef, oControl)
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).
Parameters:
string|ElementoDomRefa DOM Element or Id (string) of the UIArea
sap.ui.base.Interface|sap.ui.core.ControloControlthe Control that should be the added to the UIArea.
Deprecated API:
Use function oControl.placeAt(oDomRef, "only") of sap.ui.core.Control instead.