namespace jQuery.sap

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

Nodes Overview

Node Description
jQuery.sap.support

The jQuery.sap.support namespace is the central entry point for the Support Assistant functionality.


Methods Overview

Method Description
adding virtual history which used only to mark some intermediate state in order to navigate back to the previous state. And this state will be skipped from the browser history stack immediately after a new history state is added to the history stack after this state

By providing the hash saved from the return value of calling jQuery.sap.history.addHistory, jQuery.sap.history.backToHash will navigate back directly to the history state with the same hash.

Please use jQuery.sap.history#back() to go one step back in the history stack instead of using window.history.back(), because it handles the empty history stack situation and will call the defaultHandler for this case.

Example for the usage of history handling:

	//Initialization
	jQuery.sap.history({
		routes: [], //please refer to the jQuery.sap.history function comment for the format.
		defaultHandler: function(){
			//code here
		}
	});

	//add history
	var hash = jQuery.sap.history.addHistory("IDENTIFIER", jsonData);

	//add virtual history
	jQuery.sap.history.addVirtualHistory();

	//back to hash
	jQuery.sap.history.backToHash(hash);

	//back one step along the history stack
	jQuery.sap.history.back();

jQuery.sap.interaction jQuery.sap.KeyCodes

Enumeration of key codes.

jQuery.sap.log

A Logging API for JavaScript.

jQuery.sap.measure

Namespace for the jQuery performance measurement plug-in provided by SAP SE.

jQuery.sap.PseudoEvents

Enumeration of all so called "pseudo events", a useful classification of standard browser events as implied by SAP product standards.

jQuery.sap.storage

Returns a Storage object for a given HTML5 storage (type) and, as a convenience, provides static functions to access the default (session) storage.

jQuery.sap.Version

Represents a version consisting of major, minor, patch version and suffix, e.g.

jQuery.sap.util

Methods Overview

Method Description
jQuery.sap._loadJSResourceAsync

Loads the given Javascript resource (URN) asynchronously via as script tag. Returns a promise that will be resolved when the load event is fired or reject when the error event is fired.

Note: execution errors of the script are not reported as 'error'.

This method is not a full implementation of require. It is intended only for loading "preload" files that do not define an own module / module value.

Functionality might be removed/renamed in future, so no code outside the sap.ui.core library must use it.

jQuery.sap.addUrlWhitelist

Adds an allowlist entry for URL validation.

since: 1.58 use {@link module:sap/base/security/URLListValidator.add} instead. SAP strives to replace insensitive terms with inclusive language, but APIs cannot be renamed or immediately removed for compatibility reasons.
jQuery.sap.arrayDiff

Calculate delta of old list and new list.

This partly implements the algorithm described in "A Technique for Isolating Differences Between Files" but instead of working with hashes, it does compare each entry of the old list with each entry of the new list, which causes terrible performance on large datasets.

since: 1.38 use {@link module:sap/base/util/array/diff} instead if applicable
jQuery.sap.arraySymbolDiff

Calculate delta of old list and new list.

This function implements the algorithm described in "A Technique for Isolating Differences Between Files" (Commun. ACM, April 1978, Volume 21, Number 4, Pages 264-268).

Items in the arrays are not compared directly. Instead, a substitute symbol is determined for each item by applying the provided function fnSymbol to it. Items with strictly equal symbols are assumed to represent the same logical item:

  fnSymbol(a) === fnSymbol(b)   <=>   a 'is logically the same as' b
As an additional constraint, casting the symbols to string should not modify the comparison result. If this second constraint is not met, this method might report more diffs than necessary.

If no symbol function is provided, a default implementation is used which applies JSON.stringify to non-string items and reduces the strings to a hash code. It is not guaranteed that this default implementation fulfills the above constraint in all cases, but it is a compromise between implementation effort, generality and performance. If items are known to be non-stringifiable (e.g. because they may contain cyclic references) or when hash collisions are likely, an own fnSymbol function must be provided.

The result of the diff is a sequence of update operations, each consisting of a type (either "insert" or "delete") and an index. By applying the operations one after the other to the old array, it can be transformed to an array whose items are equal to the new array.

Sample implementation of the update


 function update(aOldArray, aNewArray) {

   // calculate the diff
   var aDiff = jQuery.sap.arraySymbolDiff(aOldArray, aNewArray, __provide_your_symbol_function_here__);

   // apply update operations
   aDiff.forEach( function(op) {

     // invariant: aOldArray and aNewArray now are equal up to (excluding) op.index

     switch ( op.type ) {
     case 'insert':
       // new array contains a new (or otherwise unmapped) item, add it here
       aOldArray.splice(op.index, 0, aNewArray[op.index]);
       break;
     case 'delete':
       // an item is no longer part of the array (or has been moved to another position), remove it
       aOldArray.splice(op.index, 1);
       break;
     default:
       throw new Error('unexpected diff operation type');
     }

   });
 }

since: 1.58 use {@link module:sap/base/util/array/diff} instead
jQuery.sap.assert

A simple assertion mechanism that logs a message when a given condition is not met.

Note: Calls to this method might be removed when the JavaScript code is optimized during build. Therefore, callers should not rely on any side effects of this method.

since: 1.58 use {@link module:sap/base/assert} instead
jQuery.sap.bindAnyEvent

Binds all events for listening with the given callback function.

since: 1.58 use {@link module:sap/ui/events/ControlEvents.bindAnyEvent} instead
jQuery.sap.byId

Shortcut for jQuery("#" + id) with additionally the id being escaped properly. I.e.: returns the jQuery object for the DOM element with the given id

Use this method instead of jQuery(...) if you know the argument is exactly one id and the id is not known in advance because it is in a variable (as opposed to a string constant with known content).

since: 1.58 use <code>jQuery(document.getElementById(sId))</code> instead
jQuery.sap.camelCase

Transforms a hyphen separated string to a camel case string.

since: 1.58 use {@link module:sap/base/strings/camelize} instead
jQuery.sap.charToUpperCase

Converts one character of the string to upper case, at a given position.

If no position is given or when it is negative or beyond the last character of sString, then the first character will be converted to upper case. The first character position is 0.

since: 1.58 use {@link module:sap/base/strings/capitalize} instead
jQuery.sap.checkMouseEnterOrLeave

Checks a given mouseover or mouseout event whether it is equivalent to a mouseenter or mousleave event regarding the given DOM reference.

since: 1.58 use {@link module:sap/ui/events/checkMouseEnterOrLeave} instead
jQuery.sap.clearDelayedCall

Stops the delayed call.

The function given when calling delayedCall is not called anymore.

since: 1.58 use native <code>clearTimeout</code> instead
jQuery.sap.clearIntervalCall

Stops the interval call.

The function given when calling intervalCall is not called anymore.

since: 1.58 use native <code>clearInterval</code> instead
jQuery.sap.clearUrlWhitelist

Clears the allowlist for URL validation.

since: 1.58 use {@link module:sap/base/security/URLListValidator.clear} instead. SAP strives to replace insensitive terms with inclusive language, but APIs cannot be renamed or immediately removed for compatibility reasons.
jQuery.sap.containsOrEquals

Returns whether oDomRefChild is contained in or equal to oDomRefContainer.

For compatibility reasons it returns true if oDomRefContainer and oDomRefChild are equal.

This method intentionally does not operate on the jQuery object, as the original jQuery.contains() method also does not do so.

since: 1.58 use {@link module:sap/ui/dom/containsOrEquals} instead
jQuery.sap.declare

Declares a module as existing.

By default, this function assumes that the module will create a JavaScript object with the same name as the module. As a convenience it ensures that the parent namespace for that object exists (by calling jQuery.sap.getObject). If such an object creation is not desired, bCreateNamespace must be set to false.

since: 1.52 UI5 modules and their dependencies should be defined using {@link sap.ui.define}. For more details see {@link topic:91f23a736f4d1014b6dd926db0e91070 Modules and Dependencies} in the documentation.
jQuery.sap.delayedCall

Calls a method after a given delay and returns an id for this timer

since: 1.58 use native <code>setTimeout</code> instead
jQuery.sap.denormalizeScrollBeginRTL

For the given scroll position measured from the "beginning" of a container (the right edge in RTL mode) this method returns the scrollLeft value as understood by the current browser in RTL mode. This value is specific to the given DOM element, as the computation may involve its dimensions.

So when oDomRef should be scrolled 2px from the beginning, the number "2" must be given as iNormalizedScrollBegin and the result of this method (which may be a large or even negative number, depending on the browser) can then be set as oDomRef.scrollLeft to achieve the desired (cross-browser-consistent) scrolling position. Low values make the right part of the content visible, high values the left part.

This method does no scrolling on its own, it only calculates the value to set (so it can also be used for animations).

Only use this method in RTL mode, as the behavior in LTR mode is undefined and may change!

since: 1.58 use {@link module:sap/ui/dom/denormalizeScrollBeginRTL} instead
jQuery.sap.denormalizeScrollLeftRTL

For the given scrollLeft value this method returns the scrollLeft value as understood by the current browser in RTL mode. This value is specific to the given DOM element, as the computation may involve its dimensions.

So when oDomRef should be scrolled 2px from the leftmost position, the number "2" must be given as iNormalizedScrollLeft and the result of this method (which may be a large or even negative number, depending on the browser) can then be set as oDomRef.scrollLeft to achieve the desired (cross-browser-consistent) scrolling position.

This method does no scrolling on its own, it only calculates the value to set (so it can also be used for animations).

since: 1.58 use {@link module:sap/ui/dom/denormalizeScrollLeftRTL} instead
jQuery.sap.disableTouchToMouseHandling

Disable touch to mouse handling

since: 1.58 use {@link module:sap/ui/events/jquery/EventSimulation.disableTouchToMouseHandling} instead
jQuery.sap.domById

Shortcut for document.getElementById().

since: 1.58 use <code>document.getElementById</code> instead
jQuery.sap.encodeCSS

Encode the string for inclusion into CSS string literals or identifiers

since: 1.58 use {@link module:sap/base/security/encodeCSS} instead
jQuery.sap.encodeHTML

Encode the string for inclusion into HTML content/attribute

since: 1.58 use {@link module:sap/base/security/encodeXML} instead
jQuery.sap.encodeJS

Encode the string for inclusion into a JS string literal

since: 1.58 use {@link module:sap/base/security/encodeJS} instead
jQuery.sap.encodeURL

Encode the string for inclusion into a URL parameter

since: 1.58 use {@link module:sap/base/security/encodeURL} instead
jQuery.sap.encodeURLParameters

Encode a map of parameters into a combined URL parameter string

since: 1.58 use {@link module:sap/base/security/encodeURLParameters} instead
jQuery.sap.encodeXML

Encode the string for inclusion into XML content/attribute

since: 1.58 use {@link module:sap/base/security/encodeXML} instead
jQuery.sap.endsWith

Checks whether a given sString ends with sEndString respecting the case of the strings.

since: 1.58 use the native solution <code>String#endsWith</code>
jQuery.sap.endsWithIgnoreCase

Checks whether a given sString ends with sEndString ignoring the case of the strings.

References:

  • jQuery.sap.endsWith

since: 1.58 use the native solution <code>sString.toLowerCase().endsWith(sEndString.toLowerCase())</code>
jQuery.sap.equal

Compares the two given values for equality, especially takes care not to compare arrays and objects by reference, but compares their content. Note: function does not work with comparing XML objects

