namespace sap.ui

Control sample: sap.ui
Visiblity:
Available since: N/A
Module:
Application Component:

Nodes Overview

Node Description
sap.ui.suite

Suite controls library.


Methods Overview

Method Description
body>

The SAPUI5 Core Runtime.

sap.ui.Device

Device and Feature Detection API: Provides information about the used browser / device and cross platform support for certain events like media queries, orientation change or resizing.

sap.ui.loader

Provides access to UI5 loader configuration.

sap.ui.model

The SAPUI5 Data Binding API.

sap.ui.dom sap.ui.events sap.ui.performance sap.ui.security sap.ui.test sap.ui.util

Methods Overview

Method Description
sap.ui.component

Creates a new instance of a Component or returns the instance of an existing Component.

If you want to look up an existing Component you can call this function with a Component ID as parameter:

  var oComponent = sap.ui.component(sComponentId);

To create a new instance of a component you pass a component configuration object into this function:

  var oComponent = sap.ui.component({
    name: "my.Component",
    url: "my/component/location",
    id: "myCompId1"
  });

since: 1.56 use {@link sap.ui.core.Component.get Component.get} or {@link sap.ui.core.Component.create Component.create} instead. Note: {@link sap.ui.core.Component.create Component.create} does not support synchronous loading or the deprecated options <em>manifestFirst</em> and <em>manifestUrl</em>.
sap.ui.component.load

Load a component without instantiating it.

Provides support for loading components asynchronously by setting oConfig.async to true. In that case, the method returns a JavaScript 6 Promise that will be fulfilled with the component class after loading.

Using async = true doesn't necessarily mean that no more synchronous loading occurs. Both the framework as well as component implementations might still execute synchronous requests. The contract for async = true just allows to use async calls.

When a manifest.json is referenced in oConfig this manifest is not used for the derived instances of the Component class. The manifest/manifest url must be provided for every instance explicitly.

Since 1.27.0, when asynchronous loading is used, additional asyncHints can be provided. This parameter is only used internally by the UI5 framework and compatibility cannot be guaranteed. The parameter must not be used in productive code, except in code delivered by the UI5 teams.

  • oConfig.asyncHints.components : string[]a list of components needed by the current component and its subcomponents The framework will try to preload these components (their Component-preload.js) asynchronously, errors will be ignored. Please note that the framework has no knowledge about whether a Component provides a preload file or whether it is bundled in some library preload. If Components are listed in the hints section, they will be preloaded.
  • oConfig.asyncHints.libs : string[]libraries needed by the Component and its subcomponents. The framework will asynchronously load those libraries, if they're not loaded yet.
  • oConfig.asyncHints.preloadBundles : string[]a list of additional preload bundles The framework will try to load these bundles asynchronously before requiring the Component, errors will be ignored. The named modules must only represent preload bundles. If they are normal modules, their dependencies will be loaded with the normal synchronous request mechanism and performance might degrade.
  • oConfig.asyncHints.preloadOnly : boolean (default: false) whether only the preloads should be done, but not the loading of the Component controller class itself.

If Components and/or libraries are listed in the hints section, all the corresponding preload files will be requested in parallel. The constructor class will only be required after all of them are rejected or resolved. Instead of specifying just the name of a component or library in the hints, an object might be given that contains a mandatory name property and, optionally, an url that will be used for a registerModulePath and/or a lazy property. When lazy is set to a truthy value, only a necessary registerModulePath will be executed, but the corresponding component or lib won't be preloaded. For preload bundles, also an object might be given instead of a simple name, but there only the url property is supported, not the lazy property.

Note: so far, only the requests for the preload files (library and/or component) are executed asynchronously. If a preload is deactivated by configuration (e.g. debug mode), then remaining requests still might be synchronous.

since: 1.56 use {@link sap.ui.core.Component.load}
sap.ui.controller

Defines a controller class or creates an instance of an already defined controller class.

When a name and a controller implementation object is given, a new controller class of the given name is created. The members of the implementation object will be copied into each new instance of that controller class (shallow copy). Note: as the members are shallow copied, controller instances will share all object values. This might or might not be what applications expect.

If only a name is given, a new instance of the named controller class is returned.

since: 1.56 use {@link sap.ui.core.mvc.Controller.extend Controller.extend} to define the controller class and {@link sap.ui.core.mvc.Controller.create Controller.create} to create controller instances. For further information, see {@link sap.ui.core.mvc.Controller}.
sap.ui.define

Defines a JavaScript module with its ID, its dependencies and a module export value or factory.

The typical and only suggested usage of this method is to have one single, top level call to sap.ui.define in one JavaScript resource (file). When a module is requested by its module ID for the first time, the corresponding resource is determined from the ID and the current configuration. The resource will be loaded and executed which in turn will execute the top level sap.ui.define call.

If the module ID was omitted from that call, it will be substituted by the ID that was used to request the module. As a preparation step, the dependencies as well as their transitive dependencies, will be loaded. Then, the module value (its export) will be determined: if a static value (object, literal) was given as vFactory, that value will be the module value. If a function was given, that function will be called (providing the module exports of the declared dependencies as parameters to the function) and its return value will be used as module export value. The framework internally associates the resulting value with the module ID and provides it to the original requester of the module. Whenever the module is requested again, the same export value will be returned (modules are executed only once).

Example:
The following example defines a module, but doesn't hard code the module ID. If stored in a file 'sap/mylib/SomeClass.js', it can be requested with the ID 'sap/mylib/SomeClass'.

  sap.ui.define(['./Helper', 'sap/m/Bar'], function(Helper,Bar) {

    // create a new class
    var SomeClass = function() {};

    // add methods to its prototype
    SomeClass.prototype.foo = function() {

        // use a function from the dependency 'Helper' in the same package (e.g. 'sap/mylib/Helper' )
        var mSettings = Helper.foo();

        // create and return an sap.m.Bar (using its local name 'Bar')
        return new Bar(mSettings);

    }

    // return the class as module value
    return SomeClass;

  });

In another module or in an application HTML page, the sap.ui.require API can be used to load the sap/mylib/Something module and to work with it:

sap.ui.require(['sap/mylib/Something'], function(Something) {

  // instantiate a Something and call foo() on it
  new Something().foo();

});

Module Name Syntax

sap.ui.define uses a simplified variant of the unified resource name syntax for the module's own name as well as for its dependencies. The only difference to that syntax is, that for sap.ui.define and sap.ui.require, the extension (which always would be '.js') has to be omitted. Both methods always add this extension internally.

As a convenience, the name of a dependency can start with the segment './' which will be replaced by the name of the package that contains the currently defined module (relative name).

It is best practice to omit the name of the defined module (first parameter) and to use relative names for the dependencies whenever possible. This reduces the necessary configuration, simplifies renaming of packages and allows to map them to a different namespace.

Dependency to Modules

If a dependencies array is given, each entry represents the name of another module that the currently defined module depends on. All dependency modules are loaded before the export of the currently defined module is determined. The module export of each dependency module will be provided as a parameter to a factory function, the order of the parameters will match the order of the modules in the dependencies array.

Note: The order in which the dependency modules are executed is not defined by the order in the dependencies array! The execution order is affected by dependencies between the dependency modules as well as by their current state (whether a module already has been loaded or not). Neither module implementations nor dependents that require a module set must make any assumption about the execution order (other than expressed by their dependencies).

Note: A static module export (a literal provided to sap.ui.define) cannot depend on the module exports of the dependency modules as it has to be calculated before the dependencies are resolved. As an alternative, modules can define a factory function, calculate a static export value in that function, potentially based on the dependencies, and return the result as module export value. The same approach must be taken when the module export is supposed to be a function.

Asynchronous Contract

sap.ui.define is designed to support real Asynchronous Module Definitions (AMD) in future, although it internally still might use synchronous module loading, depending on configuration and context. However, callers of sap.ui.define must never rely on any synchronous behavior that they might observe in a specific test scenario.

For example, callers of sap.ui.define must not use the module export value immediately after invoking sap.ui.define:

  // COUNTER EXAMPLE HOW __NOT__ TO DO IT

  // define a class Something as AMD module
  sap.ui.define('Something', [], function() {
    var Something = function() {};
    return Something;
  });

  // DON'T DO THAT!
  // accessing the class _synchronously_ after sap.ui.define was called
  new Something();

Applications that need to ensure synchronous module definition or synchronous loading of dependencies MUST use the deprecated legacy APIs jQuery.sap.declare and jQuery.sap.require.

(No) Global References

To be in line with AMD best practices, modules defined with sap.ui.define should not make any use of global variables if those variables are also available as module exports. Instead, they should add dependencies to those modules and use the corresponding parameter of the factory function to access the module exports.

As the current programming model and the documentation of UI5 heavily rely on global names, there will be a transition phase where UI5 enables AMD modules and local references to module exports in parallel to the old global names. The fourth parameter of sap.ui.define has been added to support that transition phase. When this parameter is set to true, the framework provides two additional features

  1. Before the factory function is called, the existence of the global parent namespace for the current module is ensured
  2. The module export returned by the module's factory function will be automatically exported under the global name which is derived from the ID of the module

