In Oracle Application Express includes the jQuery 1.7.1, jQuery UI 1.8.22, and jQuery Mobile - 1.1.1 RC1 JavaScript libraries. This section discusses the features available in jQuery UI and best practices when referencing jQuery libraries in your JavaScript code.
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.
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 Page Template, Header within the <head>...</head> tags as shown in the following example:
<link href="#IMAGE_PREFIX#libraries/jquery-ui/1.8.22/themes/base/minified/jquery.ui.tabs.min.css" rel="stylesheet" type="text/css" /> <script src="#IMAGE_PREFIX#libraries/jquery-ui/1.8.22/ui/minified/jquery.ui.tabs.min.js" type="text/javascript"></script>
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 sections that follow.
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 1.7.1 included with Oracle Application Express release 4.2
Tip:
Oracle Application Express release 4.2 includes jQuery version 1.6.2 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 "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);
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.