since: 1.58 use {@link module:sap/base/util/deepEqual} instead
jQuery.sap.escapeHTML

Encode the string for inclusion into HTML content/attribute. Old name "escapeHTML" kept for backward compatibility

since: 1.58 use {@link module:sap/base/security/encodeXML} instead
jQuery.sap.escapeJS

Encode the string for inclusion into a JS string literal. Old name "escapeJS" kept for backward compatibility

since: 1.58 use {@link module:sap/base/security/encodeJS} instead
jQuery.sap.escapeRegExp

Escapes all characters that would have a special meaning in a regular expression.

This method can be used when a string with arbitrary content has to be integrated into a regular expression and when the whole string should match literally.

Example:

  var text = "E=m*c^2"; // text to search
  var search = "m*c";   // text to search for

  text.match( new RegExp(                         search  ) ); // [ "c" ]
  text.match( new RegExp( jQuery.sap.escapeRegExp(search) ) ); // [ "m*c" ]

since: 1.58 use {@link module:sap/base/strings/escapeRegExp} instead
jQuery.sap.factory

Returns a new constructor function that creates objects with the given prototype.

As of 1.45.0, this method has been deprecated. Use the following code pattern instead:

  function MyFunction() {
  };
  MyFunction.prototype = oPrototype;

since: 1.45.0 define your own function and assign <code>oPrototype</code> to its <code>prototype</code> property instead.
jQuery.sap.focus

Calls focus() on the given DOM element.

since: 1.58 use <code>oDomRef.focus()</code> instead
jQuery.sap.formatMessage

Creates a string from a pattern by replacing placeholders with concrete values.

The syntax of the pattern is inspired by (but not fully equivalent to) the java.util.MessageFormat.

Placeholders have the form { integer }, where any occurrence of {0} is replaced by the value with index 0 in aValues, {1} by the value with index 1 in aValues etc.

To avoid interpretation of curly braces as placeholders, any non-placeholder fragment of the pattern can be enclosed in single quotes. The surrounding single quotes will be omitted from the result. Single quotes that are not meant to escape a fragment and that should appear in the result, need to be doubled. In the result, only a single single quote will occur.

Example Pattern Strings:

  jQuery.sap.formatMessage("Say {0}",     ["Hello"]) -> "Say Hello"    // normal use case
  jQuery.sap.formatMessage("Say '{0}'",   ["Hello"]) -> "Say {0}"      // escaped placeholder
  jQuery.sap.formatMessage("Say ''{0}''", ["Hello"]) -> "Say 'Hello'"  // doubled single quote
  jQuery.sap.formatMessage("Say '{0}'''", ["Hello"]) -> "Say {0}'"     // doubled single quote in quoted fragment

In contrast to java.util.MessageFormat, format types or format styles are not supported. Everything after the argument index and up to the first closing curly brace is ignored. Nested placeholders (as supported by java.lang.MessageFormat for the format type choice) are not ignored but reported as a parse error.

This method throws an Error when the pattern syntax is not fulfilled (e.g. unbalanced curly braces, nested placeholders or a non-numerical argument index).

This method can also be used as a formatter within a binding. The first part of a composite binding will be used as pattern, the following parts as aValues. If there is only one value and this value is an array it will be handled like the default described above.

since: 1.58 use {@link module:sap/base/strings/formatMessage} instead
jQuery.sap.getAllDeclaredModules

Returns the names of all declared modules.

References:

  • jQuery.sap.isDeclared

jQuery.sap.getModulePath

Constructs a URL to load the module with the given name and file type (suffix).

Searches the longest prefix of the given module name for which a registration exists (see jQuery.sap.registerModulePath) and replaces that prefix by the registered URL prefix.

The remainder of the module name is appended to the URL, replacing any dot with a slash.

Finally, the given suffix (typically a file name extension) is added (unconverted).

The returned name (without the suffix) doesn't end with a slash.

since: 1.58 use {@link sap.ui.require.toUrl} instead
jQuery.sap.getObject

Returns a JavaScript object which is identified by a sequence of names.

A call to getObject("a.b.C") has essentially the same effect as accessing window.a.b.C but with the difference that missing intermediate objects (a or b in the example above) don't lead to an exception.

When the addressed object exists, it is simply returned. If it doesn't exists, the behavior depends on the value of the second, optional parameter iNoCreates (assuming 'n' to be the number of names in the name sequence):

  • NaN: if iNoCreates is not a number and the addressed object doesn't exist, then getObject() returns undefined.
  • 0 < iNoCreates < n: any non-existing intermediate object is created, except the last iNoCreates ones.

Example:

  getObject()            -- returns the context object (either param or window)
  getObject("a.b.C")     -- will only try to get a.b.C and return undefined if not found.
  getObject("a.b.C", 0)  -- will create a, b, and C in that order if they don't exists
  getObject("a.b.c", 1)  -- will create a and b, but not C.

When a oContext is given, the search starts in that object. Otherwise it starts in the window object that this plugin has been created in.

Note: Although this method internally uses object["key"] to address object properties, it does not support all possible characters in a name. Especially the dot ('.') is not supported in the individual name segments, as it is always interpreted as a name separator.

since: 1.58 use {@link module:sap/base/util/ObjectPath.get} or {@link module:sap/base/util/ObjectPath.set} instead
jQuery.sap.getResourceName

Converts a UI5 module name to a unified resource name.

Used by View and Fragment APIs to convert a given module name into a unified resource name. When the sSuffix is not given, the suffix '.js' is added. This fits the most common use case of converting a module name to the Javascript resource that contains the module. Note that an empty sSuffix is not replaced by '.js'. This allows to convert UI5 module names to requireJS module names with a call to this method.

jQuery.sap.getResourcePath

Determines the URL for a resource given its unified resource name.

Searches the longest prefix of the given resource name for which a registration exists (see jQuery.sap.registerResourcePath) and replaces that prefix by the registered URL prefix.

The remainder of the resource name is appended to the URL.

Unified Resource Names
Several UI5 APIs use Unified Resource Names (URNs) as naming scheme for resources that they deal with (e.h. Javascript, CSS, JSON, XML, ...). URNs are similar to the path component of a URL:

  • they consist of a non-empty sequence of name segments
  • segments are separated by a forward slash '/'
  • name segments consist of URL path segment characters only. It is recommended to use only ASCII letters (upper or lower case), digits and the special characters '$', '_', '-', '.')
  • the empty name segment is not supported
  • names consisting of dots only, are reserved and must not be used for resources
  • names are case sensitive although the underlying server might be case-insensitive
  • the behavior with regard to URL encoded characters is not specified, %ddd notation should be avoided
  • the meaning of a leading slash is undefined, but might be defined in future. It therefore should be avoided

UI5 APIs that only deal with Javascript resources, use a slight variation of this scheme, where the extension '.js' is always omitted (see sap.ui.define, sap.ui.require).

Relationship to old Module Name Syntax

Older UI5 APIs that deal with resources (like jQuery.sap.registerModulePath, jQuery.sap.require and jQuery.sap.declare) used a dot-separated naming scheme (called 'module names') which was motivated by object names in the global namespace in Javascript.

The new URN scheme better matches the names of the corresponding resources (files) as stored in a server and the dot ('.') is no longer a forbidden character in a resource name. This finally allows to handle resources with different types (extensions) with the same API, not only JS files.

Last but not least does the URN scheme better match the naming conventions used by AMD loaders (like requireJS).

since: 1.58 use {@link sap.ui.require.toUrl} instead
jQuery.sap.getter

Returns a new function that returns the given oValue (using its closure).

Avoids the need for a dedicated member for the value.

As closures don't come for free, this function should only be used when polluting the enclosing object is an absolute "must-not" (as it is the case in public base classes).

jQuery.sap.getUriParameters

Creates and returns a new instance of jQuery.sap.util.UriParameters.

Example for reading a single URI parameter (or the value of the first occurrence of the URI parameter):

	var sValue = jQuery.sap.getUriParameters().get("myUriParam");

Example for reading the values of the first of the URI parameter (with multiple occurrences):

	var aValues = jQuery.sap.getUriParameters().get("myUriParam", true);
	for(i in aValues){
	var sValue = aValues[i];
	}

since: 1.68 use {@link module:sap/base/util/UriParameters.fromQuery UriParameters.fromQuery} or {@link module:sap/base/util/UriParameters.fromURL UriParameters.fromURL} instead.
jQuery.sap.getUrlWhitelist

Gets the allowlist for URL validation.

since: 1.58 use {@link module:sap/base/security/URLListValidator.entries} instead. SAP strives to replace insensitive terms with inclusive language, but APIs cannot be renamed or immediately removed for compatibility reasons.
jQuery.sap.globalEval

Executes an 'eval' for its arguments in the global context (without closure variables).

This is a synchronous replacement for jQuery.globalEval which in some browsers (e.g. FireFox) behaves asynchronously.

Note: To avoid potential violations of your content security policy (CSP), this API should not be used.

jQuery.sap.hashCode

This function generates a hash-code from a string

since: 1.58 use {@link module:sap/base/strings/hash} instead
jQuery.sap.hyphen

Transforms a camel case string into a hyphen separated string.

since: 1.58 use {@link module:sap/base/strings/hyphenate} instead
jQuery.sap.includeScript

Includes the script (via <script>-tag) into the head for the specified sUrl and optional sId.

since: 1.58 use {@link module:sap/ui/dom/includeScript} instead
jQuery.sap.includeStyleSheet

Includes the specified stylesheet via a <link>-tag in the head of the current document. If there is call to includeStylesheet providing the sId of an already included stylesheet, the existing element will be replaced.

since: 1.58 use {@link module:sap/ui/dom/includeStylesheet} instead
jQuery.sap.initMobile

Does some basic modifications to the HTML page that make it more suitable for mobile apps. Only the first call to this method is executed, subsequent calls are ignored. Note that this method is also called by the constructor of toplevel controls like sap.m.App, sap.m.SplitApp and sap.m.Shell. Exception: if no homeIcon was set, subsequent calls have the chance to set it.

The "options" parameter configures what exactly should be done.

It can have the following properties:

  • viewport: whether to set the viewport in a way that disables zooming (default: true)
  • statusBar: the iOS status bar color, "default", "black" or "black-translucent" (default: "default")
  • hideBrowser: whether the browser UI should be hidden as far as possible to make the app feel more native (default: true)
  • preventScroll: whether native scrolling should be disabled in order to prevent the "rubber-band" effect where the whole window is moved (default: true)
  • preventPhoneNumberDetection: whether Safari Mobile should be prevented from transforming any numbers that look like phone numbers into clickable links; this should be left as "true", otherwise it might break controls because Safari actually changes the DOM. This only affects all page content which is created after initMobile is called.
  • rootId: the ID of the root element that should be made fullscreen; only used when hideBrowser is set (default: the document.body)
  • useFullScreenHeight: a boolean that defines whether the height of the html root element should be set to 100%, which is required for other elements to cover the full height (default: true)
  • homeIcon: deprecated since 1.12, use jQuery.sap.setIcons instead.

since: 1.58 use {@link module:sap/ui/util/Mobile.init} instead
jQuery.sap.intervalCall

Calls a method after a given interval and returns an id for this interval.

since: 1.58 use native <code>setInterval</code> instead
jQuery.sap.isDeclared

Check whether a given module has been loaded / declared already.