The parameter lets the framework know whether any of those two operations is needed or not. In future versions of UI5, a central configuration option is planned to suppress those 'exports'.

Third Party Modules

Although third party modules don't use UI5 APIs, they still can be listed as dependencies in a sap.ui.define call. They will be requested and executed like UI5 modules, but to make their exports available, so called shims have to be defined.

Note that UI5 temporarily deactivates an existing AMD loader while it executes third party modules known to support AMD. This sounds contradictorily at a first glance as UI5 wants to support AMD, but for now it is necessary to fully support UI5 applications that rely on global names for such modules.

For third-party modules that UI5 delivers (e.g. those in namespace sap/ui/thirdparty/), the necessary shims are defined by UI5 itself by executing the private module ui5loader-autoconfig.js during bootstrap.

Example:

  // module 'Something' wants to use third party library 'URI.js'
  // It is packaged by UI5 as non-UI5-module 'sap/ui/thirdparty/URI'
  // the following shim helps UI5 to correctly load URI.js and to retrieve the module's export value
  // Apps don't have to define that shim, it is already applied by ui5loader-autconfig.js
  sap.ui.loader.config({
    shim: {
      'sap/ui/thirdparty/URI': {
         amd: true, // URI.js reacts on an AMD loader, this flag lets UI5 temp. disable such loaders
         exports: 'URI' // name of the global variable under which URI.js exports its module value
      }
    }
  });

  // now the module can be retrieved like other modules
  sap.ui.define('Something', ['sap/ui/thirdparty/URI'], function(URIModuleValue) {

    new URIModuleValue(...); // same as the global 'URI' name: new URI(...)

    ...
  });

Differences to Standard AMD

