Namespace jQuery.sapModule: jquery.sap.global

Adds a whitelist entry for URL validation.

Note: It is strongly recommended to set a path only in combination with an origin (never set a path alone). There's almost no case where checking only the path of a URL would allow to ensure its validity.

Calculate delta of old list and new list This implements the algorithm described in "A Technique for Isolating Differences Between Files" (Commun. ACM, April 1978, Volume 21, Number 4, Pages 264-268)

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.

Binds all events for listening with the given callback function.

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

Transforms a hyphen separated string to an camel case string.

Converts a character of the string to upper case.
If no pos is defined as second parameter or pos is negative or greater than sString the first character will be converted into upper case. the first char position is 0.

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

Stops the delayed call.

The function given when calling delayedCall is not called anymore.

Stops the interval call.

The function given when calling intervalCall is not called anymore.

Clears the whitelist for URL validation

Returns whether oDomRefChild is oDomRefContainer or is contained in oDomRefContainer.

This is a browser-independent version of the .contains method of Internet Explorer. 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.

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.

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

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!

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

Disable touch to mouse handling

Shortcut for document.getElementById(), including a bug fix for older IE versions.

Encode the string for inclusion into CSS string literals or identifiers

Encode the string for inclusion into HTML content/attribute

Encode the string for inclusion into a JS string literal

Encode the string for inclusion into an URL parameter

Encode a map of parameters into a combined URL parameter string

Encode the string for inclusion into XML content/attribute

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

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

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

This function escapes the reserved letters in Regular Expression

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

Calls focus() on the given DOM element, but catches and ignores any errors that occur when doing so. (i.e. IE8 throws an error when the DOM element is invisible or disabled)

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} y 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.

Returns the names of all declared modules.

Constructs an 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.

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

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 an 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 recommened 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).

Experimental API:Since 1.27.0

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

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];
	}

Gets the whitelist for URL validation.

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.

Transforms a camel case string into a hyphen separated string.

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

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.

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.

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

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.

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.

Returns the window reference for a DomRef

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

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

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

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");

Registers an 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.

Registers an 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.

Removes a whitelist entry for URL validation.

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.

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

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.

Serializes the specified XML document into a string representation.

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: PNG does not seem to be supported by Internet Explorer and 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.

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.

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.

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.

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

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

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

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

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.

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

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.

Creates and returns a pseudo-unique id.

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

Unbinds all events for listening with the given callback function.

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

Use jQuery.unique() for arrays of DOMElements.

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

Note: It is strongly recommended to validate only absolute URLs. There's almost no case where checking only the path of a URL would allow to ensure its validity. For compatibility reasons, this API cannot automatically resolve URLs relative to document.baseURI, but callers should do so. In that case, and when the allow list is not empty, an entry for the origin of document.baseURI must be added to the allow list.

Details

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:

 ::= *["."]
  ::= [*[]]

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  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 a whitelist has been configured using addUrlWhitelist, any URL that passes the syntactic checks above, additionally will be tested against the content of the whitelist.