Returns true as soon as a module has been required the first time, even when loading/executing it has not finished yet. So the main assertion of a return value of true is that the necessary actions have been taken to make the module available in the near future. It does not mean, that the content of the module is already available!

This fuzzy behavior is necessary to avoid multiple requests for the same module. As a consequence of the assertion above, a preloaded module does not count as declared. For preloaded modules, an explicit call to jQuery.sap.require is necessary to make them available.

If a caller wants to know whether a module needs to be loaded from the server, it can set bIncludePreloaded to true. Then, preloaded modules will be reported as 'declared' as well by this method.

since: 1.58 use {@link sap.ui.require} instead
jQuery.sap.isResourceLoaded

Whether the given resource has been loaded (or preloaded).

jQuery.sap.isSpecialKey

Detect whether the pressed key is: SHIFT, CONTROL, ALT, BREAK, CAPS_LOCK, PAGE_UP, PAGE_DOWN, END, HOME, ARROW_LEFT, ARROW_UP, ARROW_RIGHT, ARROW_DOWN, PRINT, INSERT, DELETE, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, BACKSPACE, TAB, ENTER, ESCAPE

since: 1.58 use {@link module:sap/ui/events/isSpecialKey} instead
jQuery.sap.newObject

Returns a new object which has the given oPrototype as its prototype.

If several objects with the same prototype are to be created, jQuery.sap.factory should be used instead.

since: 1.45.0 use <code>Object.create(oPrototype)</code> instead.
jQuery.sap.now

Returns a high resolution timestamp in microseconds if supported by the environment, otherwise in milliseconds. The timestamp is based on 01/01/1970 00:00:00 (UNIX epoch) as float with microsecond precision or with millisecond precision, if high resolution timestamps are not available. The fractional part of the timestamp represents fractions of a millisecond. Converting to a Date is possible by using require(["sap/base/util/now"], function(now){new Date(now());}

since: 1.58 use {@link module:sap/base/util/now} instead
jQuery.sap.ownerWindow

Returns the window reference for a DomRef.

since: 1.58 use {@link module:sap/ui/dom/getOwnerWindow} instead
jQuery.sap.padLeft

Pads a string on the left side until is has at least the given length.

The method always adds full copies of sPadChar to the given string. When sPadChar has a length > 1, the length of the returned string actually might be greater than iLength.

since: 1.58 use the native <code>String#padStart</code> instead
jQuery.sap.padRight

Pads a string on the right side until is has at least the given length.

The method always adds full copies of sPadChar to the given string. When sPadChar has a length > 1, the length of the returned string actually might be greater than iLength.

since: 1.58 use the native <code>String#padEnd</code> instead
jQuery.sap.parseXML

Parses the specified XML formatted string text using native parsing function of the browser and returns a valid XML document. If an error occurred during parsing a parse error object is returned as property (parseError) of the returned XML document object. The parse error object has the following error information parameters: errorCode, url, reason, srcText, line, linepos, filepos

since: 1.58 use {@link module:sap/ui/util/XMLHelper.parse} instead
jQuery.sap.properties

Creates and returns a new instance of jQuery.sap.util.Properties.

If option 'url' is passed, immediately a load request for the given target is triggered. A property file that is loaded can contain comments with a leading ! or #. The loaded property list does not contain any comments.

Example for loading a property file:

 jQuery.sap.properties({url : "../myProperty.properties"});

Example for creating an empty properties instance:

 jQuery.sap.properties();

Examples for getting and setting properties:

	var oProperties = jQuery.sap.properties();
	oProperties.setProperty("KEY_1","Test Key");
	var sValue1 = oProperties.getProperty("KEY_1");
	var sValue2 = oProperties.getProperty("KEY_2","Default");

since: 1.58 use {@link module:sap/base/util/Properties.create} instead
jQuery.sap.registerModulePath

Registers a URL prefix for a module name prefix.

Before a module is loaded, the longest registered prefix of its module name is searched for and the associated URL prefix is used as a prefix for the request URL. The remainder of the module name is attached to the request URL by replacing dots ('.') with slashes ('/').

The registration and search operates on full name segments only. So when a prefix

'sap.com' -> 'http://www.sap.com/ui5/resources/'

is registered, then it will match the name

'sap.com.Button'

but not

'sap.commons.Button'

Note that the empty prefix ('') will always match and thus serves as a fallback for any search.

The prefix can either be given as string or as object which contains the url and a 'final' property. If 'final' is set to true, overwriting a module prefix is not possible anymore.

since: 1.58 set path mappings via {@link sap.ui.loader.config} instead.
jQuery.sap.registerModuleShims

Register information about third party modules that are not UI5 modules.

The information maps the name of the module (without extension '.js') to an info object. Instead of a complete info object, only the value of the deps property can be given as an array.

since: 1.58 use {@link sap.ui.loader.config} instead
jQuery.sap.registerPreloadedModules

Adds all resources from a preload bundle to the preload cache.

When a resource exists already in the cache, the new content is ignored.

jQuery.sap.registerResourcePath

Registers a URL prefix for a resource name prefix.

Before a resource is loaded, the longest registered prefix of its unified resource name is searched for and the associated URL prefix is used as a prefix for the request URL. The remainder of the resource name is attached to the request URL 1:1.

The registration and search operates on full name segments only. So when a prefix

'sap/com' -> 'http://www.sap.com/ui5/resources/'

is registered, then it will match the name

'sap/com/Button'

but not

'sap/commons/Button'

Note that the empty prefix ('') will always match and thus serves as a fallback for any search.

The url prefix can either be given as string or as object which contains the url and a final flag. If final is set to true, overwriting a resource name prefix is not possible anymore.

since: 1.58 set path mappings via {@link sap.ui.loader.config} instead.
jQuery.sap.removeUrlWhitelist

Removes an allowlist entry for URL validation.

since: 1.58 use {@link module:sap/base/security/URLListValidator.clear} and {@link module:sap/base/security/URLListValidator.add} instead. SAP strives to replace insensitive terms with inclusive language, but APIs cannot be renamed or immediately removed for compatibility reasons.
jQuery.sap.require

Ensures that the given module is loaded and executed before execution of the current script continues.

By issuing a call to this method, the caller declares a dependency to the listed modules.

Any required and not yet loaded script will be loaded and execute synchronously. Already loaded modules will be skipped.

since: 1.52 UI5 modules and their dependencies should be defined using {@link sap.ui.define}. When additional modules have to be loaded dynamically at a later point in time, the asynchronous API {@link sap.ui.require} should be used. For more details, see {@link topic:91f23a736f4d1014b6dd926db0e91070 Modules and Dependencies} in the documentation.
jQuery.sap.resources

Creates and returns a new instance of jQuery.sap.util.ResourceBundle using the given URL and locale to determine what to load.

since: 1.58 Use {@link module:sap/base/i18n/ResourceBundle} instead.
jQuery.sap.resources.isBundle

Checks if the given object is an instance of jQuery.sap.util.ResourceBundle.

since: 1.58 Use the instanceof operator together with the class {@link module:sap/base/i18n/ResourceBundle} instead.
jQuery.sap.scrollbarSize

Returns the size (width of the vertical / height of the horizontal) native browser scrollbars.

This function must only be used when the DOM is ready.

since: 1.58 use {@link module:sap/ui/dom/getScrollbarSize} instead
jQuery.sap.serializeXML

Serializes the specified XML document into a string representation.

since: 1.58 use {@link module:sap/ui/util/XMLHelper.serialize} instead
jQuery.sap.setIcons

Sets the bookmark icon for desktop browsers and the icon to be displayed on the home screen of iOS devices after the user does "add to home screen".

Only call this method once and call it early when the page is loading: browsers behave differently when the favicon is modified while the page is alive. Some update the displayed icon inside the browser but use an old icon for bookmarks. When a favicon is given, any other existing favicon in the document will be removed. When at least one home icon is given, all existing home icons will be removed and new home icon tags for all four resolutions will be created.

The home icons must be in PNG format and given in different sizes for iPad/iPhone with and without retina display. The favicon is used in the browser and for desktop shortcuts and should optimally be in ICO format: ICO files can contain different image sizes for different usage locations. E.g. a 16x16px version is used inside browsers.

All icons are given in an an object holding icon URLs and other settings. The properties of this object are:

  • phone: a 60x60 pixel version for non-retina iPhones
  • tablet: a 76x76 pixel version for non-retina iPads
  • phone@2: a 120x120 pixel version for retina iPhones
  • tablet@2: a 152x152 pixel version for retina iPads
  • precomposed: whether the home icons already have some glare effect (otherwise iOS will add it) (default: false)
  • favicon: the ICO file to be used inside the browser and for desktop shortcuts

One example is:

{
   'phone':'phone-icon_60x60.png',
   'phone@2':'phone-retina_120x120.png',
   'tablet':'tablet-icon_76x76.png',
   'tablet@2':'tablet-retina_152x152.png',
   'precomposed':true,
   'favicon':'desktop.ico'
}
If one of the sizes is not given, the largest available alternative image will be used instead for this size. On Android these icons may or may not be used by the device. Apparently chances can be improved by using icons with glare effect, so the "precomposed" property can be set to "true". Some Android devices may also use the favicon for bookmarks instead of the home icons.

since: 1.58 use {@link module:sap/ui/util/Mobile.setIcons} instead
jQuery.sap.setMobileWebAppCapable

Sets the "apple-mobile-web-app-capable" and "mobile-web-app-capable" meta information which defines whether the application is loaded in full screen mode (browser address bar and toolbar are hidden) after the user does "add to home screen" on mobile devices. Currently this meta tag is only supported by iOS Safari and mobile Chrome from version 31.

If the application opens new tabs because of attachments, url and so on, setting this to false will let the user be able to go from the new tab back to the application tab after the application is added to home screen.

Note: this function only has effect when the application runs on iOS Safari and mobile Chrome from version 31.

since: 1.58 use {@link module:sap/ui/util/Mobile.setWebAppCapable} instead
jQuery.sap.setObject

Sets an object property to a given value, where the property is identified by a sequence of names (path).

When a oContext is given, the path starts in that object. Otherwise it starts in the window object that this plugin has been created for.

Note: Although this method internally uses object["key"] to address object properties, it does not support all possible characters in a name. Especially the dot ('.') is not supported in the individual name segments, as it is always interpreted as a name separator.

since: 1.58 use {@link module:sap/base/util/ObjectPath.set} instead
jQuery.sap.sjax

Convenience wrapper around jQuery.ajax() that avoids the need for callback functions when synchronous calls are made. If the setting complexResult is true (default), then the return value is an object with the following properties

  • success boolean whether the call succeeded or not
  • data any the data returned by the call. For dataType 'text' this is a string, for JSON it is an object, for XML it is a document. When the call failed, then data is not defined
  • status string a textual status ('success,', 'error', 'timeout',...)
  • statusCode string the HTTP status code of the request
  • error Error an error object (exception) in case an error occurred
  • errorText string an error message in case an error occurred

When complexResult is false, then in the case of success, only 'data' is returned, in case of an error the 'fallback' setting is returned (defaults to undefined).

Note that async=false is always enforced by this method.

since: 1.58 It is no longer recommended to use synchronous calls at all. There are alternatives like native <code>XMLHttpRequest</code> or <code>jQuery.ajax</code> but try to avoid the sync flag. There will be no replacement for <code>jQuery.sap.sjax</code>.
jQuery.sap.startsWith

Checks whether a given sString starts with sStartString respecting the case of the strings.

since: 1.58 use the native <code>String#startsWith</code>
jQuery.sap.startsWithIgnoreCase

Checks whether a given sString starts with sStartString ignoring the case of both strings.

References:

  • jQuery.sap.startsWith

since: 1.58 use the native solution <code>sString.toLowerCase().startsWith(sEndString.toLowerCase())</code>
jQuery.sap.syncGet

Convenience wrapper for jQuery.sap.sjax that enforeces the Http method GET and defaults the data type of the result to 'text'.

since: 1.58 see {@link jQuery.sap.sjax}
jQuery.sap.syncGetJSON

Convenience wrapper for jQuery.sap.sjax that enforces the Http method GET and the data type 'json'. If a fallback value is given, the function simply returns the response as an object or - if some error occurred - the fallback value. This is useful for applications that don't require detailed error diagnostics.

If applications need to know about occurring errors, they can either call sjax() directly or they can omit the fallback value (providing only two parameters to syncGetJSON()). They then receive the same complex result object as for the sjax() call.

Note that providing "undefined" or "null" as a fallback is different from omitting the fallback (complex result).

since: 1.58 see {@link jQuery.sap.sjax}
jQuery.sap.syncGetText

Convenience wrapper for jQuery.sap.sjax that enforces the Http method GET and the data type 'text'. If a fallback value is given, the function simply returns the response as a text or - if some error occurred - the fallback value. This is useful for applications that don't require detailed error diagnostics.

If applications need to know about occurring errors, they can either call sjax() directly or they can omit the fallback value (providing only two parameters to syncGetText()). They then receive the same complex result object as for the sjax() call.

since: 1.58 see {@link jQuery.sap.sjax}
jQuery.sap.syncPost

Convenience wrapper for jQuery.sap.sjax that enforces the Http method POST and defaults the data type of the result to 'text'.

since: 1.58 see {@link jQuery.sap.sjax}
jQuery.sap.syncStyleClass

Search ancestors of the given source DOM element for the specified CSS class name. If the class name is found, set it to the root DOM element of the target control. If the class name is not found, it is also removed from the target DOM element.

since: 1.58 use {@link module:sap/ui/core/syncStyleClass} instead
jQuery.sap.uid

Creates and returns a pseudo-unique id.

No means for detection of overlap with already present or future UIDs.

since: 1.58 use {@link module:sap/base/util/uid} instead
jQuery.sap.unbindAnyEvent

Unbinds all events for listening with the given callback function.

since: 1.58 use {@link module:sap/ui/events/ControlEvents.unbindAnyEvent} instead
jQuery.sap.unique

Sorts the given array in-place and removes any duplicates (identified by "===").

Use jQuery.uniqueSort() for arrays of DOMElements.

since: 1.58 use {@link module:sap/base/util/array/uniqueSort} instead
jQuery.sap.validateUrl

Validates a URL. Check if it's not a script or other security issue.

By default the URL validation does only allow the http, https and ftp protocol. If other protocols are required, an allowlist of all allowed protocols needs to be defined.

Split URL into components and check for allowed characters according to RFC 3986:

authority     = [ userinfo "@" ] host [ ":" port ]
userinfo      = *( unreserved / pct-encoded / sub-delims / ":" )
host          = IP-literal / IPv4address / reg-name

IP-literal    = "[" ( IPv6address / IPvFuture  ) "]"
IPvFuture     = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )
IPv6address   =                            6( h16 ":" ) ls32
              /                       "::" 5( h16 ":" ) ls32
              / [               h16 ] "::" 4( h16 ":" ) ls32
              / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32
              / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32
              / [ *3( h16 ":" ) h16 ] "::"    h16 ":"   ls32
              / [ *4( h16 ":" ) h16 ] "::"              ls32
              / [ *5( h16 ":" ) h16 ] "::"              h16
              / [ *6( h16 ":" ) h16 ] "::"
