With OpenUI5 1.82, the third-party library jQuery is upgraded from jQuery 2.2.3 to jQuery 3.5.1. Several measures have been implemented to make this new framework variant of jQuery as compatible to the previously contained version as feasible. In particular, we introduce a compatibility layer to ensure that most of your existing application or control code may not need adjustment. This could, however, introduce incompatibilites to the new jQuery version. Please read the following information carefully to understand any current and possible future impact.
With the major version upgrade from jQuery 2.x to jQuery 3.x, a number of incompatible changes have been introduced (see the breaking changes in the jQuery 3.0 Core Upgrade Guide).
We evaluated each of those changes and classified them to see what needed to be fixed on the layers of framework, control and application. To minimize the migration effort required by application and control developers, we have introduced an additional compatibility layer on top of jQuery (delivered as sap/ui/thirdparty/jquery-compat.js).
This compatibility layer has the following properties:
excludeJQueryCompat configuration via:
URL parameter (case-sensitive): sap-ui-excludeJQueryCompat=true
data-sap-ui-excludejquerycompat="true"window["sap-ui-config"]["excludejQueryCompat"]=trueThe following table contains some important differences between jQuery 2.2.3 and jQuery 3.5.1. The rightmost column indicates whether such an incompatible change of jQuery 3.x was “rolled back” to the original jQuery 2.x behavior by our compatibility layer.
Note:
Though we aim to make sure that the jQuery APIs used by controls and applications stay compatible even after breaking changes by jQuery, we cannot guarantee a 100% compatibility rate.
| API \(and what has changed\) | jQuery 2.x | jQuery 3.x | jQuery 3.x + Compat. Layer = jQuery 2.x |
|---|---|---|---|
| **`jQuery.fn.size()`** | function exists | removed |  |
| **`jQuery.fn.offset()`** must have at least one valid DOM element, otherwise it throws an error | doesn't throw error | throws an error |  |
| **`jQuery.fn.context`** when a jQuery object is created from a node \(like in our `oControl.$()` call\), it no longer has the `context` property set | `context` property exists | `context` property has been removed |  |
| **`jQuery.fn.andSelf()`** function was removed; jQuery proposes to use`jQuery.fn.addBack()` instead. | exists | removed |  |
| **`jQuery.fn.[width|height|outerWidth|outerHeight]`** return value type changed | returns integer | returns float |  |
| **`jQuery.fn.[width|height|outerWidth|outerHeight]`** in case of an empty jQuery element, the return value was changed from `null` to `undefined` | returns `null` \(can be automatically cast to 0 when compared to a number\) | returns `undefined` \(cast to `NaN`\) |  |
| **`jQuery.event.props`** and **`jQuery.event.fixHooks`** | exist | removed |  |
| **`jQuery.Deferred.then(function A() {})`** | Function `A` is called immediately within the same call stack | Function `A` is called after the current call stack is finished |  |
| **`jQuery.Deferred.[resolve|reject|notify]`** `this` context that is set by | `this` context is set to the promise of the `Deferred` object | `this` context is undefined |  |
Some incompatible changes that are introduced with jQuery 3.5.1 aren’t restored to the old behavior of jQuery 2.2.3 by our compatibility layer. This is because we consider them reasonable improvements, for which we don’t see any negative impact from our evaluation with existing applications.
| API | jQuery 2.x | jQuery 3.x | |||||
|---|---|---|---|---|---|---|---|
| **`jQuery.fn.[width|height]`** doesn't include the scrollbar width if there is one | includes the width or height of the scrollbar, if there is one | doesn't include the scrollbar width if there is one Use `jQuery.fn.[outerWidth|outerHeight]` instead. Also works in jQuery 2.x | |||||
| **`jQuery.animation`** | uses `setInterval()` | uses `requestAnimationFrame()` | |||||
| **`jQuery.ajax`** for multiple response header values that have the same header name | only returns the first header value | merges multiple header values into a string, separated by ", " | |||||
| **`jQuery(function A() {})`** callback is delayed even if the `DOM Ready` event already occurred | Function `A` is called immediately within the current call stack | Function `A` is called after the current call stack has finished | |||||
| **`jQuery.swap()`** | exists | *removed, because it's an undocumented internal method!* | |||||
| **`jQuery.data`** in case the key contains a dash "-" | see [https://jquery.com/upgrade-guide/3.0/\#data](https://jquery.com/upgrade-guide/3.0/#data) | see [https://jquery.com/upgrade-guide/3.0/\#data](https://jquery.com/upgrade-guide/3.0/#data) | |||||
| **`jQuery.fn.selector`** unreliable pseudo-selector has been removed | concatenates the selector property after further tree traversal calls, for example `jQuery.fn.filter` \(see [https://api.jquery.com/category/traversing/tree-traversal/](https://api.jquery.com/category/traversing/tree-traversal/)\) | according to jQuery documentation, it was never reliable and thus removed with 3.0: [https://api.jquery.com/selector/](https://api.jquery.com/selector/) | |||||
| **`jQuery.easing.*`** see [https://jquery.com/upgrade-guide/3.0/\#deprecated-additional-easing-function-parameters](https://jquery.com/upgrade-guide/3.0/#deprecated-additional-easing-function-parameters) | function accepts multiple arguments | function accepts only one argument | |||||
| **`jQuery.fn.[append|prepend]`** [jQuery Issue \#3976](https://github.com/jquery/jquery/issues/3976) see also the table below | automatically add a ` |
| adding elements to a table does **not** create an additional ` | ` element </td> </tr>|||||||
| **`jQuery.fn.[after|append|before|html|prepend|replaceWith]`** **`jQuery.parseHTML`** [jQuery Pull Request \#4642](https://github.com/jquery/jquery/pull/4642) see also the table below | some jQuery APIs in certain contexts call the `htmlPrefilter()` method, which replaces self-closing HTML tags with properly closed HTML elements \(e.g. <div/\> is replaced by <div\></div\>\) | the `htmlPrefilter()` method returns the passed string unmodified |
| Changed Behavior | in OpenUI5 < 1.82 | in OpenUI5 \>= 1.82 | Recommendation | ||||
|---|---|---|---|---|---|---|---|
| **Automatic creation of ` | OpenUI5 Controls using a string-based rendering approach in their renderer modules implicitly use jQuery APIs to create the DOM elements. Whenever you flush a ` | ||||||
| flushing a ` | ||||||
| If your application or control code depends on a ` | ` element being present in the DOM, you should add it manually to your rendering code and your CSS styling rules. Adding the `` element in this way is backward-compatible to older OpenUI5 and jQuery versions. </td> </tr>|||
| **Self-Closing HTML Tags** see also the table above | OpenUI5 uses a UI5-specific jQuery 2.2.3 variant. Formerly, its internal `htmlPrefilter()` method used to replace self-closing HTML tags with properly closed HTML elements \(e.g. <div/\> was replaced by <div\></div\>\). Since jQuery 3.5.0, this replacement is no longer done. Instead, the browser will automatically close the self-closing HTML element based on the DOM hierarchy, which could very likely occur at the wrong place. The custom jQuery 2.2.3 variant used in OpenUI5 also implements this change, because self-closing HTML tags for non-void HTML elements are not valid in HTML5. The updated jQuery 2.2.3 variant is contained in the following OpenUI5 versions: - 1.38.47 or higher - 1.52.43 or higher - 1.60.28 or higher - 1.71.20 or higher - 1.78.4 or higher - 1.80.1 or higher - 1.81.0 or higher | jQuery no longer closes self-closing tags for non-void HTML elements in the `htmlPrefilter()` method. Instead, the browser will automatically close the self-closing HTML element based on the DOM hierarchy, which could very likely occur at the wrong place. | You should properly close non-void HTML elements. For detailed instructions for identifying affected code and fixing it, see [these instructions](https://github.com/SAP/openui5/blob/master/docs/self_closing_tags_fix_instructions.md). Properly closing non-void HTML elements in this way is backward-compatible to older OpenUI5 and jQuery versions. | `, ` | `, ` |
|---|