Oracle Application Express includes the jQuery 1.11.2 and 2.1.3, jQuery UI 1.10.4, and jQuery Mobile - 1.4.4 JavaScript libraries. This section discusses the features available in jQuery UI and best practices when referencing jQuery libraries in your JavaScript code.
The JavaScript libraries for jQuery and jQueryUI used by Oracle Application Express have been updated as follows:
jQuery has been updated from version 1.7.1 to version 2.1.3.
jQueryUI has been updated from version 1.8.14 to version 1.10.4.
Tip:
For a list of bug fixes and enhancement, see the jQuery and jQueryUI release notes at:This upgrade may impact existing applications in the following ways.
Possible Impacts of Updated jQuery Version
If you have used jQuery in your own JavaScript code in applications, then you may be impacted by changed behavior caused by the updated jQuery version. The most significant impact concerns the use of the jQuery attr method. This method returns slightly different values in some circumstances. Please review the jQuery change log for further details of this and other changes.
If you are concerned this may impact your applications, Oracle suggests the following:
Fallback to the previous version of jQuery for your code. You can include jQuery 1.7.1 and jQuery UI 1.8.14 by adding the following to your Page Template > Header, within the <head>…</head> tags, importantly ensuring this is done directly after the #HEAD# substitution string and before you include any of your libraries:
...
#HEAD#
<script src="#IMAGE_PREFIX#libraries/jquery/1.7.1/jquery-1.7.1.min.js" type="text/javascript"></script>
...
Oracle Application Express still includes jQuery 2.1.3 as part of the #APEX_JAVASCRIPT# substitution, but including 1.7.1 afterwards means that the variables $ and jQuery will now point to jQuery version 1.7.1, which you can continue to use in your applications.
Tip:
jQuery 1.7.1 is still included with Oracle Application Express distribution, so you do not need to add this to your web server.Review and retest your jQuery code to see if you are impacted by the changes. This is more work initially, but has two advantages. First, you only need to load one version of the jQuery library into your application. Second, you also benefit from the enhancements included with the most recent version.
Possible Impacts of Updated jQuery UI
You may experience compatibility issues if you have included components of jQuery UI that are not included by default with Oracle Application Express. To reduce page size and processing, only the components of jQuery UI used by Oracle Application Express base functionality are included with Oracle Application Express. All of these default components now use jQuery UI 1.10.4.. You could experience compatibility issues if you are referencing an older version of jQuery UI.
All of these default components are now using jQuery UI 1.10.4., whereas any components you may have previously included may be referencing an older version. This means there may be compatibility issues between the versions of jQuery UI components you have included and the updated jQuery and jQuery UI versions we include by default.
If you are concerned this may impact your applications, Oracle suggestions two possible options:
Fallback to the previous versions of jQuery and jQuery UI in your code. You can include jQuery 1.7.1 and jQuery UI 1.8.14 by adding the following to your Page Template > Header, within the <head>…</head> tags, importantly ensuring this is done straight after the #HEAD# substitution string and before you include any of your libraries:
...
#HEAD#
<script src="#IMAGE_PREFIX#libraries/jquery/1.7.1/jquery-1.7.1.min.js" type="text/javascript"></script>
<script src="#IMAGE_PREFIX#libraries/jquery-ui/1.8.14/ui/minified/jquery-ui-1.8.14.custom.min.js" type="text/javascript"></script>
...
Although Oracle Application Express still includes jQuery 2.1.3 and jQuery UI 1.10.4 as part of the #APEX_JAVASCRIPT# substitution, Oracle just includes the older versions for compatibility with your other jQuery UI components you may be referencing.
Tip:
jQuery 2.1.3 and jQuery UI 1.10.4. are still included with Oracle Application Express, so you do not need to add this to your web server.Review your jQuery UI code, update any jQuery UI components to reference version 1.10.4., and retest. This approach is more work initially, but has the advantage that you only need to load one version of the jQuery library and one version of the jQuery UI library into your application. You also benefit from the enhancements included with the most recent versions.
To make the reference agnostic to future version changes, Oracle suggests you search the files containing your JavaScript code and also in Application Search in the Application Builder for the following libraries/jquery-ui/ and replace it with #JQUERYUI_DIRECTORY#.
Oracle Application Express only loads the components of jQuery UI that are required for base Oracle Application Express functionality. Oracle Application Express does not include the entire jQuery UI library since doing so would significantly add to download and processing time for each page load. Oracle Application Express includes these components by default:
jQuery UI Core - Required for all interactions and widgets.
Query UI Widget - The widget factory that is the base for all widgets.
jQuery UI Mouse - The mouse widget is a base class for all interactions and widgets with heavy mouse interaction.
jQuery UI Position - A utility plug-in for positioning elements relative to other elements.
jQuery UI Draggable - Makes any element on the page draggable.
jQuery UI Resizable - Makes any element on the page resizable.
jQuery UI Dialog - Opens existing mark up in a draggable and resizable dialog.
jQuery UI Datepicker - A datepicker than can be toggled from a input or displayed inline.
jQuery UI Effects - Extends the internal jQuery effects, includes morphing, easing, and is required by all other effects.
jQuery UI Effects Drop - A drop out effect by moving the element in one direction and hiding it at the same time.
jQuery UI Tooltip - Shows additional information for any element on hover or focus
For more information about jQuery UI and these specific components, see the jQuery UI site:
http://jqueryui.com/
Oracle Application Express does not include the entire jQuery UI library. You can easily activate other components of jQuery UI by just including the relevant files. For example, to include the Tabs jQuery UI Widget in your application, you would include the following in your User Interface definition.
Set Cascading Style Sheets to:
#JQUERYUI_DIRECTORY#themes/base/#MIN_DIRECTORY#jquery.ui.tabs#MIN#.css
Set JavaScript to:
#JQUERYUI_DIRECTORY#ui/#MIN_DIRECTORY#jquery.ui.tabs#MIN#.js
Tip:
You do not need to include the Dependencies for Tabs of UI Core and UI Widget since these are included by default with Oracle Application Express, as shown in the previous list of default components.Determining when to use the $, jQuery, and apex.jQuery references to the jQuery library in your own JavaScript code depends on where you use it.
Newer versions of Oracle Application Express may include updated versions of the jQuery libraries. When new versions of jQuery are released, they sometimes introduce changes that could break existing functionality. These issues are documented in the Change Log for a particular version's Release Notes. To minimize your risk when upgrading to a newer version of Oracle Application Express, Oracle recommends the best practices described in the following sections.
If you want to use jQuery in your own JavaScript code in an application, Oracle recommends you use jQuery or the shortcut $ for the following reasons:
If you upgrade Oracle Application Express, there is the potential that the newer jQuery version may break your existing code.
To avoid intensive testing and rewriting of your application to the new jQuery version, you can include the old jQuery version that was shipped with Oracle Application Express release 4.1 in your Page Template, Header within the <head>…</head> tags after the #HEAD# substitution string. Consider the following example:
... #HEAD# ... <script src="#IMAGE_PREFIX#libraries/jquery/1.6.2/jquery-1.6.2.min.js" type="text/javascript"></script> ...
In this example, the references to the jQuery library '$' and 'jQuery' point to jQuery version 1.6.2 (the version included in Oracle Application Express release 4.1) and not the newer version 2.1.3 included with Oracle Application Express release 5.0.
Tip:
Oracle Application Express release 5.0 includes jQuery version 2.1.3 so you do not need to add this to your web server.Note that no additional code changes necessary. This approach minimizes the risk of breaking custom jQuery code when upgrading to a newer version of Application Express.
If jQuery plug-in you use requires a different version of jQuery and you want to use that version in other code in your application.
In this case, you can include version of jQuery library (the newer or older) into your page template as described in the previous step (that is, after the #HEAD# substitution string). The variables $ and jQuery point to the appropriate jQuery version.
If a jQuery plug-in you use requires a different version of jQuery and you do not want to use that version in other code in an application.
For example, suppose a jQuery plug-in requires jQuery 1.6.2, but you want to use jQuery 1.7.1 which included with Oracle Application Express. Include jQuery version 1.6.2 into your Page Template, Header, within the <head>…</head> tags, before the #HEAD# substitution string.
In this case, you also need a JavaScript snippet to define a new variable to store the plug-in specific jQuery version (for example, jQuery_1_6_2) and then assign it. Consider the following example:
...
<script src="#IMAGE_PREFIX#libraries/jquery/1.6.2/jquery-1.6.2.min.js" type="text/javascript"></script>
<script type="text/javascript">
var jQuery_1_6_2 = jQuery;
</script>
...
#HEAD#
...
You must also modify the initialization code of the jQuery plug-in to use the jQuery_1_6_2 variable, for example:
(function($) {
... plugin code ...
})(jQuery_1_6_2);
For more information about jQuery plug-in initialization, see "About Using JavaScript Code in a Plug-In."
Tip:
In all of these scenarios, use the variables$ and jQuery in your application to specify the version you require. Note that the variable apex.jQuery still points to the version that ships with Oracle Application Express to support built-in functionality, which depends on that jQuery version.If you want to use jQuery in an Oracle Application Express plug-in, Oracle recommends using the apex.jQuery reference to the jQuery library. This reference should even include a modification of the initialization code of the included jQuery plug-in to use the apex.jQuery reference.
If you look at the JavaScript code of a jQuery plug-in, notice that most have the following code structure:
(function($) {
... plugin code ...
})(jQuery);
This structure declares an anonymous JavaScript function with a parameter $, which is immediately called and passed the parameter value of the current jQuery variable. The use of $ as the jQuery shortcut is implemented in a safe manner without having to rely on the fact that $ is still used to reference the main jQuery library.
Oracle recommends copying the jQuery plug-in file and prefixing it with apex (for example, apex.jquery.maskedinput-1.2.2.js). This makes it obvious to Oracle Application Express that the file has been modified. Then, change the reference from jQuery to apex.jQuery in the initialization code as shown in the following example.
(function($) {
... plugin code ...
})(apex.jQuery);
Other Reasons to Use this Approach
As a plug-in developer, you want to minimize your testing effort and create an environment where you have full control. Assume you are not following the recommendations described in the previous section. What happens if your plug-in is using a different version of jQuery?
This may result in strange plug-in behavior. Furthermore, it may be difficult to reproduce that behavior because you will not know if your plug-in is actually referencing a different version of jQuery. Using the apex.jQuery namespace reduces your risk and also the risk to your users. This approach enables you to test your plug-ins with the Oracle Application Express versions you want to support.