ls32          = ( h16 ":" h16 ) / IPv4address
              ; least-significant 32 bits of address
h16           = 1*4HEXDIG
              ; 16 bits of address represented in hexadecimal

IPv4address   = dec-octet "." dec-octet "." dec-octet "." dec-octet
dec-octet     = DIGIT                 ; 0-9
              / %x31-39 DIGIT         ; 10-99
              / "1" 2DIGIT            ; 100-199
              / "2" %x30-34 DIGIT     ; 200-249
              / "25" %x30-35          ; 250-255

reg-name      = *( unreserved / pct-encoded / sub-delims )

pct-encoded   = "%" HEXDIG HEXDIG
reserved      = gen-delims / sub-delims
gen-delims    = ":" / "/" / "?" / "#" / "[" / "]" / "@"
sub-delims    = "!" / "$" / "&" / "'" / "(" / ")"
              / "*" / "+" / "," / ";" / "="
unreserved    = ALPHA / DIGIT / "-" / "." / "_" / "~"
pchar         = unreserved / pct-encoded / sub-delims / ":" / "@"

path          = path-abempty    ; begins with "/" or is empty
              / path-absolute   ; begins with "/" but not "//"
              / path-noscheme   ; begins with a non-colon segment
              / path-rootless   ; begins with a segment
              / path-empty      ; zero characters

path-abempty  = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty    = 0
segment       = *pchar
segment-nz    = 1*pchar
segment-nz-nc = 1*( unreserved / pct-encoded / sub-delims / "@" )
              ; non-zero-length segment without any colon ":"

query         = *( pchar / "/" / "?" )

fragment      = *( pchar / "/" / "?" )

For the hostname component, we are checking for valid DNS hostnames according to RFC 952 / RFC 1123:

hname         = name *("." name)
name          = let-or-digit ( *( let-or-digit-or-hyphen ) let-or-digit )

When the URI uses the protocol 'mailto:', the address part is additionally checked against the most commonly used parts of RFC 6068:

mailtoURI     = "mailto:" [ to ] [ hfields ]
to            = addr-spec *("," addr-spec )
hfields       = "?" hfield *( "&" hfield )
hfield        = hfname "=" hfvalue
hfname        = *qchar
hfvalue       = *qchar
addr-spec     = local-part "@" domain
local-part    = dot-atom-text              // not accepted: quoted-string
domain        = dot-atom-text              // not accepted: "[" *dtext-no-obs "]"
dtext-no-obs  = %d33-90 / ; Printable US-ASCII
                %d94-126  ; characters not including
                          ; "[", "]", or "\"
qchar         = unreserved / pct-encoded / some-delims
some-delims   = "!" / "$" / "'" / "(" / ")" / "*"
              / "+" / "," / ";" / ":" / "@"

Note:
A number of characters that can appear in <addr-spec> MUST be
percent-encoded.  These are the characters that cannot appear in
a URI according to [STD66] as well as "%" (because it is used for
percent-encoding) and all the characters in gen-delims except "@"
and ":" (i.e., "/", "?", "#", "[", and "]").  Of the characters
in sub-delims, at least the following also have to be percent-
encoded: "&", ";", and "=".  Care has to be taken both when
encoding as well as when decoding to make sure these operations
are applied only once.

When an allowlist has been configured using add, any URL that passes the syntactic checks above, additionally will be tested against the content of the allowlist.

since: 1.58 use {@link module:sap/base/security/URLListValidator.validate} instead.

jQuery.sap._loadJSResourceAsync

Loads the given Javascript resource (URN) asynchronously via as script tag. Returns a promise that will be resolved when the load event is fired or reject when the error event is fired.

Note: execution errors of the script are not reported as 'error'.

This method is not a full implementation of require. It is intended only for loading "preload" files that do not define an own module / module value.

Functionality might be removed/renamed in future, so no code outside the sap.ui.core library must use it.

Param Type DefaultValue Description

jQuery.sap.addUrlWhitelist

Adds an allowlist entry for URL validation.

since: 1.58 use {@link module:sap/base/security/URLListValidator.add} instead. SAP strives to replace insensitive terms with inclusive language, but APIs cannot be renamed or immediately removed for compatibility reasons.
Param Type DefaultValue Description
protocol string

The protocol of the URL, can be falsy to allow all protocols for an entry e.g. "", "http", "mailto"

host string

The host of the URL, can be falsy to allow all hosts. A wildcard asterisk can be set at the beginning, e.g. "examples.com", "*.example.com"

port string

The port of the URL, can be falsy to allow all ports, e.g. "", "8080"

path string

the path of the URL, path of the url, can be falsy to allow all paths. A wildcard asterisk can be set at the end, e.g. "/my-example*", "/my-news"

jQuery.sap.arrayDiff

Calculate delta of old list and new list.

This partly implements the algorithm described in "A Technique for Isolating Differences Between Files" but instead of working with hashes, it does compare each entry of the old list with each entry of the new list, which causes terrible performance on large datasets.

since: 1.38 use {@link module:sap/base/util/array/diff} instead if applicable
Param Type DefaultValue Description
aOld Array

Old Array

aNew Array

New Array

fnCompare function

Function to compare list entries

bUniqueEntries boolean

Whether entries are unique, so no duplicate entries exist

jQuery.sap.arraySymbolDiff

Calculate delta of old list and new list.

This function implements the algorithm described in "A Technique for Isolating Differences Between Files" (Commun. ACM, April 1978, Volume 21, Number 4, Pages 264-268).

Items in the arrays are not compared directly. Instead, a substitute symbol is determined for each item by applying the provided function fnSymbol to it. Items with strictly equal symbols are assumed to represent the same logical item:

  fnSymbol(a) === fnSymbol(b)   <=>   a 'is logically the same as' b
As an additional constraint, casting the symbols to string should not modify the comparison result. If this second constraint is not met, this method might report more diffs than necessary.

If no symbol function is provided, a default implementation is used which applies JSON.stringify to non-string items and reduces the strings to a hash code. It is not guaranteed that this default implementation fulfills the above constraint in all cases, but it is a compromise between implementation effort, generality and performance. If items are known to be non-stringifiable (e.g. because they may contain cyclic references) or when hash collisions are likely, an own fnSymbol function must be provided.

The result of the diff is a sequence of update operations, each consisting of a type (either "insert" or "delete") and an index. By applying the operations one after the other to the old array, it can be transformed to an array whose items are equal to the new array.

Sample implementation of the update


 function update(aOldArray, aNewArray) {

   // calculate the diff
   var aDiff = jQuery.sap.arraySymbolDiff(aOldArray, aNewArray, __provide_your_symbol_function_here__);

   // apply update operations
   aDiff.forEach( function(op) {

     // invariant: aOldArray and aNewArray now are equal up to (excluding) op.index

     switch ( op.type ) {
     case 'insert':
       // new array contains a new (or otherwise unmapped) item, add it here
       aOldArray.splice(op.index, 0, aNewArray[op.index]);
       break;
     case 'delete':
       // an item is no longer part of the array (or has been moved to another position), remove it
       aOldArray.splice(op.index, 1);
       break;
     default:
       throw new Error('unexpected diff operation type');
     }

   });
 }

since: 1.58 use {@link module:sap/base/util/array/diff} instead
Param Type DefaultValue Description
aOld Array

Old Array

aNew Array

New Array

fnSymbol function

Function to calculate substitute symbols for array items

jQuery.sap.assert

A simple assertion mechanism that logs a message when a given condition is not met.

Note: Calls to this method might be removed when the JavaScript code is optimized during build. Therefore, callers should not rely on any side effects of this method.