The current implementation of sap.ui.define differs from the AMD specification (https://github.com/amdjs/amdjs-api) or from concrete AMD loaders like requireJS in several aspects:

  • The name sap.ui.define is different from the plain define. This has two reasons: first, it avoids the impression that sap.ui.define is an exact implementation of an AMD loader. And second, it allows the coexistence of an AMD loader (e.g. requireJS) and sap.ui.define in one application as long as UI5 or applications using UI5 are not fully prepared to run with an AMD loader. Note that the difference of the API names also implies that the UI5 loader can't be used to load 'real' AMD modules as they expect methods define and require to be available. Modules that use Unified Module Definition (UMD) syntax, can be loaded, but only when no AMD loader is present or when they expose their export also to the global namespace, even when an AMD loader is present (as e.g. jQuery does) or when a shim is defined for them using the amd:true flag (see example above)
  • Depending on configuration and the current context, sap.ui.define loads the dependencies of a module either synchronously using a sync XHR call + eval or asynchronously via script tags. The sync loading is basically a tribute to the synchronous history of UI5. There's no way for a module developer to enforce synchronous loading of the dependencies and on the long run, sync loading will be faded out. Applications that need to ensure synchronous loading of dependencies MUST use the deprecated legacy APIs like jQuery.sap.require.
  • sap.ui.define does not support plugins to use other file types, formats or protocols. It is not planned to support this in future
  • sap.ui.define does not support absolute URLs as module names (dependencies) nor does it allow module names that start with a slash. To refer to a module at an absolute URL, a resource root can be registered that points to that URL (or to a prefix of it).
  • sap.ui.define does not support the 'sugar' of requireJS where CommonJS style dependency declarations using sap.ui.require("something") are automagically converted into sap.ui.define dependencies before executing the factory function.

Limitations, Design Considerations

  • Limitation: as dependency management is not supported for Non-UI5 modules, the only way to ensure proper execution order for such modules currently is to rely on the order in the dependency array. Obviously, this only works as long as sap.ui.define uses synchronous loading. It will be enhanced when asynchronous loading is implemented.
  • It was discussed to enforce asynchronous execution of the module factory function (e.g. with a timeout of 0). But this would have invalidated the current migration scenario where a sync jQuery.sap.require call can load a sap.ui.define'ed module. If the module definition would not execute synchronously, the synchronous contract of the require call would be broken (default behavior in existing UI5 applications)
  • A single file must not contain multiple calls to sap.ui.define. Multiple calls currently are only supported in the so called 'preload' files that the UI5 merge tooling produces. The exact details of how this works might be changed in future implementations and are not part of the API contract


References:
  • https://github.com/amdjs/amdjs-api

sap.ui.extensionpoint

Creates 0..n UI5 controls from an ExtensionPoint.

One control if the ExtensionPoint is e.g. filled with a View, zero for extension points without configured extension and n controls for multi-root Fragments as extension.

In JSViews, this function allows both JSON notation in aggregation content as well as adding an extension point to an aggregation after the target control has already been instantiated. In the latter case the optional parameters oTargetControls and oTargetAggregation need to be specified.

since: 1.56 Use {@link sap.ui.core.ExtensionPoint.load} instead
sap.ui.fragment

Instantiate a Fragment - this method loads the Fragment content, instantiates it, and returns this content. The Fragment object itself is not an entity which has further significance beyond this constructor.

To instantiate an existing Fragment, call this method as: sap.ui.fragment(sName, sType, [oController]); The sName must correspond to a Fragment module which can be loaded via the module system (fragmentName + suffix ".fragment.[typeextension]") and which defines the Fragment content. If oController is given, the (event handler) methods referenced in the Fragment will be called on this controller. Note that Fragments may require a Controller to be given and certain methods to be available.

The Fragment types "XML", "JS" and "HTML" are available by default; additional Fragment types can be implemented and added using the sap.ui.core.Fragment.registerType() function.

Advanced usage: To instantiate a Fragment and give further configuration options, call this method as: sap.ui.fragment(oFragmentConfig, [oController]); The oFragmentConfig object can have the following properties: - "fragmentName": the name of the Fragment, as above - "fragmentContent": the definition of the Fragment content itself. When this property is given, any given name is ignored. The type of this property depends on the Fragment type, e.g. it could be a string for XML Fragments. - "type": the type of the Fragment, as above (mandatory) - "id": the ID of the Fragment (optional) Further properties may be supported by future or custom Fragment types. Any given properties will be forwarded to the Fragment implementation.

If you want to give a fixed ID for the Fragment, please use the advanced version of this method call with the configuration object or use the typed factories like sap.ui.xmlfragment(...) or sap.ui.jsfragment(...). Otherwise the Fragment ID is generated. In any case, the Fragment ID will be used as prefix for the ID of all contained controls.

since: 1.58 use {@link sap.ui.core.Fragment.load} instead
sap.ui.getCore

Retrieve the SAPUI5 Core instance for the current window.

sap.ui.getVersionInfo

Loads the version info file (resources/sap-ui-version.json) and returns it or if a library name is specified then the version info of the individual library will be returned.

In case of the version info file is not available an error will occur when calling this function.

since: 1.56 Use {@link module:sap/ui/VersionInfo.load} instead
sap.ui.htmlfragment

Instantiates an HTML-based Fragment.

To instantiate a fragment, call:

   sap.ui.htmlfragment([sId], sFragmentName, [oController]);
The fragment instance ID is optional and will be used as prefix for the ID of all contained controls. If no ID is passed, controls will not be prefixed. The sFragmentName must correspond to an HTML fragment which can be loaded via the module system (fragmentName + ".fragment.html") and which defines the fragment. If oController is given, the methods referenced in the fragment will be called on this controller. Note that fragments may require a controller to be given and certain methods to be available.

Advanced usage:

To instantiate a fragment and optionally directly give the HTML definition instead of loading it from a file, call:

    sap.ui.htmlfragment(oFragmentConfig, [oController]);
The oFragmentConfig object can either have a fragmentName or a fragmentContent property, but not both of them. fragmentContent can hold the fragment definition as XML string; if not given, fragmentName must be given and the fragment content definition is loaded by the module system. Again, if oController is given, any methods referenced in the fragment will be called on this controller.

since: 1.58 use {@link sap.ui.core.Fragment.load} instead
sap.ui.htmlview

Defines or creates an instance of a declarative HTML view.

The behavior of this method depends on the signature of the call and on the current context.

  • View Definition sap.ui.htmlview(sId, vView): Defines a view of the given name with the given implementation. sId must be the views name, vView must be an object and can contain implementations for any of the hooks provided by HTMLView
  • View Instantiation sap.ui.htmlview(sId?, vView): Creates an instance of the view with the given name (and id)
  • .

Any other call signature will lead to a runtime error. If the id is omitted in the second variant, an id will be created automatically.

since: 1.56 Use {@link sap.ui.core.mvc.HTMLView.create HTMLView.create} to create view instances
sap.ui.jsfragment

Defines OR instantiates an HTML-based fragment.

To define a JS fragment, call:

   sap.ui.jsfragment(sName, oFragmentDefinition)
where:
  • sName is the name by which this fragment later can be found and instantiated. If defined in its own file, in order to be found by the module loading system, the file location and name must correspond to sName (path + file name must be: fragmentName + ".fragment.js").
  • oFragmentDefinition is an object at least holding the createContent(oController) method which defines the fragment content. If given during instantiation, the createContent method receives a controller instance (otherwise, parameter oController will be undefined) and the return value must be one sap.ui.core.Control (which could have any number of children).

To instantiate a JS fragment, call:

   sap.ui.jsfragment([sId], sFragmentName, [oController]);
The fragment ID is optional (generated if not given) and the fragment implementation can use it to make contained controls unique (this depends on the implementation: some JS fragments may choose not to support multiple instances within one application and not use the ID prefixing). The sFragmentName must correspond to a JS fragment which can be loaded via the module system (sFragmentName converted to a path + ".fragment.js" suffix) and which defines the fragment. Or it can be a name that has been used earlier to define a fragment of that name. If oController is given, the methods referenced in the fragment will be called on this controller. Note that fragments may require a controller to be given and certain methods to be available.

since: 1.58 use {@link sap.ui.core.Fragment.load} instead
sap.ui.jsonview

Creates a JSON view of the given name and id.

The viewName must either correspond to a JSON module that can be loaded via the module system (viewName + suffix ".view.json") and which defines the view or it must be a configuration object for a view. The configuration object can have a viewName, viewContent and a controller property. The viewName behaves as described above, viewContent can hold the view description as JSON string or as object literal.

Note: when an object literal is given, it might be modified during view construction.

The controller property can hold a controller instance. If a controller instance is given, it overrides the controller defined in the view.

When property async is set to true, the view definition and the controller class (and its dependencies) will be loaded asynchronously. Any controls used in the view might be loaded sync or async, depending on the view configuration. Even when the view definition is provided as string or object tree, controller or controls might be loaded asynchronously. In any case, a view instance will be returned synchronously by this factory API, but its content (control tree) might appear only later. Also see sap.ui.core.mvc.View#loaded.

Like with any other control, an id is optional and will be created when missing.

since: 1.56 Use {@link sap.ui.core.mvc.JSONView.create JSONView.create} to create view instances
sap.ui.jsview

Defines or creates an instance of a JavaScript view.

The behavior of this method depends on the signature of the call and on the current context.

View Definition

  sap.ui.jsview(sId, vView);
Defines a view of the given name with the given implementation. sId must be the view's name, vView must be an object and can contain implementations for any of the hooks provided by JSView.

View Instantiation (deprecated)

  var oView = sap.ui.jsview(vView);
  var oView = sap.ui.jsview(vView, bASync);
  var oView = sap.ui.jsview(sId, vView);
  var oView = sap.ui.jsview(sId, vView, bAsync);
Creates an instance of the view with the given name (and id). If no view implementation has been defined for that view name, a JavaScript module with the same qualified name and with suffix .view.js will be loaded (required) and executed. The module should register a view definition on execution (1st. variant above).

If sId is omitted, an ID will be created automatically.

When bAsync has a truthy value, the view definition will be read asynchronously, if needed, but the (incomplete) view instance will be returned immediately.

Note: Any other call signature will lead to a runtime error.

since: 1.56 Use {@link sap.ui.core.mvc.View.extend View.extend} to define the view class and {@link sap.ui.core.mvc.View.create View.create} to create view instances
sap.ui.lazyRequire

Creates a lazy loading stub for a given class sClassName.

If the class has been loaded already, nothing is done. Otherwise a stub object or constructor and - optionally - a set of stub methods are created. All created stubs will load the corresponding module on execution and then delegate to their counterpart in the loaded module.

When no methods are given or when the list of methods contains the special name "new" (which is an operator can't be used as method name in JavaScript), then a stub constructor for class sClassName is created. Otherwise, a plain object is created.

Note: Accessing any stub as a plain object without executing it (no matter whether it is a function or an object) won't load the module and therefore most likely won't work as expected. This is a fundamental restriction of the lazy loader approach.

Note: As a side effect of this method, the namespace containing the given class is created immediately.

since: 1.56 Lazy loading enforces synchronous requests and therefore has been deprecated without a replacement. Instead of loading classes via lazy stubs, they should be required as dependencies of an AMD module (using {@link sap.ui.define}) or on demand with a call to {@link sap.ui.require}.
sap.ui.localResources

Redirects access to resources that are part of the given namespace to a location relative to the assumed application root folder.

Any UI5 managed resource (view, controller, control, JavaScript module, CSS file, etc.) whose resource name starts with sNamespace, will be loaded from an equally named subfolder of the application root folder. If the resource name consists of multiple segments (separated by a dot), each segment is assumed to represent an individual folder. In other words: when a resource name is converted to a URL, any dots ('.') are converted to slashes ('/').

Limitation: For the time being, the application root folder is assumed to be the same as the folder where the current page resides in.

Usage sample:

  // Let UI5 know that resources, whose name starts with "com.mycompany.myapp"
  // should be loaded from the URL location "./com/mycompany/myapp"
  sap.ui.localResources("com.mycompany.myapp");

  // The following call implicitly will use the mapping done by the previous line
  // It will load a view from ./com/mycompany/myapp/views/Main.view.xml
  View.create({ viewName : "com.mycompany.myapp.views.Main", type : ViewType.XML}).then(function(oView) {
      // do stuff
  });

When applications need a more flexible mapping between resource names and their location, they can use jQuery.sap.registerModulePath.

It is intended to make this configuration obsolete in future releases, but for the time being, applications must call this method when they want to store resources relative to the assumed application root folder.

References:

  • jQuery.sap.registerModulePath

since: 1.56 use <code>sap.ui.loader.config</code> instead.
sap.ui.namespace

Ensures that a given a namespace or hierarchy of nested namespaces exists in the current window.

since: 1.1 see {@link topic:c78c07c094e04ccfaab659378a1707c7 Creating Control and Class Modules}.
sap.ui.predefine
sap.ui.require

Resolves one or more module dependencies.

Synchronous Retrieval of a Single Module Export Value (Probing)

When called with a single string, that string is assumed to be the ID of an already loaded module and the export of that module is returned. If the module has not been loaded yet, or if it is a Non-UI5 module (e.g. third-party module) without a shim, undefined is returned.

This signature variant allows synchronous access to module exports without initiating module loading.

Sample:

  var JSONModel = sap.ui.require("sap/ui/model/json/JSONModel");

For modules that are known to be UI5 modules, this signature variant can be used to check whether the module has been loaded.

Asynchronous Loading of Multiple Modules

If an array of strings is given and (optionally) a callback function, then the strings are interpreted as module IDs and the corresponding modules (and their transitive dependencies) are loaded. Then the callback function will be called asynchronously. The module exports of the specified modules will be provided as parameters to the callback function in the same order in which they appeared in the dependencies array.

The return value for the asynchronous use case is undefined.

  sap.ui.require(['sap/ui/model/json/JSONModel', 'sap/ui/core/UIComponent'], function(JSONModel,UIComponent) {

    var MyComponent = UIComponent.extend('MyComponent', {
      ...
    });
    ...

  });

This method uses the same variation of the unified resource name syntax that sap.ui.define uses: module names are specified without the implicit extension '.js'. Relative module names are not supported.

sap.ui.require.toUrl

Calculates a URL from the provided resource name.

The calculation takes any configured ID mappings or resource paths into account (see config options map and paths. It also supports relative segments such as ./ and ../ within the path, but not at its beginning. If relative navigation would cross the root namespace (e.g. sap.ui.require.toUrl("../")) or when the resource name starts with a slash or with a relative segment, an error is thrown.

Note: toUrl does not resolve the returned URL; whether it is an absolute URL or a relative URL depends on the configured baseUrl and paths.

References:

  • https://github.com/amdjs/amdjs-api/wiki/require#requiretourlstring-

sap.ui.requireSync

Load a single module synchronously and return its module value.

Basically, this method is a combination of jQuery.sap.require and sap.ui.require. Its main purpose is to simplify the migration of modules to AMD style in those cases where some dependencies have to be loaded late (lazy) and synchronously.

The method accepts a single module name in the same syntax that sap.ui.define and sap.ui.require already use (a simplified variation of the unified resource name: slash separated names without the implicit extension '.js'). As for sap.ui.require, relative names (using ./ or ../) are not supported. If not loaded yet, the named module will be loaded synchronously and the export value of the module will be returned. While a module is executing, a value of undefined will be returned in case it is required again during that period of time (e.g. in case of cyclic dependencies).

Note: Applications are strongly encouraged to use this method only when synchronous loading is unavoidable. Any code that uses this method won't benefit from future performance improvements that require asynchronous module loading (e.g. HTTP/2). And such code never can comply with stronger content security policies (CSPs) that forbid 'eval'.

sap.ui.resource

Returns the URL of a resource that belongs to the given library and has the given relative location within the library. This is mainly meant for static resources like images that are inside the library. It is NOT meant for access to JavaScript modules or anything for which a different URL has been registered with jQuery.sap.registerModulePath(). For these cases use jQuery.sap.getModulePath(). It DOES work, however, when the given sResourcePath starts with "themes/" (= when it is a theme-dependent resource). Even when for this theme a different location outside the normal library location is configured.

since: 1.56.0 use <code>sap.ui.require.toUrl</code> instead.
sap.ui.setRoot

Displays the control tree with the given root inside the area of the given DOM reference (or inside the DOM node with the given ID) or in the given Control.

Example:

  <div id="SAPUI5UiArea"></div>
  <script>
    var oRoot = new sap.ui.commons.Label();
    oRoot.setText("Hello world!");
    sap.ui.setRoot("SAPUI5UiArea", oRoot);
  </script>

This is a shortcut for sap.ui.getCore().setRoot().

Internally, if a string is given that does not identify a UIArea or a control then implicitly a new UIArea is created for the given DOM reference and the given control is added.

since: 1.1 use {@link sap.ui.core.Control#placeAt Control#placeAt} instead.
sap.ui.template

Creates a Template for the given ID, DOM reference or a configuration object.

If no parameter is defined, this function makes a lookup of DOM elements which are specifying a type attribute. If the value of this type attribute matches a registered type then the content of this DOM element will be used to create a new Template instance.

If you want to lookup all kind of existing and known templates and parse them directly you can simply call:

  sap.ui.template();

To parse a concrete DOM element you can do so by using this function in the following way:

  sap.ui.template("theTemplateId");

Or you can pass the reference to a DOM element and use this DOM element as a source for the template:

  sap.ui.template(oDomRef);

The last option to use this function is to pass the information via a configuration object. This configuration object can be used to pass a context for the templating framework when compiling the template:

  var oTemplateById = sap.ui.template({
    id: "theTemplateId",
    context: { ... }
  });

  var oTemplateByDomRef = sap.ui.template({
    domref: oDomRef,
    context: { ... }
  });

It can also be used to load a template from another file:

  var oTemplate = sap.ui.template({
    id: "myTemplate",
    src: "myTemplate.tmpl"
  });

  var oTemplateWithContext = sap.ui.template({
    id: "myTemplate",
    src: "myTemplate.tmpl",
    context: { ... }
  });

since: 1.56 use an {@link sap.ui.core.mvc.XMLView XMLView} or {@link sap.ui.core.mvc.JSView JSView} instead.
sap.ui.templateview

Defines or creates an instance of a template view.

The behavior of this method depends on the signature of the call and on the current context.

  • View Definition sap.ui.templateview(sId, vView): Defines a view of the given name with the given implementation. sId must be the views name, vView must be an object and can contain implementations for any of the hooks provided by templateview
  • View Instantiation sap.ui.templateview(sId?, vView): Creates an instance of the view with the given name (and id)
  • .

Any other call signature will lead to a runtime error. If the id is omitted in the second variant, an id will be created automatically.

since: 1.56 use {@link sap.ui.core.mvc.XMLView} in combination with {@link topic:5ee619fc1370463ea674ee04b65ed83b XML Templating} instead
sap.ui.view

Creates a view of the given type, name and with the given ID.

since: 1.56 Use {@link sap.ui.core.mvc.View.extend View.extend} to define the view class and {@link sap.ui.core.mvc.View.create View.create} to create view instances
sap.ui.xmlfragment

Instantiates an XML-based Fragment.

To instantiate a fragment, call:

   sap.ui.xmlfragment([sId], sFragmentName, [oController]);
The fragment instance ID is optional and will be used as prefix for the ID of all contained controls. If no ID is passed, controls will not be prefixed. The sFragmentName must correspond to an XML fragment which can be loaded via the module system (fragmentName + ".fragment.xml") and which defines the fragment. If oController is given, the methods referenced in the fragment will be called on this controller.

Note that fragments may require a controller to be given and certain methods to be available.

Advanced usage:

To instantiate a fragment and optionally directly give the XML definition instead of loading it from a file, call:

    sap.ui.xmlfragment(oFragmentConfig, [oController]);
The oFragmentConfig object can either have a fragmentName or a fragmentContent property, but not both. fragmentContent can hold the fragment definition as XML string; if not given, fragmentName must be given and the fragment content definition is loaded via the module system. Again, if oController is given, the methods referenced in the fragment will be called on this controller.

since: 1.58 use {@link sap.ui.core.Fragment.load} instead
sap.ui.xmlview

Instantiates an XMLView of the given name and with the given ID.

The vView can either be the name of the module that contains the view definition or it can be a configuration object with properties viewName, viewContent and a controller property (more properties are described in the parameters section below).

If a viewName is given, it behaves the same as when vView is a string: the named resource will be loaded and parsed as XML. Alternatively, an already loaded view definition can be provided as viewContent, either as XML string or as an already parsed XML document. Exactly one of viewName and viewContent must be given, if none or both are given, an error will be reported. The controller property is optional and can hold a controller instance. When given, it overrides the controller class defined in the view definition.

When property async is set to true, the view definition and the controller class (and its dependencies) will be loaded asynchronously. Any controls used in the view might be loaded sync or async, depending on the processingMode. Even when the view definition is provided as string or XML Document, controller or controls might be loaded asynchronously. In any case a view instance will be returned synchronously by this factory API, but its content (control tree) might appear only later. Also see sap.ui.core.mvc.View#loaded.

Note: If an XML document is given, it might be modified during view construction.

Note: On root level, you can only define content for the default aggregation, e.g. without adding the <content> tag. If you want to specify content for another aggregation of a view like dependents, place it in a child control's dependents aggregation or add it by using sap.ui.core.mvc.XMLView#addDependent.

Note: If you enable caching, you need to take care of the invalidation via keys. Automatic invalidation takes only place if the UI5 version or the component descriptor (manifest.json) change. This is still an experimental feature and may experience slight changes of the invalidation parameters or the cache key format.

Like with any other control, sId is optional and an ID will be created automatically.

since: 1.56 Use {@link sap.ui.core.mvc.XMLView.create XMLView.create} to create view instances

sap.ui.component

Creates a new instance of a Component or returns the instance of an existing Component.

If you want to look up an existing Component you can call this function with a Component ID as parameter:

  var oComponent = sap.ui.component(sComponentId);

To create a new instance of a component you pass a component configuration object into this function:

  var oComponent = sap.ui.component({
    name: "my.Component",
    url: "my/component/location",
    id: "myCompId1"
  });

since: 1.56 use {@link sap.ui.core.Component.get Component.get} or {@link sap.ui.core.Component.create Component.create} instead. Note: {@link sap.ui.core.Component.create Component.create} does not support synchronous loading or the deprecated options <em>manifestFirst</em> and <em>manifestUrl</em>.
Param Type DefaultValue Description
vConfig string object

ID of an existing Component or the configuration object to create the Component

name string

Name of the Component to load, as a dot-separated name; Even when an alternative location is specified from which the manifest should be loaded (e.g. vConfig.manifest is set to a non-empty string), then the name specified in that manifest will be ignored and this name will be used instead to determine the module to be loaded.

url string

Alternative location from where to load the Component. If a manifestUrl is given, this URL specifies the location of the final component defined via that manifest, otherwise it specifies the location of the component defined via its name vConfig.name.

componentData object

Initial data of the Component (@see sap.ui.core.Component#getComponentData)

id string

sId of the new Component

settings object

Settings of the new Component

activeTerminologies string[]

List of active terminologies. The order of the given active terminologies is significant. The ResourceBundle API documentation describes the processing behavior in more detail. Please also have a look at this dev-guide chapter for general usage instructions: Text Verticalization.

async boolean

Indicates whether the Component creation should be done asynchronously; defaults to true when using the manifest property with a truthy value otherwise the default is false (experimental setting)

asyncHints object

@since 1.27.0 Hints for the asynchronous loading. Beware: This parameter is only used internally by the UI5 framework and compatibility cannot be guaranteed. The parameter must not be used in productive code, except in code delivered by the UI5 teams.

libs string[]

Libraries that should be (pre-)loaded before the Component (experimental setting)

components string[]

Components that should be (pre-)loaded before the Component (experimental setting)

waitFor Promise Promise[]

@since 1.37.0 a Promise or and array of Promises for which the Component instantiation should wait (experimental setting)

manifest boolean string object

@since 1.49.0 Controls when and from where to load the manifest for the Component. When set to any truthy value, the manifest will be loaded asynchronously by default and evaluated before the Component controller, if it is set to a falsy value other than undefined, the manifest will be loaded after the controller. A non-empty string value will be interpreted as the URL location from where to load the manifest. A non-null object value will be interpreted as manifest content. Setting this property to a value other than undefined, completely deactivates the properties manifestUrl and manifestFirst, no matter what their values are.

manifestUrl string

@since 1.33.0 Specifies the URL from where the manifest should be loaded from Using this property implies vConfig.manifestFirst=true.
DEPRECATED since 1.49.0, use vConfig.manifest=url instead!. Note that this property is ignored when vConfig.manifest has a value other than undefined.

manifestFirst boolean

@since 1.33.0 defines whether the manifest is loaded before or after the Component controller. Defaults to sap.ui.getCore().getConfiguration().getManifestFirst()
DEPRECATED since 1.49.0, use vConfig.manifest=true|false instead! Note that this property is ignored when vConfig.manifest has a value other than undefined.

handleValidation string false

If set to true validation of the component is handled by the MessageManager

sap.ui.component.load

Load a component without instantiating it.

Provides support for loading components asynchronously by setting oConfig.async to true. In that case, the method returns a JavaScript 6 Promise that will be fulfilled with the component class after loading.

Using async = true doesn't necessarily mean that no more synchronous loading occurs. Both the framework as well as component implementations might still execute synchronous requests. The contract for async = true just allows to use async calls.

When a manifest.json is referenced in oConfig this manifest is not used for the derived instances of the Component class. The manifest/manifest url must be provided for every instance explicitly.

Since 1.27.0, when asynchronous loading is used, additional asyncHints can be provided. This parameter is only used internally by the UI5 framework and compatibility cannot be guaranteed. The parameter must not be used in productive code, except in code delivered by the UI5 teams.

If Components and/or libraries are listed in the hints section, all the corresponding preload files will be requested in parallel. The constructor class will only be required after all of them are rejected or resolved. Instead of specifying just the name of a component or library in the hints, an object might be given that contains a mandatory name property and, optionally, an url that will be used for a registerModulePath and/or a lazy property. When lazy is set to a truthy value, only a necessary registerModulePath will be executed, but the corresponding component or lib won't be preloaded. For preload bundles, also an object might be given instead of a simple name, but there only the url property is supported, not the lazy property.

Note: so far, only the requests for the preload files (library and/or component) are executed asynchronously. If a preload is deactivated by configuration (e.g. debug mode), then remaining requests still might be synchronous.

since: 1.56 use {@link sap.ui.core.Component.load}
Param Type DefaultValue Description
oConfig object

Configuration object describing the Component to be loaded. See sap.ui.component for more information.

sap.ui.controller

Defines a controller class or creates an instance of an already defined controller class.

When a name and a controller implementation object is given, a new controller class of the given name is created. The members of the implementation object will be copied into each new instance of that controller class (shallow copy). Note: as the members are shallow copied, controller instances will share all object values. This might or might not be what applications expect.

If only a name is given, a new instance of the named controller class is returned.

since: 1.56 use {@link sap.ui.core.mvc.Controller.extend Controller.extend} to define the controller class and {@link sap.ui.core.mvc.Controller.create Controller.create} to create controller instances. For further information, see {@link sap.ui.core.mvc.Controller}.
Param Type DefaultValue Description
sName string

The controller name

oControllerImpl object

An object literal defining the methods and properties of the controller

bAsync boolean false

Decides whether the controller gets loaded asynchronously or not

sap.ui.define

Defines a JavaScript module with its ID, its dependencies and a module export value or factory.

The typical and only suggested usage of this method is to have one single, top level call to sap.ui.define in one JavaScript resource (file). When a module is requested by its module ID for the first time, the corresponding resource is determined from the ID and the current configuration. The resource will be loaded and executed which in turn will execute the top level sap.ui.define call.

If the module ID was omitted from that call, it will be substituted by the ID that was used to request the module. As a preparation step, the dependencies as well as their transitive dependencies, will be loaded. Then, the module value (its export) will be determined: if a static value (object, literal) was given as vFactory, that value will be the module value. If a function was given, that function will be called (providing the module exports of the declared dependencies as parameters to the function) and its return value will be used as module export value. The framework internally associates the resulting value with the module ID and provides it to the original requester of the module. Whenever the module is requested again, the same export value will be returned (modules are executed only once).

Example:
The following example defines a module, but doesn't hard code the module ID. If stored in a file 'sap/mylib/SomeClass.js', it can be requested with the ID 'sap/mylib/SomeClass'.

  sap.ui.define(['./Helper', 'sap/m/Bar'], function(Helper,Bar) {

    // create a new class
    var SomeClass = function() {};

    // add methods to its prototype
    SomeClass.prototype.foo = function() {

        // use a function from the dependency 'Helper' in the same package (e.g. 'sap/mylib/Helper' )
        var mSettings = Helper.foo();

        // create and return an sap.m.Bar (using its local name 'Bar')
        return new Bar(mSettings);

    }

    // return the class as module value
    return SomeClass;

  });

In another module or in an application HTML page, the sap.ui.require API can be used to load the sap/mylib/Something module and to work with it:

sap.ui.require(['sap/mylib/Something'], function(Something) {

  // instantiate a Something and call foo() on it
  new Something().foo();

});

Module Name Syntax

sap.ui.define uses a simplified variant of the unified resource name syntax for the module's own name as well as for its dependencies. The only difference to that syntax is, that for sap.ui.define and sap.ui.require, the extension (which always would be '.js') has to be omitted. Both methods always add this extension internally.

As a convenience, the name of a dependency can start with the segment './' which will be replaced by the name of the package that contains the currently defined module (relative name).

It is best practice to omit the name of the defined module (first parameter) and to use relative names for the dependencies whenever possible. This reduces the necessary configuration, simplifies renaming of packages and allows to map them to a different namespace.

Dependency to Modules

If a dependencies array is given, each entry represents the name of another module that the currently defined module depends on. All dependency modules are loaded before the export of the currently defined module is determined. The module export of each dependency module will be provided as a parameter to a factory function, the order of the parameters will match the order of the modules in the dependencies array.

Note: The order in which the dependency modules are executed is not defined by the order in the dependencies array! The execution order is affected by dependencies between the dependency modules as well as by their current state (whether a module already has been loaded or not). Neither module implementations nor dependents that require a module set must make any assumption about the execution order (other than expressed by their dependencies).

Note: A static module export (a literal provided to sap.ui.define) cannot depend on the module exports of the dependency modules as it has to be calculated before the dependencies are resolved. As an alternative, modules can define a factory function, calculate a static export value in that function, potentially based on the dependencies, and return the result as module export value. The same approach must be taken when the module export is supposed to be a function.

Asynchronous Contract

sap.ui.define is designed to support real Asynchronous Module Definitions (AMD) in future, although it internally still might use synchronous module loading, depending on configuration and context. However, callers of sap.ui.define must never rely on any synchronous behavior that they might observe in a specific test scenario.

For example, callers of sap.ui.define must not use the module export value immediately after invoking sap.ui.define:

  // COUNTER EXAMPLE HOW __NOT__ TO DO IT

  // define a class Something as AMD module
  sap.ui.define('Something', [], function() {
    var Something = function() {};
    return Something;
  });

  // DON'T DO THAT!
  // accessing the class _synchronously_ after sap.ui.define was called
  new Something();

Applications that need to ensure synchronous module definition or synchronous loading of dependencies MUST use the deprecated legacy APIs jQuery.sap.declare and jQuery.sap.require.

(No) Global References

To be in line with AMD best practices, modules defined with sap.ui.define should not make any use of global variables if those variables are also available as module exports. Instead, they should add dependencies to those modules and use the corresponding parameter of the factory function to access the module exports.

As the current programming model and the documentation of UI5 heavily rely on global names, there will be a transition phase where UI5 enables AMD modules and local references to module exports in parallel to the old global names. The fourth parameter of sap.ui.define has been added to support that transition phase. When this parameter is set to true, the framework provides two additional features

  1. Before the factory function is called, the existence of the global parent namespace for the current module is ensured
  2. The module export returned by the module's factory function will be automatically exported under the global name which is derived from the ID of the module

The parameter lets the framework know whether any of those two operations is needed or not. In future versions of UI5, a central configuration option is planned to suppress those 'exports'.

Third Party Modules

Although third party modules don't use UI5 APIs, they still can be listed as dependencies in a sap.ui.define call. They will be requested and executed like UI5 modules, but to make their exports available, so called shims have to be defined.

Note that UI5 temporarily deactivates an existing AMD loader while it executes third party modules known to support AMD. This sounds contradictorily at a first glance as UI5 wants to support AMD, but for now it is necessary to fully support UI5 applications that rely on global names for such modules.

For third-party modules that UI5 delivers (e.g. those in namespace sap/ui/thirdparty/), the necessary shims are defined by UI5 itself by executing the private module ui5loader-autoconfig.js during bootstrap.

Example:

  // module 'Something' wants to use third party library 'URI.js'
  // It is packaged by UI5 as non-UI5-module 'sap/ui/thirdparty/URI'
  // the following shim helps UI5 to correctly load URI.js and to retrieve the module's export value
  // Apps don't have to define that shim, it is already applied by ui5loader-autconfig.js
  sap.ui.loader.config({
    shim: {
      'sap/ui/thirdparty/URI': {
         amd: true, // URI.js reacts on an AMD loader, this flag lets UI5 temp. disable such loaders
         exports: 'URI' // name of the global variable under which URI.js exports its module value
      }
    }
  });

  // now the module can be retrieved like other modules
  sap.ui.define('Something', ['sap/ui/thirdparty/URI'], function(URIModuleValue) {

    new URIModuleValue(...); // same as the global 'URI' name: new URI(...)

    ...
  });

Differences to Standard AMD

The current implementation of sap.ui.define differs from the AMD specification (https://github.com/amdjs/amdjs-api) or from concrete AMD loaders like requireJS in several aspects:

Limitations, Design Considerations



References:

Param Type DefaultValue Description
sModuleName string

ID of the module in simplified resource name syntax. When omitted, the loader determines the ID from the request.

aDependencies string[]

List of dependencies of the module

vFactory function any

The module export value or a function that calculates that value

bExport boolean

Whether an export to global names is required - should be used by SAP-owned code only

sap.ui.extensionpoint

Creates 0..n UI5 controls from an ExtensionPoint.

One control if the ExtensionPoint is e.g. filled with a View, zero for extension points without configured extension and n controls for multi-root Fragments as extension.

In JSViews, this function allows both JSON notation in aggregation content as well as adding an extension point to an aggregation after the target control has already been instantiated. In the latter case the optional parameters oTargetControls and oTargetAggregation need to be specified.

since: 1.56 Use {@link sap.ui.core.ExtensionPoint.load} instead
Param Type DefaultValue Description
oContainer sap.ui.core.mvc.View sap.ui.core.Fragment

The view or fragment containing the extension point

sExtName string

The extensionName used to identify the extension point in the customizing

fnCreateDefaultContent function

Optional callback function creating default content, returning an array of controls. It is executed when there's no customizing, if not provided, no default content will be rendered. fnCreateDefaultContent might also return a Promise, which resolves with an array of controls.

oTargetControl sap.ui.core.Control

Optional - use this parameter to attach the extension point to a particular aggregation

sAggregationName string

Optional - if provided along with oTargetControl, the extension point content is added to this particular aggregation at oTargetControl, if not given, but an oTargetControl is still present, the function will attempt to add the extension point to the default aggregation of oTargetControl. If no oTargetControl is provided, sAggregationName will also be ignored.

sap.ui.fragment

Instantiate a Fragment - this method loads the Fragment content, instantiates it, and returns this content. The Fragment object itself is not an entity which has further significance beyond this constructor.

To instantiate an existing Fragment, call this method as: sap.ui.fragment(sName, sType, [oController]); The sName must correspond to a Fragment module which can be loaded via the module system (fragmentName + suffix ".fragment.[typeextension]") and which defines the Fragment content. If oController is given, the (event handler) methods referenced in the Fragment will be called on this controller. Note that Fragments may require a Controller to be given and certain methods to be available.

The Fragment types "XML", "JS" and "HTML" are available by default; additional Fragment types can be implemented and added using the sap.ui.core.Fragment.registerType() function.

Advanced usage: To instantiate a Fragment and give further configuration options, call this method as: sap.ui.fragment(oFragmentConfig, [oController]); The oFragmentConfig object can have the following properties: - "fragmentName": the name of the Fragment, as above - "fragmentContent": the definition of the Fragment content itself. When this property is given, any given name is ignored. The type of this property depends on the Fragment type, e.g. it could be a string for XML Fragments. - "type": the type of the Fragment, as above (mandatory) - "id": the ID of the Fragment (optional) Further properties may be supported by future or custom Fragment types. Any given properties will be forwarded to the Fragment implementation.

If you want to give a fixed ID for the Fragment, please use the advanced version of this method call with the configuration object or use the typed factories like sap.ui.xmlfragment(...) or sap.ui.jsfragment(...). Otherwise the Fragment ID is generated. In any case, the Fragment ID will be used as prefix for the ID of all contained controls.

since: 1.58 use {@link sap.ui.core.Fragment.load} instead
Param Type DefaultValue Description
sName string Object

the Fragment name

sType string

the Fragment type, e.g. "XML", "JS", or "HTML"

oController sap.ui.core.mvc.Controller Object

the Controller or Object which should be used by the controls in the Fragment. Note that some Fragments may not need a Controller and other may need one - and even rely on certain methods implemented in the Controller.

sap.ui.getCore

Retrieve the SAPUI5 Core instance for the current window.

Param Type DefaultValue Description

sap.ui.getVersionInfo

Loads the version info file (resources/sap-ui-version.json) and returns it or if a library name is specified then the version info of the individual library will be returned.

In case of the version info file is not available an error will occur when calling this function.

since: 1.56 Use {@link module:sap/ui/VersionInfo.load} instead
Param Type DefaultValue Description
mOptions string object

name of the library (e.g. "sap.ui.core") or an object map (see below)

library boolean

name of the library (e.g. "sap.ui.core")

async boolean false

whether "sap-ui-version.json" should be loaded asynchronously

failOnError boolean true

whether to propagate load errors or not (not relevant for async loading)

sap.ui.htmlfragment

Instantiates an HTML-based Fragment.

To instantiate a fragment, call:

   sap.ui.htmlfragment([sId], sFragmentName, [oController]);
The fragment instance ID is optional and will be used as prefix for the ID of all contained controls. If no ID is passed, controls will not be prefixed. The sFragmentName must correspond to an HTML fragment which can be loaded via the module system (fragmentName + ".fragment.html") and which defines the fragment. If oController is given, the methods referenced in the fragment will be called on this controller. Note that fragments may require a controller to be given and certain methods to be available.

Advanced usage:

To instantiate a fragment and optionally directly give the HTML definition instead of loading it from a file, call:

    sap.ui.htmlfragment(oFragmentConfig, [oController]);
The oFragmentConfig object can either have a fragmentName or a fragmentContent property, but not both of them. fragmentContent can hold the fragment definition as XML string; if not given, fragmentName must be given and the fragment content definition is loaded by the module system. Again, if oController is given, any methods referenced in the fragment will be called on this controller.

since: 1.58 use {@link sap.ui.core.Fragment.load} instead
Param Type DefaultValue Description
sId string

ID of the newly created fragment

vFragment string object

Resource name of the fragment, a module name in dot notation without the '.fragment.html' suffix. Alternatively, a configuration object can be given with the properties described below. In this case, no sId may be given as first parameter, but as property id in the configuration object.

id string

ID of the newly created fragment; will be used as a prefix to all contained control IDs

fragmentName string

Resource name of the Fragment; a module name in dot notation without the '.fragment.html' suffix

fragmentContent string

Definition of the fragment as an HTML string

oController sap.ui.core.mvc.Controller object

A controller to be used for event handlers in the fragment; can either be the controller of an enclosing view, a new controller instance, or a simple object with the necessary methods attached. Note that a fragment has no runtime representation besides its contained controls. There's therefore no API to retrieve the controller after creating a fragment

sap.ui.htmlview

Defines or creates an instance of a declarative HTML view.

The behavior of this method depends on the signature of the call and on the current context.

Any other call signature will lead to a runtime error. If the id is omitted in the second variant, an id will be created automatically.

since: 1.56 Use {@link sap.ui.core.mvc.HTMLView.create HTMLView.create} to create view instances
Param Type DefaultValue Description
sId string

id of the newly created view, only allowed for instance creation

vView string object

name or implementation of the view.

async boolean

whether the view source is loaded asynchronously

sap.ui.jsfragment

Defines OR instantiates an HTML-based fragment.

To define a JS fragment, call:

   sap.ui.jsfragment(sName, oFragmentDefinition)
where:

To instantiate a JS fragment, call:

   sap.ui.jsfragment([sId], sFragmentName, [oController]);
The fragment ID is optional (generated if not given) and the fragment implementation can use it to make contained controls unique (this depends on the implementation: some JS fragments may choose not to support multiple instances within one application and not use the ID prefixing). The sFragmentName must correspond to a JS fragment which can be loaded via the module system (sFragmentName converted to a path + ".fragment.js" suffix) and which defines the fragment. Or it can be a name that has been used earlier to define a fragment of that name. If oController is given, the methods referenced in the fragment will be called on this controller. Note that fragments may require a controller to be given and certain methods to be available.

since: 1.58 use {@link sap.ui.core.Fragment.load} instead
Param Type DefaultValue Description
vName string object

Name of the fragment when defining a fragment; ID or name or configuration object when instantiating a fragment

id string

ID of the newly created fragment; will be used as a prefix to all contained control IDs

fragmentName string

Name of the fragment. When no fragment has been defined with that name, the name will be converted to a path by replacing dots with slashes and appending '.fragment.js'. The corresponding resource will be loaded and is expected to define a fragment with the fragmentName

vFragmentDefinition object string

When defining a fragment, this parameter must be a factory object that will be used to create new instances of the fragment; it must at least contain a createContent method. When creating an instance of a fragment and when vName was an ID, this parameter must be the name of the fragment. When the first parameter was a name, this parameter must be omitted.

oController sap.ui.core.mvc.Controller object

A controller to be used for event handlers in the fragment; can either be the controller of an enclosing view, a new controller instance, or a simple object with the necessary methods attached. Note that a fragment has no runtime representation besides its contained controls. There's therefore no API to retrieve the controller after creating a fragment

sap.ui.jsonview

Creates a JSON view of the given name and id.

The viewName must either correspond to a JSON module that can be loaded via the module system (viewName + suffix ".view.json") and which defines the view or it must be a configuration object for a view. The configuration object can have a viewName, viewContent and a controller property. The viewName behaves as described above, viewContent can hold the view description as JSON string or as object literal.

Note: when an object literal is given, it might be modified during view construction.

The controller property can hold a controller instance. If a controller instance is given, it overrides the controller defined in the view.

When property async is set to true, the view definition and the controller class (and its dependencies) will be loaded asynchronously. Any controls used in the view might be loaded sync or async, depending on the view configuration. Even when the view definition is provided as string or object tree, controller or controls might be loaded asynchronously. In any case, a view instance will be returned synchronously by this factory API, but its content (control tree) might appear only later. Also see sap.ui.core.mvc.View#loaded.

Like with any other control, an id is optional and will be created when missing.

since: 1.56 Use {@link sap.ui.core.mvc.JSONView.create JSONView.create} to create view instances
Param Type DefaultValue Description
sId string

id of the newly created view

vView string object

name of a view resource or view configuration as described above.

viewName string

name of a view resource in module name notation (without suffix)

viewContent string object

view definition as a JSON string or an object literal

async boolean

defines how the view source is loaded and rendered later on

controller sap.ui.core.mvc.Controller

controller to be used for this view instance

sap.ui.jsview

Defines or creates an instance of a JavaScript view.

The behavior of this method depends on the signature of the call and on the current context.

View Definition

  sap.ui.jsview(sId, vView);
Defines a view of the given name with the given implementation. sId must be the view's name, vView must be an object and can contain implementations for any of the hooks provided by JSView.

View Instantiation (deprecated)

  var oView = sap.ui.jsview(vView);
  var oView = sap.ui.jsview(vView, bASync);
  var oView = sap.ui.jsview(sId, vView);
  var oView = sap.ui.jsview(sId, vView, bAsync);
Creates an instance of the view with the given name (and id). If no view implementation has been defined for that view name, a JavaScript module with the same qualified name and with suffix .view.js will be loaded (required) and executed. The module should register a view definition on execution (1st. variant above).

If sId is omitted, an ID will be created automatically.

When bAsync has a truthy value, the view definition will be read asynchronously, if needed, but the (incomplete) view instance will be returned immediately.

Note: Any other call signature will lead to a runtime error.

since: 1.56 Use {@link sap.ui.core.mvc.View.extend View.extend} to define the view class and {@link sap.ui.core.mvc.View.create View.create} to create view instances
Param Type DefaultValue Description
sId string

ID of the newly created view, only allowed for instance creation

vView string object

name or implementation of the view.

bAsync boolean false

whether the view source is loaded asynchronously

sap.ui.lazyRequire

Creates a lazy loading stub for a given class sClassName.

If the class has been loaded already, nothing is done. Otherwise a stub object or constructor and - optionally - a set of stub methods are created. All created stubs will load the corresponding module on execution and then delegate to their counterpart in the loaded module.

When no methods are given or when the list of methods contains the special name "new" (which is an operator can't be used as method name in JavaScript), then a stub constructor for class sClassName is created. Otherwise, a plain object is created.

Note: Accessing any stub as a plain object without executing it (no matter whether it is a function or an object) won't load the module and therefore most likely won't work as expected. This is a fundamental restriction of the lazy loader approach.

Note: As a side effect of this method, the namespace containing the given class is created immediately.

since: 1.56 Lazy loading enforces synchronous requests and therefore has been deprecated without a replacement. Instead of loading classes via lazy stubs, they should be required as dependencies of an AMD module (using {@link sap.ui.define}) or on demand with a call to {@link sap.ui.require}.
Param Type DefaultValue Description
sClassName string

Fully qualified name (dot notation) of the class that should be prepared

sMethods string 'new'

Space separated list of additional (static) methods that should be created as stubs

sModuleName string

Name of the module to load, defaults to the class name

sap.ui.localResources

Redirects access to resources that are part of the given namespace to a location relative to the assumed application root folder.

Any UI5 managed resource (view, controller, control, JavaScript module, CSS file, etc.) whose resource name starts with sNamespace, will be loaded from an equally named subfolder of the application root folder. If the resource name consists of multiple segments (separated by a dot), each segment is assumed to represent an individual folder. In other words: when a resource name is converted to a URL, any dots ('.') are converted to slashes ('/').

Limitation: For the time being, the application root folder is assumed to be the same as the folder where the current page resides in.

Usage sample:

  // Let UI5 know that resources, whose name starts with "com.mycompany.myapp"
  // should be loaded from the URL location "./com/mycompany/myapp"
  sap.ui.localResources("com.mycompany.myapp");

  // The following call implicitly will use the mapping done by the previous line
  // It will load a view from ./com/mycompany/myapp/views/Main.view.xml
  View.create({ viewName : "com.mycompany.myapp.views.Main", type : ViewType.XML}).then(function(oView) {
      // do stuff
  });

When applications need a more flexible mapping between resource names and their location, they can use jQuery.sap.registerModulePath.

It is intended to make this configuration obsolete in future releases, but for the time being, applications must call this method when they want to store resources relative to the assumed application root folder.

References:

since: 1.56 use <code>sap.ui.loader.config</code> instead.
Param Type DefaultValue Description
sNamespace string

Namespace prefix for which to load resources relative to the application root folder

sap.ui.namespace

Ensures that a given a namespace or hierarchy of nested namespaces exists in the current window.

since: 1.1 see {@link topic:c78c07c094e04ccfaab659378a1707c7 Creating Control and Class Modules}.
Param Type DefaultValue Description
sNamespace string

sap.ui.predefine

Param Type DefaultValue Description

sap.ui.require

Resolves one or more module dependencies.

Synchronous Retrieval of a Single Module Export Value (Probing)

When called with a single string, that string is assumed to be the ID of an already loaded module and the export of that module is returned. If the module has not been loaded yet, or if it is a Non-UI5 module (e.g. third-party module) without a shim, undefined is returned.

This signature variant allows synchronous access to module exports without initiating module loading.

Sample:

  var JSONModel = sap.ui.require("sap/ui/model/json/JSONModel");

For modules that are known to be UI5 modules, this signature variant can be used to check whether the module has been loaded.

Asynchronous Loading of Multiple Modules

If an array of strings is given and (optionally) a callback function, then the strings are interpreted as module IDs and the corresponding modules (and their transitive dependencies) are loaded. Then the callback function will be called asynchronously. The module exports of the specified modules will be provided as parameters to the callback function in the same order in which they appeared in the dependencies array.

The return value for the asynchronous use case is undefined.

  sap.ui.require(['sap/ui/model/json/JSONModel', 'sap/ui/core/UIComponent'], function(JSONModel,UIComponent) {

    var MyComponent = UIComponent.extend('MyComponent', {
      ...
    });
    ...

  });

This method uses the same variation of the unified resource name syntax that sap.ui.define uses: module names are specified without the implicit extension '.js'. Relative module names are not supported.

Param Type DefaultValue Description
vDependencies string string[]

Dependency (dependencies) to resolve

fnCallback function

Callback function to execute after resolving an array of dependencies

fnErrback function

Callback function to execute if an error was detected while loading the dependencies or executing the factory function. Note that due to browser limitations not all errors will be reported via this callback. In general, module loading is designed for the non-error case. Error handling is not complete.

sap.ui.require.toUrl

Calculates a URL from the provided resource name.

The calculation takes any configured ID mappings or resource paths into account (see config options map and paths. It also supports relative segments such as ./ and ../ within the path, but not at its beginning. If relative navigation would cross the root namespace (e.g. sap.ui.require.toUrl("../")) or when the resource name starts with a slash or with a relative segment, an error is thrown.

Note: toUrl does not resolve the returned URL; whether it is an absolute URL or a relative URL depends on the configured baseUrl and paths.

References:

Param Type DefaultValue Description
sName string

Name of a resource e.g. 'app/data.json'

sap.ui.requireSync

Load a single module synchronously and return its module value.

Basically, this method is a combination of jQuery.sap.require and sap.ui.require. Its main purpose is to simplify the migration of modules to AMD style in those cases where some dependencies have to be loaded late (lazy) and synchronously.

The method accepts a single module name in the same syntax that sap.ui.define and sap.ui.require already use (a simplified variation of the unified resource name: slash separated names without the implicit extension '.js'). As for sap.ui.require, relative names (using ./ or ../) are not supported. If not loaded yet, the named module will be loaded synchronously and the export value of the module will be returned. While a module is executing, a value of undefined will be returned in case it is required again during that period of time (e.g. in case of cyclic dependencies).

Note: Applications are strongly encouraged to use this method only when synchronous loading is unavoidable. Any code that uses this method won't benefit from future performance improvements that require asynchronous module loading (e.g. HTTP/2). And such code never can comply with stronger content security policies (CSPs) that forbid 'eval'.

Param Type DefaultValue Description
sModuleName string

Module name in requireJS syntax

sap.ui.resource

Returns the URL of a resource that belongs to the given library and has the given relative location within the library. This is mainly meant for static resources like images that are inside the library. It is NOT meant for access to JavaScript modules or anything for which a different URL has been registered with jQuery.sap.registerModulePath(). For these cases use jQuery.sap.getModulePath(). It DOES work, however, when the given sResourcePath starts with "themes/" (= when it is a theme-dependent resource). Even when for this theme a different location outside the normal library location is configured.

since: 1.56.0 use <code>sap.ui.require.toUrl</code> instead.
Param Type DefaultValue Description
sLibraryName string

the name of a library, like "sap.ui.commons"

sResourcePath string

the relative path of a resource inside this library, like "img/mypic.png" or "themes/my_theme/img/mypic.png"

sap.ui.setRoot

Displays the control tree with the given root inside the area of the given DOM reference (or inside the DOM node with the given ID) or in the given Control.

Example:

  <div id="SAPUI5UiArea"></div>
  <script>
    var oRoot = new sap.ui.commons.Label();
    oRoot.setText("Hello world!");
    sap.ui.setRoot("SAPUI5UiArea", oRoot);
  </script>

This is a shortcut for sap.ui.getCore().setRoot().

Internally, if a string is given that does not identify a UIArea or a control then implicitly a new UIArea is created for the given DOM reference and the given control is added.

since: 1.1 use {@link sap.ui.core.Control#placeAt Control#placeAt} instead.
Param Type DefaultValue Description
oDomRef string Element sap.ui.core.Control

a DOM Element or Id String of the UIArea

oControl sap.ui.base.Interface sap.ui.core.Control

the Control that should be added to the UIArea.

sap.ui.template

Creates a Template for the given ID, DOM reference or a configuration object.

If no parameter is defined, this function makes a lookup of DOM elements which are specifying a type attribute. If the value of this type attribute matches a registered type then the content of this DOM element will be used to create a new Template instance.

If you want to lookup all kind of existing and known templates and parse them directly you can simply call:

  sap.ui.template();

To parse a concrete DOM element you can do so by using this function in the following way:

  sap.ui.template("theTemplateId");

Or you can pass the reference to a DOM element and use this DOM element as a source for the template:

  sap.ui.template(oDomRef);

The last option to use this function is to pass the information via a configuration object. This configuration object can be used to pass a context for the templating framework when compiling the template:

  var oTemplateById = sap.ui.template({
    id: "theTemplateId",
    context: { ... }
  });

  var oTemplateByDomRef = sap.ui.template({
    domref: oDomRef,
    context: { ... }
  });

It can also be used to load a template from another file:

  var oTemplate = sap.ui.template({
    id: "myTemplate",
    src: "myTemplate.tmpl"
  });

  var oTemplateWithContext = sap.ui.template({
    id: "myTemplate",
    src: "myTemplate.tmpl",
    context: { ... }
  });

since: 1.56 use an {@link sap.ui.core.mvc.XMLView XMLView} or {@link sap.ui.core.mvc.JSView JSView} instead.
Param Type DefaultValue Description
oTemplate string Element object

the ID or the DOM reference to the template to lookup or a configuration object containing the src, type and eventually the ID of the Template.

id string

the ID of the Template / the ID of the DOM element containing the source of the Template

domref Element

the DOM element containing the source of the Template

type string

the type of the Template

context object

the context for the renderer/templating

src string

the URL to lookup the template (experimental!)

control string

the fully qualified name of the control to declare (experimental!)

sap.ui.templateview

Defines or creates an instance of a template view.

The behavior of this method depends on the signature of the call and on the current context.

Any other call signature will lead to a runtime error. If the id is omitted in the second variant, an id will be created automatically.

since: 1.56 use {@link sap.ui.core.mvc.XMLView} in combination with {@link topic:5ee619fc1370463ea674ee04b65ed83b XML Templating} instead
Param Type DefaultValue Description
sId string

id of the newly created view, only allowed for instance creation

vView string object

name or implementation of the view.

sap.ui.view

Creates a view of the given type, name and with the given ID.

since: 1.56 Use {@link sap.ui.core.mvc.View.extend View.extend} to define the view class and {@link sap.ui.core.mvc.View.create View.create} to create view instances
Param Type DefaultValue Description
sId string

The ID of the newly created view, only allowed for instance creation. If no ID is given, an ID will be generated. For view definition, skip this parameter and use vView as the first parameter.

vView string object

The view name or view configuration object.

id object

Specifies an ID for the view instance. If no ID is given, an ID will be generated.

viewName object

Corresponds to an XML module that can be loaded via the module system (vView.viewName + suffix ".view.xml").

controller sap.ui.core.mvc.Controller

The controller instance must be a valid controller implementation. The given controller instance overrides the controller defined in the view definition.

async boolean

Whether the view source is loaded asynchronously. In asynchronous mode, the view is returned empty, and the view content is loaded asynchronously.

type sap.ui.core.mvc.ViewType

Specifies what kind of view will be instantiated. All valid view types are listed in the enumeration sap.ui.core.mvc.ViewType.

viewData object

Holds application specific data. This data is available during the whole lifecycle of the view and the controller, for example in the constructor and in the onInit hook.

preprocessors Map<string,object[]>

Holds a map from the specified preprocessor type (e.g. "xml") to an array of preprocessor configurations. Each configuration consists of a preprocessor property (optional when registered as on-demand preprocessor) and may contain further preprocessor-specific settings.

preprocessor string sap.ui.core.mvc.View.Preprocessor function

The used preprocessor. For further information see sap.ui.core.mvc.View.Preprocessor.process. Do not set properties starting with an underscore, such as _sProperty, as these are reserved for internal purposes. When several preprocessors are provided for one hook, it has to be made sure that they do not conflict when being processed serially.


Note: These preprocessors are only available to this instance. For global or on-demand availability use sap.ui.core.mvc.XMLView.registerPreprocessor.


Note: Please note that preprocessors in general are currently only available for XMLViews.


Note: Preprocessors only work in asynchronous views and will be ignored by default when the view is instantiated synchronously, as this could have unexpected side effects. You may override this behaviour by setting the bSyncSupport flag of the preprocessor to true.

sap.ui.xmlfragment

Instantiates an XML-based Fragment.

To instantiate a fragment, call:

   sap.ui.xmlfragment([sId], sFragmentName, [oController]);
The fragment instance ID is optional and will be used as prefix for the ID of all contained controls. If no ID is passed, controls will not be prefixed. The sFragmentName must correspond to an XML fragment which can be loaded via the module system (fragmentName + ".fragment.xml") and which defines the fragment. If oController is given, the methods referenced in the fragment will be called on this controller.

Note that fragments may require a controller to be given and certain methods to be available.

Advanced usage:

To instantiate a fragment and optionally directly give the XML definition instead of loading it from a file, call:

    sap.ui.xmlfragment(oFragmentConfig, [oController]);
The oFragmentConfig object can either have a fragmentName or a fragmentContent property, but not both. fragmentContent can hold the fragment definition as XML string; if not given, fragmentName must be given and the fragment content definition is loaded via the module system. Again, if oController is given, the methods referenced in the fragment will be called on this controller.

since: 1.58 use {@link sap.ui.core.Fragment.load} instead
Param Type DefaultValue Description
sId string

ID of the newly created fragment

vFragment string object

Resource name of the fragment; a module name in dot notation without the '.fragment.xml' suffix. Alternatively, a configuration object can be given with the properties described below. In this case, no sId may be given as first parameter, but as property id in the configuration object.

id string

ID of the newly created fragment; will be used as a prefix to all contained control IDs

fragmentName string

Resource name of the fragment; a module name in dot notation without the '.fragment.html' suffix

fragmentContent string

Definition of the fragment as an XML string

oController sap.ui.core.mvc.Controller object

A controller to be used for event handlers in the fragment; can either be the controller of an enclosing view, a new controller instance, or a simple object with the necessary methods attached. Note that a fragment has no runtime representation besides its contained controls. There's therefore no API to retrieve the controller after creating a fragment

sap.ui.xmlview

Instantiates an XMLView of the given name and with the given ID.

The vView can either be the name of the module that contains the view definition or it can be a configuration object with properties viewName, viewContent and a controller property (more properties are described in the parameters section below).

If a viewName is given, it behaves the same as when vView is a string: the named resource will be loaded and parsed as XML. Alternatively, an already loaded view definition can be provided as viewContent, either as XML string or as an already parsed XML document. Exactly one of viewName and viewContent must be given, if none or both are given, an error will be reported. The controller property is optional and can hold a controller instance. When given, it overrides the controller class defined in the view definition.

When property async is set to true, the view definition and the controller class (and its dependencies) will be loaded asynchronously. Any controls used in the view might be loaded sync or async, depending on the processingMode. Even when the view definition is provided as string or XML Document, controller or controls might be loaded asynchronously. In any case a view instance will be returned synchronously by this factory API, but its content (control tree) might appear only later. Also see sap.ui.core.mvc.View#loaded.

Note: If an XML document is given, it might be modified during view construction.

Note: On root level, you can only define content for the default aggregation, e.g. without adding the <content> tag. If you want to specify content for another aggregation of a view like dependents, place it in a child control's dependents aggregation or add it by using sap.ui.core.mvc.XMLView#addDependent.

Note: If you enable caching, you need to take care of the invalidation via keys. Automatic invalidation takes only place if the UI5 version or the component descriptor (manifest.json) change. This is still an experimental feature and may experience slight changes of the invalidation parameters or the cache key format.

Like with any other control, sId is optional and an ID will be created automatically.

since: 1.56 Use {@link sap.ui.core.mvc.XMLView.create XMLView.create} to create view instances
Param Type DefaultValue Description
sId string

ID of the newly created view

vView string object

Name of the view or a view configuration object as described above

viewName string

Name of the view resource in module name notation (without suffix)

viewContent string Document

XML string or XML document that defines the view

async boolean

whether the view source is loaded asynchronously

cache object

Cache configuration, only for async views; caching gets active when this object is provided with vView.cache.keys array; keys are used to store data in the cache and for invalidation of the cache

keys Array<(string Promise<string>)>

Array with strings or Promises resolving with strings

preprocessors object

Preprocessors configuration, see sap.ui.core.mvc.View

controller sap.ui.core.mvc.Controller

Controller instance to be used for this view