since: 1.58 use {@link module:sap/base/assert} instead
Param Type DefaultValue Description
bResult boolean

Result of the checked assertion

vMessage string function

Message that will be logged when the result is false. In case this is a function, the return value of the function will be displayed. This can be used to execute complex code only if the assertion fails.

jQuery.sap.bindAnyEvent

Binds all events for listening with the given callback function.

since: 1.58 use {@link module:sap/ui/events/ControlEvents.bindAnyEvent} instead
Param Type DefaultValue Description
fnCallback function

Callback function

jQuery.sap.byId

Shortcut for jQuery("#" + id) with additionally the id being escaped properly. I.e.: returns the jQuery object for the DOM element with the given id

Use this method instead of jQuery(...) if you know the argument is exactly one id and the id is not known in advance because it is in a variable (as opposed to a string constant with known content).

since: 1.58 use <code>jQuery(document.getElementById(sId))</code> instead
Param Type DefaultValue Description
sId string

The id to search for and construct the jQuery object

oContext Element

the context DOM Element

jQuery.sap.camelCase

Transforms a hyphen separated string to a camel case string.

since: 1.58 use {@link module:sap/base/strings/camelize} instead
Param Type DefaultValue Description
sString string

Hyphen separated string

jQuery.sap.charToUpperCase

Converts one character of the string to upper case, at a given position.

If no position is given or when it is negative or beyond the last character of sString, then the first character will be converted to upper case. The first character position is 0.

since: 1.58 use {@link module:sap/base/strings/capitalize} instead
Param Type DefaultValue Description
sString string

String for which one character should be converted

iPos int

Position of the character that should be converted

jQuery.sap.checkMouseEnterOrLeave

Checks a given mouseover or mouseout event whether it is equivalent to a mouseenter or mousleave event regarding the given DOM reference.

since: 1.58 use {@link module:sap/ui/events/checkMouseEnterOrLeave} instead
Param Type DefaultValue Description
oEvent jQuery.Event
oDomRef Element

jQuery.sap.clearDelayedCall

Stops the delayed call.

The function given when calling delayedCall is not called anymore.

since: 1.58 use native <code>clearTimeout</code> instead
Param Type DefaultValue Description
sDelayedCallId string

The id returned, when calling delayedCall

jQuery.sap.clearIntervalCall

Stops the interval call.

The function given when calling intervalCall is not called anymore.

since: 1.58 use native <code>clearInterval</code> instead
Param Type DefaultValue Description
sIntervalCallId string

The id returned, when calling intervalCall

jQuery.sap.clearUrlWhitelist

Clears the allowlist for URL validation.

since: 1.58 use {@link module:sap/base/security/URLListValidator.clear} instead. SAP strives to replace insensitive terms with inclusive language, but APIs cannot be renamed or immediately removed for compatibility reasons.
Param Type DefaultValue Description

jQuery.sap.containsOrEquals

Returns whether oDomRefChild is contained in or equal to oDomRefContainer.

For compatibility reasons it returns true if oDomRefContainer and oDomRefChild are equal.

This method intentionally does not operate on the jQuery object, as the original jQuery.contains() method also does not do so.

since: 1.58 use {@link module:sap/ui/dom/containsOrEquals} instead
Param Type DefaultValue Description
oDomRefContainer Element

The container element

oDomRefChild Element

The child element (must not be a text node, must be an element)

jQuery.sap.declare

Declares a module as existing.

By default, this function assumes that the module will create a JavaScript object with the same name as the module. As a convenience it ensures that the parent namespace for that object exists (by calling jQuery.sap.getObject). If such an object creation is not desired, bCreateNamespace must be set to false.

since: 1.52 UI5 modules and their dependencies should be defined using {@link sap.ui.define}. For more details see {@link topic:91f23a736f4d1014b6dd926db0e91070 Modules and Dependencies} in the documentation.
Param Type DefaultValue Description
sModuleName string object

name of the module to be declared or in case of an object {modName: "...", type: "..."} where modName is the name of the module and the type could be a specific dot separated extension e.g. {modName: "sap.ui.core.Dev", type: "view"} loads sap/ui/core/Dev.view.js and registers as sap.ui.core.Dev.view

bCreateNamespace boolean true

whether to create the parent namespace

jQuery.sap.delayedCall

Calls a method after a given delay and returns an id for this timer

since: 1.58 use native <code>setTimeout</code> instead
Param Type DefaultValue Description
iDelay int

Delay time in milliseconds

oObject object

Object from which the method should be called

method string object

function pointer or name of the method

aParameters array

Method parameters

jQuery.sap.denormalizeScrollBeginRTL

For the given scroll position measured from the "beginning" of a container (the right edge in RTL mode) this method returns the scrollLeft value as understood by the current browser in RTL mode. This value is specific to the given DOM element, as the computation may involve its dimensions.

So when oDomRef should be scrolled 2px from the beginning, the number "2" must be given as iNormalizedScrollBegin and the result of this method (which may be a large or even negative number, depending on the browser) can then be set as oDomRef.scrollLeft to achieve the desired (cross-browser-consistent) scrolling position. Low values make the right part of the content visible, high values the left part.

This method does no scrolling on its own, it only calculates the value to set (so it can also be used for animations).

Only use this method in RTL mode, as the behavior in LTR mode is undefined and may change!

since: 1.58 use {@link module:sap/ui/dom/denormalizeScrollBeginRTL} instead
Param Type DefaultValue Description
iNormalizedScrollBegin int

The distance from the rightmost position to which the element should be scrolled

oDomRef Element

The DOM Element to which scrollLeft will be applied

jQuery.sap.denormalizeScrollLeftRTL

For the given scrollLeft value this method returns the scrollLeft value as understood by the current browser in RTL mode. This value is specific to the given DOM element, as the computation may involve its dimensions.

So when oDomRef should be scrolled 2px from the leftmost position, the number "2" must be given as iNormalizedScrollLeft and the result of this method (which may be a large or even negative number, depending on the browser) can then be set as oDomRef.scrollLeft to achieve the desired (cross-browser-consistent) scrolling position.

This method does no scrolling on its own, it only calculates the value to set (so it can also be used for animations).

since: 1.58 use {@link module:sap/ui/dom/denormalizeScrollLeftRTL} instead
Param Type DefaultValue Description
iNormalizedScrollLeft int

The distance from the leftmost position to which the element should be scrolled

oDomRef Element

The DOM Element to which scrollLeft will be applied

jQuery.sap.disableTouchToMouseHandling

Disable touch to mouse handling

since: 1.58 use {@link module:sap/ui/events/jquery/EventSimulation.disableTouchToMouseHandling} instead
Param Type DefaultValue Description

jQuery.sap.domById

Shortcut for document.getElementById().

since: 1.58 use <code>document.getElementById</code> instead
Param Type DefaultValue Description
sId string

The id of the DOM element to return

oWindow Window window

The window (optional)

jQuery.sap.encodeCSS

Encode the string for inclusion into CSS string literals or identifiers

since: 1.58 use {@link module:sap/base/security/encodeCSS} instead
Param Type DefaultValue Description
sString string

The string to be escaped

jQuery.sap.encodeHTML

Encode the string for inclusion into HTML content/attribute

since: 1.58 use {@link module:sap/base/security/encodeXML} instead
Param Type DefaultValue Description
sString string

The string to be escaped

jQuery.sap.encodeJS

Encode the string for inclusion into a JS string literal

since: 1.58 use {@link module:sap/base/security/encodeJS} instead
Param Type DefaultValue Description
sString string

The string to be escaped

jQuery.sap.encodeURL

Encode the string for inclusion into a URL parameter

since: 1.58 use {@link module:sap/base/security/encodeURL} instead
Param Type DefaultValue Description
sString string

The string to be escaped

jQuery.sap.encodeURLParameters

Encode a map of parameters into a combined URL parameter string

since: 1.58 use {@link module:sap/base/security/encodeURLParameters} instead
Param Type DefaultValue Description
mParams object

The map of parameters to encode

jQuery.sap.encodeXML

Encode the string for inclusion into XML content/attribute

since: 1.58 use {@link module:sap/base/security/encodeXML} instead
Param Type DefaultValue Description
sString string

The string to be escaped

jQuery.sap.endsWith

Checks whether a given sString ends with sEndString respecting the case of the strings.

since: 1.58 use the native solution <code>String#endsWith</code>
Param Type DefaultValue Description
sString string

String to be checked

sEndString string

The end string to be searched

jQuery.sap.endsWithIgnoreCase

Checks whether a given sString ends with sEndString ignoring the case of the strings.

References:

since: 1.58 use the native solution <code>sString.toLowerCase().endsWith(sEndString.toLowerCase())</code>
Param Type DefaultValue Description
sString string

String to be checked

sEndString string

The end string to be searched

jQuery.sap.equal

Compares the two given values for equality, especially takes care not to compare arrays and objects by reference, but compares their content. Note: function does not work with comparing XML objects

since: 1.58 use {@link module:sap/base/util/deepEqual} instead
Param Type DefaultValue Description
a any

A value of any type

b any

A value of any type

maxDepth int 10

Maximum recursion depth

contains boolean

Whether all existing properties in a are equal as in b

jQuery.sap.escapeHTML

Encode the string for inclusion into HTML content/attribute. Old name "escapeHTML" kept for backward compatibility

since: 1.58 use {@link module:sap/base/security/encodeXML} instead
Param Type DefaultValue Description
sString string

The string to be escaped

jQuery.sap.escapeJS

Encode the string for inclusion into a JS string literal. Old name "escapeJS" kept for backward compatibility

since: 1.58 use {@link module:sap/base/security/encodeJS} instead
Param Type DefaultValue Description
sString string

The string to be escaped

jQuery.sap.escapeRegExp

Escapes all characters that would have a special meaning in a regular expression.

This method can be used when a string with arbitrary content has to be integrated into a regular expression and when the whole string should match literally.

Example:

  var text = "E=m*c^2"; // text to search
  var search = "m*c";   // text to search for

  text.match( new RegExp(                         search  ) ); // [ "c" ]
  text.match( new RegExp( jQuery.sap.escapeRegExp(search) ) ); // [ "m*c" ]

since: 1.58 use {@link module:sap/base/strings/escapeRegExp} instead
Param Type DefaultValue Description
sString string

String to escape

jQuery.sap.factory

Returns a new constructor function that creates objects with the given prototype.

As of 1.45.0, this method has been deprecated. Use the following code pattern instead:

  function MyFunction() {
  };
  MyFunction.prototype = oPrototype;

since: 1.45.0 define your own function and assign <code>oPrototype</code> to its <code>prototype</code> property instead.
Param Type DefaultValue Description
oPrototype object

Prototype to use for the new objects

jQuery.sap.focus

Calls focus() on the given DOM element.

since: 1.58 use <code>oDomRef.focus()</code> instead
Param Type DefaultValue Description
oDomRef Element

The DOM element to focus (or null - in this case the method does nothing)

jQuery.sap.formatMessage

Creates a string from a pattern by replacing placeholders with concrete values.

The syntax of the pattern is inspired by (but not fully equivalent to) the java.util.MessageFormat.

Placeholders have the form { integer }, where any occurrence of {0} is replaced by the value with index 0 in aValues, {1} by the value with index 1 in aValues etc.

To avoid interpretation of curly braces as placeholders, any non-placeholder fragment of the pattern can be enclosed in single quotes. The surrounding single quotes will be omitted from the result. Single quotes that are not meant to escape a fragment and that should appear in the result, need to be doubled. In the result, only a single single quote will occur.

Example Pattern Strings:

  jQuery.sap.formatMessage("Say {0}",     ["Hello"]) -> "Say Hello"    // normal use case
  jQuery.sap.formatMessage("Say '{0}'",   ["Hello"]) -> "Say {0}"      // escaped placeholder
  jQuery.sap.formatMessage("Say ''{0}''", ["Hello"]) -> "Say 'Hello'"  // doubled single quote
  jQuery.sap.formatMessage("Say '{0}'''", ["Hello"]) -> "Say {0}'"     // doubled single quote in quoted fragment

In contrast to java.util.MessageFormat, format types or format styles are not supported. Everything after the argument index and up to the first closing curly brace is ignored. Nested placeholders (as supported by java.lang.MessageFormat for the format type choice) are not ignored but reported as a parse error.

This method throws an Error when the pattern syntax is not fulfilled (e.g. unbalanced curly braces, nested placeholders or a non-numerical argument index).

This method can also be used as a formatter within a binding. The first part of a composite binding will be used as pattern, the following parts as aValues. If there is only one value and this value is an array it will be handled like the default described above.

since: 1.58 use {@link module:sap/base/strings/formatMessage} instead
Param Type DefaultValue Description
sPattern string

A pattern string in the described syntax

aValues any[] []

The values to be used instead of the placeholders.

jQuery.sap.getAllDeclaredModules

Returns the names of all declared modules.

References:

Param Type DefaultValue Description

jQuery.sap.getModulePath

Constructs a URL to load the module with the given name and file type (suffix).

Searches the longest prefix of the given module name for which a registration exists (see jQuery.sap.registerModulePath) and replaces that prefix by the registered URL prefix.

The remainder of the module name is appended to the URL, replacing any dot with a slash.

Finally, the given suffix (typically a file name extension) is added (unconverted).

The returned name (without the suffix) doesn't end with a slash.

since: 1.58 use {@link sap.ui.require.toUrl} instead
Param Type DefaultValue Description
sModuleName string

module name to detemrine the path for

sSuffix string

suffix to be added to the resulting path

jQuery.sap.getObject

Returns a JavaScript object which is identified by a sequence of names.

A call to getObject("a.b.C") has essentially the same effect as accessing window.a.b.C but with the difference that missing intermediate objects (a or b in the example above) don't lead to an exception.

When the addressed object exists, it is simply returned. If it doesn't exists, the behavior depends on the value of the second, optional parameter iNoCreates (assuming 'n' to be the number of names in the name sequence):

Example:

  getObject()            -- returns the context object (either param or window)
  getObject("a.b.C")     -- will only try to get a.b.C and return undefined if not found.
  getObject("a.b.C", 0)  -- will create a, b, and C in that order if they don't exists
  getObject("a.b.c", 1)  -- will create a and b, but not C.

When a oContext is given, the search starts in that object. Otherwise it starts in the window object that this plugin has been created in.

Note: Although this method internally uses object["key"] to address object properties, it does not support all possible characters in a name. Especially the dot ('.') is not supported in the individual name segments, as it is always interpreted as a name separator.

since: 1.58 use {@link module:sap/base/util/ObjectPath.get} or {@link module:sap/base/util/ObjectPath.set} instead
Param Type DefaultValue Description
sName string

a dot separated sequence of names that identify the required object

iNoCreates int

number of objects (from the right) that should not be created

oContext object window

the context to execute the search in

jQuery.sap.getResourceName

Converts a UI5 module name to a unified resource name.

Used by View and Fragment APIs to convert a given module name into a unified resource name. When the sSuffix is not given, the suffix '.js' is added. This fits the most common use case of converting a module name to the Javascript resource that contains the module. Note that an empty sSuffix is not replaced by '.js'. This allows to convert UI5 module names to requireJS module names with a call to this method.

Param Type DefaultValue Description
sModuleName string

Module name as a dot separated name

sSuffix string '.js'

Suffix to add to the final resource name

jQuery.sap.getResourcePath

Determines the URL for a resource given its unified resource name.

Searches the longest prefix of the given resource name for which a registration exists (see jQuery.sap.registerResourcePath) and replaces that prefix by the registered URL prefix.

The remainder of the resource name is appended to the URL.

Unified Resource Names
Several UI5 APIs use Unified Resource Names (URNs) as naming scheme for resources that they deal with (e.h. Javascript, CSS, JSON, XML, ...). URNs are similar to the path component of a URL:

UI5 APIs that only deal with Javascript resources, use a slight variation of this scheme, where the extension '.js' is always omitted (see sap.ui.define, sap.ui.require).

Relationship to old Module Name Syntax

Older UI5 APIs that deal with resources (like jQuery.sap.registerModulePath, jQuery.sap.require and jQuery.sap.declare) used a dot-separated naming scheme (called 'module names') which was motivated by object names in the global namespace in Javascript.

The new URN scheme better matches the names of the corresponding resources (files) as stored in a server and the dot ('.') is no longer a forbidden character in a resource name. This finally allows to handle resources with different types (extensions) with the same API, not only JS files.

Last but not least does the URN scheme better match the naming conventions used by AMD loaders (like requireJS).

since: 1.58 use {@link sap.ui.require.toUrl} instead
Param Type DefaultValue Description
sResourceName string

unified resource name of the resource

jQuery.sap.getter

Returns a new function that returns the given oValue (using its closure).

Avoids the need for a dedicated member for the value.

As closures don't come for free, this function should only be used when polluting the enclosing object is an absolute "must-not" (as it is the case in public base classes).

Param Type DefaultValue Description
oValue object

The value that the getter should return

jQuery.sap.getUriParameters

Creates and returns a new instance of jQuery.sap.util.UriParameters.

Example for reading a single URI parameter (or the value of the first occurrence of the URI parameter):

	var sValue = jQuery.sap.getUriParameters().get("myUriParam");

Example for reading the values of the first of the URI parameter (with multiple occurrences):

	var aValues = jQuery.sap.getUriParameters().get("myUriParam", true);
	for(i in aValues){
	var sValue = aValues[i];
	}

since: 1.68 use {@link module:sap/base/util/UriParameters.fromQuery UriParameters.fromQuery} or {@link module:sap/base/util/UriParameters.fromURL UriParameters.fromURL} instead.
Param Type DefaultValue Description
sUri string

Uri to determine the parameters for

jQuery.sap.getUrlWhitelist

Gets the allowlist for URL validation.

since: 1.58 use {@link module:sap/base/security/URLListValidator.entries} instead. SAP strives to replace insensitive terms with inclusive language, but APIs cannot be renamed or immediately removed for compatibility reasons.
Param Type DefaultValue Description

jQuery.sap.globalEval

Executes an 'eval' for its arguments in the global context (without closure variables).

This is a synchronous replacement for jQuery.globalEval which in some browsers (e.g. FireFox) behaves asynchronously.

Note: To avoid potential violations of your content security policy (CSP), this API should not be used.

Param Type DefaultValue Description

jQuery.sap.hashCode

This function generates a hash-code from a string

since: 1.58 use {@link module:sap/base/strings/hash} instead
Param Type DefaultValue Description
sString string

The string to generate the hash-code from

jQuery.sap.hyphen

Transforms a camel case string into a hyphen separated string.

since: 1.58 use {@link module:sap/base/strings/hyphenate} instead
Param Type DefaultValue Description
sString string

camel case string

jQuery.sap.includeScript

Includes the script (via <script>-tag) into the head for the specified sUrl and optional sId.

since: 1.58 use {@link module:sap/ui/dom/includeScript} instead
Param Type DefaultValue Description
vUrl string object

the URL of the script to load or a configuration object

url string

the URL of the script to load

id string

id that should be used for the script tag

attributes object

map of attributes that should be used for the script tag

vId string object

id that should be used for the script tag or map of attributes

fnLoadCallback function

callback function to get notified once the script has been loaded

fnErrorCallback function

callback function to get notified once the script loading failed

jQuery.sap.includeStyleSheet

Includes the specified stylesheet via a <link>-tag in the head of the current document. If there is call to includeStylesheet providing the sId of an already included stylesheet, the existing element will be replaced.

since: 1.58 use {@link module:sap/ui/dom/includeStylesheet} instead
Param Type DefaultValue Description
vUrl string object

the URL of the stylesheet to load or a configuration object

url string

the URL of the stylesheet to load

id string

id that should be used for the link tag

attributes object

map of attributes that should be used for the script tag

vId string object

id that should be used for the link tag or map of attributes

fnLoadCallback function

callback function to get notified once the stylesheet has been loaded

fnErrorCallback function

callback function to get notified once the stylesheet loading failed.

jQuery.sap.initMobile

Does some basic modifications to the HTML page that make it more suitable for mobile apps. Only the first call to this method is executed, subsequent calls are ignored. Note that this method is also called by the constructor of toplevel controls like sap.m.App, sap.m.SplitApp and sap.m.Shell. Exception: if no homeIcon was set, subsequent calls have the chance to set it.

The "options" parameter configures what exactly should be done.

It can have the following properties:

since: 1.58 use {@link module:sap/ui/util/Mobile.init} instead
Param Type DefaultValue Description
options object

configures what exactly should be done

viewport boolean true

whether to set the viewport in a way that disables zooming

statusBar string 'default'

the iOS status bar color, "default", "black" or "black-translucent"

hideBrowser boolean true

whether the browser UI should be hidden as far as possible to make the app feel more native

preventScroll boolean true

whether native scrolling should be disabled in order to prevent the "rubber-band" effect where the whole window is moved

preventPhoneNumberDetection boolean true

whether Safari mobile should be prevented from transforming any numbers that look like phone numbers into clickable links

rootId string

the ID of the root element that should be made fullscreen; only used when hideBrowser is set. If not set, the body is used

useFullScreenHeight boolean true

whether the height of the html root element should be set to 100%, which is required for other elements to cover the full height

homeIcon string

deprecated since 1.12, use jQuery.sap.setIcons instead.

homeIconPrecomposed boolean false

deprecated since 1.12, use jQuery.sap.setIcons instead.

mobileWebAppCapable boolean true

whether the Application will be loaded in full screen mode after added to home screen on mobile devices. The default value for this property only enables the full screen mode when runs on iOS device.

jQuery.sap.intervalCall

Calls a method after a given interval and returns an id for this interval.

since: 1.58 use native <code>setInterval</code> instead
Param Type DefaultValue Description
iInterval int

Interval time in milliseconds

oObject object

Object from which the method should be called

method string object

function pointer or name of the method

aParameters array

Method parameters

jQuery.sap.isDeclared

Check whether a given module has been loaded / declared already.

Returns true as soon as a module has been required the first time, even when loading/executing it has not finished yet. So the main assertion of a return value of true is that the necessary actions have been taken to make the module available in the near future. It does not mean, that the content of the module is already available!

This fuzzy behavior is necessary to avoid multiple requests for the same module. As a consequence of the assertion above, a preloaded module does not count as declared. For preloaded modules, an explicit call to jQuery.sap.require is necessary to make them available.

If a caller wants to know whether a module needs to be loaded from the server, it can set bIncludePreloaded to true. Then, preloaded modules will be reported as 'declared' as well by this method.

since: 1.58 use {@link sap.ui.require} instead
Param Type DefaultValue Description
sModuleName string

name of the module to be checked

bIncludePreloaded boolean false

whether preloaded modules should be reported as declared.

jQuery.sap.isResourceLoaded

Whether the given resource has been loaded (or preloaded).

Param Type DefaultValue Description
sResourceName string

Name of the resource to check, in unified resource name format

jQuery.sap.isSpecialKey

Detect whether the pressed key is: SHIFT, CONTROL, ALT, BREAK, CAPS_LOCK, PAGE_UP, PAGE_DOWN, END, HOME, ARROW_LEFT, ARROW_UP, ARROW_RIGHT, ARROW_DOWN, PRINT, INSERT, DELETE, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, BACKSPACE, TAB, ENTER, ESCAPE

since: 1.58 use {@link module:sap/ui/events/isSpecialKey} instead
Param Type DefaultValue Description
oEvent jQuery.Event

The event object of the keydown, keyup or keypress events.

jQuery.sap.newObject

Returns a new object which has the given oPrototype as its prototype.

If several objects with the same prototype are to be created, jQuery.sap.factory should be used instead.

since: 1.45.0 use <code>Object.create(oPrototype)</code> instead.
Param Type DefaultValue Description
oPrototype object

Prototype to use for the new object

jQuery.sap.now

Returns a high resolution timestamp in microseconds if supported by the environment, otherwise in milliseconds. The timestamp is based on 01/01/1970 00:00:00 (UNIX epoch) as float with microsecond precision or with millisecond precision, if high resolution timestamps are not available. The fractional part of the timestamp represents fractions of a millisecond. Converting to a Date is possible by using require(["sap/base/util/now"], function(now){new Date(now());}

since: 1.58 use {@link module:sap/base/util/now} instead
Param Type DefaultValue Description

jQuery.sap.ownerWindow

Returns the window reference for a DomRef.

since: 1.58 use {@link module:sap/ui/dom/getOwnerWindow} instead
Param Type DefaultValue Description
oDomRef Element

The DOM reference

jQuery.sap.padLeft

Pads a string on the left side until is has at least the given length.

The method always adds full copies of sPadChar to the given string. When sPadChar has a length > 1, the length of the returned string actually might be greater than iLength.

since: 1.58 use the native <code>String#padStart</code> instead
Param Type DefaultValue Description
sString string

String to be padded

sPadChar string

Char to use for the padding

iLength int

Target length of the string

jQuery.sap.padRight

Pads a string on the right side until is has at least the given length.

The method always adds full copies of sPadChar to the given string. When sPadChar has a length > 1, the length of the returned string actually might be greater than iLength.

since: 1.58 use the native <code>String#padEnd</code> instead
Param Type DefaultValue Description
sString string

String to be padded

sPadChar string

Char to use for the padding

iLength int

Target length of the string

jQuery.sap.parseXML

Parses the specified XML formatted string text using native parsing function of the browser and returns a valid XML document. If an error occurred during parsing a parse error object is returned as property (parseError) of the returned XML document object. The parse error object has the following error information parameters: errorCode, url, reason, srcText, line, linepos, filepos

since: 1.58 use {@link module:sap/ui/util/XMLHelper.parse} instead
Param Type DefaultValue Description
sXMLText string

the XML data as string

jQuery.sap.properties

Creates and returns a new instance of jQuery.sap.util.Properties.

If option 'url' is passed, immediately a load request for the given target is triggered. A property file that is loaded can contain comments with a leading ! or #. The loaded property list does not contain any comments.

Example for loading a property file:

 jQuery.sap.properties({url : "../myProperty.properties"});

Example for creating an empty properties instance:

 jQuery.sap.properties();

Examples for getting and setting properties:

	var oProperties = jQuery.sap.properties();
	oProperties.setProperty("KEY_1","Test Key");
	var sValue1 = oProperties.getProperty("KEY_1");
	var sValue2 = oProperties.getProperty("KEY_2","Default");

since: 1.58 use {@link module:sap/base/util/Properties.create} instead
Param Type DefaultValue Description
mParams object

Parameters used to initialize the property list

url string

The URL to the .properties file which should be loaded

async boolean false

Whether the .properties file should be loaded asynchronously or not

headers object

A map of additional header key/value pairs to send along with the request (see headers option of jQuery.ajax)

returnNullIfMissing object false

Whether null should be returned for a missing properties file; by default an empty collection is returned

jQuery.sap.registerModulePath

Registers a URL prefix for a module name prefix.

Before a module is loaded, the longest registered prefix of its module name is searched for and the associated URL prefix is used as a prefix for the request URL. The remainder of the module name is attached to the request URL by replacing dots ('.') with slashes ('/').

The registration and search operates on full name segments only. So when a prefix

'sap.com' -> 'http://www.sap.com/ui5/resources/'

is registered, then it will match the name

'sap.com.Button'

but not

'sap.commons.Button'

Note that the empty prefix ('') will always match and thus serves as a fallback for any search.

The prefix can either be given as string or as object which contains the url and a 'final' property. If 'final' is set to true, overwriting a module prefix is not possible anymore.

since: 1.58 set path mappings via {@link sap.ui.loader.config} instead.
Param Type DefaultValue Description
sModuleName string

module name to register a path for

vUrlPrefix string object

path prefix to register, either a string literal or an object (e.g. {url : 'url/to/res', 'final': true})

url string

path prefix to register

final boolean

flag to avoid overwriting the url path prefix for the given module name at a later point of time

jQuery.sap.registerModuleShims

Register information about third party modules that are not UI5 modules.

The information maps the name of the module (without extension '.js') to an info object. Instead of a complete info object, only the value of the deps property can be given as an array.

since: 1.58 use {@link sap.ui.loader.config} instead
Param Type DefaultValue Description
mShims object

Map of shim configuration objects keyed by module names (withou extension '.js')

jQuery.sap.registerPreloadedModules

Adds all resources from a preload bundle to the preload cache.

When a resource exists already in the cache, the new content is ignored.

Param Type DefaultValue Description
oData object

Preload bundle

url string

URL from which the bundle has been loaded

name string

Unique name of the bundle

version string '1.0'

Format version of the preload bundle

modules object

Map of resources keyed by their resource name; each resource must be a string or a function

jQuery.sap.registerResourcePath

Registers a URL prefix for a resource name prefix.

Before a resource is loaded, the longest registered prefix of its unified resource name is searched for and the associated URL prefix is used as a prefix for the request URL. The remainder of the resource name is attached to the request URL 1:1.

The registration and search operates on full name segments only. So when a prefix

'sap/com' -> 'http://www.sap.com/ui5/resources/'

is registered, then it will match the name

'sap/com/Button'

but not

'sap/commons/Button'

Note that the empty prefix ('') will always match and thus serves as a fallback for any search.

The url prefix can either be given as string or as object which contains the url and a final flag. If final is set to true, overwriting a resource name prefix is not possible anymore.

since: 1.58 set path mappings via {@link sap.ui.loader.config} instead.
Param Type DefaultValue Description
sResourceNamePrefix string

in unified resource name syntax

vUrlPrefix string object

prefix to use instead of the sResourceNamePrefix, either a string literal or an object (e.g. {url : 'url/to/res', 'final': true})

url string

path prefix to register

final boolean

flag to avoid overwriting the url path prefix for the given module name at a later point of time

jQuery.sap.removeUrlWhitelist

Removes an allowlist entry for URL validation.

since: 1.58 use {@link module:sap/base/security/URLListValidator.clear} and {@link module:sap/base/security/URLListValidator.add} instead. SAP strives to replace insensitive terms with inclusive language, but APIs cannot be renamed or immediately removed for compatibility reasons.
Param Type DefaultValue Description
iIndex int

index of entry

jQuery.sap.require

Ensures that the given module is loaded and executed before execution of the current script continues.

By issuing a call to this method, the caller declares a dependency to the listed modules.

Any required and not yet loaded script will be loaded and execute synchronously. Already loaded modules will be skipped.

since: 1.52 UI5 modules and their dependencies should be defined using {@link sap.ui.define}. When additional modules have to be loaded dynamically at a later point in time, the asynchronous API {@link sap.ui.require} should be used. For more details, see {@link topic:91f23a736f4d1014b6dd926db0e91070 Modules and Dependencies} in the documentation.
Param Type DefaultValue Description
vModuleName string object

one or more names of modules to be loaded or in case of an object {modName: "...", type: "..."} where modName is the name of the module and the type could be a specific dot separated extension e.g. {modName: "sap.ui.core.Dev", type: "view"} loads sap/ui/core/Dev.view.js and registers as sap.ui.core.Dev.view

jQuery.sap.resources

Creates and returns a new instance of jQuery.sap.util.ResourceBundle using the given URL and locale to determine what to load.

since: 1.58 Use {@link module:sap/base/i18n/ResourceBundle} instead.
Param Type DefaultValue Description
mParams object

Parameters used to initialize the resource bundle

url string ''

URL pointing to the base .properties file of a bundle (.properties file without any locale information, e.g. "mybundle.properties")

locale string

Optional language (aka 'locale') to load the texts for. Can either be a BCP47 language tag or a JDK compatible locale string (e.g. "en-GB", "en_GB" or "fr"); Defaults to the current session locale if sap.ui.getCore is available, otherwise to 'en'

includeInfo boolean false

Whether to include origin information into the returned property values

async boolean false

Whether the first bundle should be loaded asynchronously Note: Fallback bundles loaded by #getText are always loaded synchronously.

jQuery.sap.resources.isBundle

Checks if the given object is an instance of jQuery.sap.util.ResourceBundle.

since: 1.58 Use the instanceof operator together with the class {@link module:sap/base/i18n/ResourceBundle} instead.
Param Type DefaultValue Description
oBundle jQuery.sap.util.ResourceBundle

object to check

jQuery.sap.scrollbarSize

Returns the size (width of the vertical / height of the horizontal) native browser scrollbars.

This function must only be used when the DOM is ready.

since: 1.58 use {@link module:sap/ui/dom/getScrollbarSize} instead
Param Type DefaultValue Description
sClasses string

the CSS class that should be added to the test element.

bForce boolean false

force recalculation of size (e.g. when CSS was changed). When no classes are passed all calculated sizes are reset.

jQuery.sap.serializeXML

Serializes the specified XML document into a string representation.

since: 1.58 use {@link module:sap/ui/util/XMLHelper.serialize} instead
Param Type DefaultValue Description
oXMLDocument string

the XML document object to be serialized as string

jQuery.sap.setIcons

Sets the bookmark icon for desktop browsers and the icon to be displayed on the home screen of iOS devices after the user does "add to home screen".

Only call this method once and call it early when the page is loading: browsers behave differently when the favicon is modified while the page is alive. Some update the displayed icon inside the browser but use an old icon for bookmarks. When a favicon is given, any other existing favicon in the document will be removed. When at least one home icon is given, all existing home icons will be removed and new home icon tags for all four resolutions will be created.

The home icons must be in PNG format and given in different sizes for iPad/iPhone with and without retina display. The favicon is used in the browser and for desktop shortcuts and should optimally be in ICO format: ICO files can contain different image sizes for different usage locations. E.g. a 16x16px version is used inside browsers.

All icons are given in an an object holding icon URLs and other settings. The properties of this object are:

One example is:

{
   'phone':'phone-icon_60x60.png',
   'phone@2':'phone-retina_120x120.png',
   'tablet':'tablet-icon_76x76.png',
   'tablet@2':'tablet-retina_152x152.png',
   'precomposed':true,
   'favicon':'desktop.ico'
}
If one of the sizes is not given, the largest available alternative image will be used instead for this size. On Android these icons may or may not be used by the device. Apparently chances can be improved by using icons with glare effect, so the "precomposed" property can be set to "true". Some Android devices may also use the favicon for bookmarks instead of the home icons.

since: 1.58 use {@link module:sap/ui/util/Mobile.setIcons} instead
Param Type DefaultValue Description
oIcons object

jQuery.sap.setMobileWebAppCapable

Sets the "apple-mobile-web-app-capable" and "mobile-web-app-capable" meta information which defines whether the application is loaded in full screen mode (browser address bar and toolbar are hidden) after the user does "add to home screen" on mobile devices. Currently this meta tag is only supported by iOS Safari and mobile Chrome from version 31.

If the application opens new tabs because of attachments, url and so on, setting this to false will let the user be able to go from the new tab back to the application tab after the application is added to home screen.

Note: this function only has effect when the application runs on iOS Safari and mobile Chrome from version 31.

since: 1.58 use {@link module:sap/ui/util/Mobile.setWebAppCapable} instead
Param Type DefaultValue Description
bValue boolean

whether the Application will be loaded in full screen mode after added to home screen from iOS Safari or mobile Chrome from version 31.

jQuery.sap.setObject

Sets an object property to a given value, where the property is identified by a sequence of names (path).

When a oContext is given, the path starts in that object. Otherwise it starts in the window object that this plugin has been created for.

Note: Although this method internally uses object["key"] to address object properties, it does not support all possible characters in a name. Especially the dot ('.') is not supported in the individual name segments, as it is always interpreted as a name separator.

since: 1.58 use {@link module:sap/base/util/ObjectPath.set} instead
Param Type DefaultValue Description
sName string

a dot separated sequence of names that identify the property

vValue any

value to be set, can have any type

oContext object window

the context to execute the search in

jQuery.sap.sjax

Convenience wrapper around jQuery.ajax() that avoids the need for callback functions when synchronous calls are made. If the setting complexResult is true (default), then the return value is an object with the following properties

When complexResult is false, then in the case of success, only 'data' is returned, in case of an error the 'fallback' setting is returned (defaults to undefined).

Note that async=false is always enforced by this method.

since: 1.58 It is no longer recommended to use synchronous calls at all. There are alternatives like native <code>XMLHttpRequest</code> or <code>jQuery.ajax</code> but try to avoid the sync flag. There will be no replacement for <code>jQuery.sap.sjax</code>.
Param Type DefaultValue Description
oOrigSettings string

the ajax() settings

jQuery.sap.startsWith

Checks whether a given sString starts with sStartString respecting the case of the strings.

since: 1.58 use the native <code>String#startsWith</code>
Param Type DefaultValue Description
sString string

String to be checked

sStartString string

The start string to be searched

jQuery.sap.startsWithIgnoreCase

Checks whether a given sString starts with sStartString ignoring the case of both strings.

References:

since: 1.58 use the native solution <code>sString.toLowerCase().startsWith(sEndString.toLowerCase())</code>
Param Type DefaultValue Description
sString string

String to be checked

sStartString string

The start string to be searched

jQuery.sap.syncGet

Convenience wrapper for jQuery.sap.sjax that enforeces the Http method GET and defaults the data type of the result to 'text'.

since: 1.58 see {@link jQuery.sap.sjax}
Param Type DefaultValue Description
sUrl string

the URL

data string object

request parameters in the format accepted by jQuery.ajax()

sDataType string 'text'

the type of data expected from the server, default is "text"

jQuery.sap.syncGetJSON

Convenience wrapper for jQuery.sap.sjax that enforces the Http method GET and the data type 'json'. If a fallback value is given, the function simply returns the response as an object or - if some error occurred - the fallback value. This is useful for applications that don't require detailed error diagnostics.

If applications need to know about occurring errors, they can either call sjax() directly or they can omit the fallback value (providing only two parameters to syncGetJSON()). They then receive the same complex result object as for the sjax() call.

Note that providing "undefined" or "null" as a fallback is different from omitting the fallback (complex result).

since: 1.58 see {@link jQuery.sap.sjax}
Param Type DefaultValue Description
sUrl string

the URL

data string object

request parameters in the format accepted by jQuery.ajax()

fallback object

if set, only data is returned (and this fallback instead in case of errors); if unset, a result structure is returned

jQuery.sap.syncGetText

Convenience wrapper for jQuery.sap.sjax that enforces the Http method GET and the data type 'text'. If a fallback value is given, the function simply returns the response as a text or - if some error occurred - the fallback value. This is useful for applications that don't require detailed error diagnostics.

If applications need to know about occurring errors, they can either call sjax() directly or they can omit the fallback value (providing only two parameters to syncGetText()). They then receive the same complex result object as for the sjax() call.

since: 1.58 see {@link jQuery.sap.sjax}
Param Type DefaultValue Description
sUrl string

the URL

data string object

request parameters in the format accepted by jQuery.ajax()

fallback string

if set, only data is returned (and this fallback instead in case of errors); if unset, a result structure is returned

jQuery.sap.syncPost

Convenience wrapper for jQuery.sap.sjax that enforces the Http method POST and defaults the data type of the result to 'text'.

since: 1.58 see {@link jQuery.sap.sjax}
Param Type DefaultValue Description
sUrl string

the URL

data string object

request parameters in the format accepted by jQuery.ajax()

sDataType string 'text'

the type of data expected from the server, default is "text"

jQuery.sap.syncStyleClass

Search ancestors of the given source DOM element for the specified CSS class name. If the class name is found, set it to the root DOM element of the target control. If the class name is not found, it is also removed from the target DOM element.

since: 1.58 use {@link module:sap/ui/core/syncStyleClass} instead
Param Type DefaultValue Description
sStyleClass string

CSS class name

vSource jQuery sap.ui.core.Control string

jQuery object, control or an id of the source element.

vDestination jQuery sap.ui.core.Control

target jQuery object or a control.

jQuery.sap.uid

Creates and returns a pseudo-unique id.

No means for detection of overlap with already present or future UIDs.

since: 1.58 use {@link module:sap/base/util/uid} instead
Param Type DefaultValue Description

jQuery.sap.unbindAnyEvent

Unbinds all events for listening with the given callback function.

since: 1.58 use {@link module:sap/ui/events/ControlEvents.unbindAnyEvent} instead
Param Type DefaultValue Description
fnCallback function

Callback function

jQuery.sap.unique

Sorts the given array in-place and removes any duplicates (identified by "===").

Use jQuery.uniqueSort() for arrays of DOMElements.

since: 1.58 use {@link module:sap/base/util/array/uniqueSort} instead
Param Type DefaultValue Description
a Array

An Array of any type

jQuery.sap.validateUrl

Validates a URL. Check if it's not a script or other security issue.

By default the URL validation does only allow the http, https and ftp protocol. If other protocols are required, an allowlist of all allowed protocols needs to be defined.

Split URL into components and check for allowed characters according to RFC 3986:

authority     = [ userinfo "@" ] host [ ":" port ]
userinfo      = *( unreserved / pct-encoded / sub-delims / ":" )
host          = IP-literal / IPv4address / reg-name

IP-literal    = "[" ( IPv6address / IPvFuture  ) "]"
IPvFuture     = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )
IPv6address   =                            6( h16 ":" ) ls32
              /                       "::" 5( h16 ":" ) ls32
              / [               h16 ] "::" 4( h16 ":" ) ls32
              / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32
              / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32
              / [ *3( h16 ":" ) h16 ] "::"    h16 ":"   ls32
              / [ *4( h16 ":" ) h16 ] "::"              ls32
              / [ *5( h16 ":" ) h16 ] "::"              h16
              / [ *6( h16 ":" ) h16 ] "::"
ls32          = ( h16 ":" h16 ) / IPv4address
              ; least-significant 32 bits of address
h16           = 1*4HEXDIG
              ; 16 bits of address represented in hexadecimal

IPv4address   = dec-octet "." dec-octet "." dec-octet "." dec-octet
dec-octet     = DIGIT                 ; 0-9
              / %x31-39 DIGIT         ; 10-99
              / "1" 2DIGIT            ; 100-199
              / "2" %x30-34 DIGIT     ; 200-249
              / "25" %x30-35          ; 250-255

reg-name      = *( unreserved / pct-encoded / sub-delims )

pct-encoded   = "%" HEXDIG HEXDIG
reserved      = gen-delims / sub-delims
gen-delims    = ":" / "/" / "?" / "#" / "[" / "]" / "@"
sub-delims    = "!" / "$" / "&" / "'" / "(" / ")"
              / "*" / "+" / "," / ";" / "="
unreserved    = ALPHA / DIGIT / "-" / "." / "_" / "~"
pchar         = unreserved / pct-encoded / sub-delims / ":" / "@"

path          = path-abempty    ; begins with "/" or is empty
              / path-absolute   ; begins with "/" but not "//"
              / path-noscheme   ; begins with a non-colon segment
              / path-rootless   ; begins with a segment
              / path-empty      ; zero characters

path-abempty  = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty    = 0
segment       = *pchar
segment-nz    = 1*pchar
segment-nz-nc = 1*( unreserved / pct-encoded / sub-delims / "@" )
              ; non-zero-length segment without any colon ":"

query         = *( pchar / "/" / "?" )

fragment      = *( pchar / "/" / "?" )

For the hostname component, we are checking for valid DNS hostnames according to RFC 952 / RFC 1123:

hname         = name *("." name)
name          = let-or-digit ( *( let-or-digit-or-hyphen ) let-or-digit )

When the URI uses the protocol 'mailto:', the address part is additionally checked against the most commonly used parts of RFC 6068:

mailtoURI     = "mailto:" [ to ] [ hfields ]
to            = addr-spec *("," addr-spec )
hfields       = "?" hfield *( "&" hfield )
hfield        = hfname "=" hfvalue
hfname        = *qchar
hfvalue       = *qchar
addr-spec     = local-part "@" domain
local-part    = dot-atom-text              // not accepted: quoted-string
domain        = dot-atom-text              // not accepted: "[" *dtext-no-obs "]"
dtext-no-obs  = %d33-90 / ; Printable US-ASCII
                %d94-126  ; characters not including
                          ; "[", "]", or "\"
qchar         = unreserved / pct-encoded / some-delims
some-delims   = "!" / "$" / "'" / "(" / ")" / "*"
              / "+" / "," / ";" / ":" / "@"

Note:
A number of characters that can appear in <addr-spec> MUST be
percent-encoded.  These are the characters that cannot appear in
a URI according to [STD66] as well as "%" (because it is used for
percent-encoding) and all the characters in gen-delims except "@"
and ":" (i.e., "/", "?", "#", "[", and "]").  Of the characters
in sub-delims, at least the following also have to be percent-
encoded: "&", ";", and "=".  Care has to be taken both when
encoding as well as when decoding to make sure these operations
are applied only once.

When an allowlist has been configured using add, any URL that passes the syntactic checks above, additionally will be tested against the content of the allowlist.

since: 1.58 use {@link module:sap/base/security/URLListValidator.validate} instead.
Param Type DefaultValue Description
sUrl string