The apex namespace is the top level Oracle Application Express namespace and contains a number of sub namespaces, and a few common functions and properties.
This is also where the general Application Express specific events are documented.
Namespaces
Properties
(static) gPageContext$ :jQuery
This namespace property stores the current page context. The current page context is different depending on whether the page is a Desktop, or jQuery Mobile page. For Desktop, this is set to the HTML document (same as apex.jQuery(document)). For jQuery Mobile, where pages are actually represented as DIV elements in the Browser DOM and multiple page DIVs can be loaded in the Browser DOM at one time, this is set to the DIV element representing the current page. This is used to set the context for your jQuery selectors, to ensure that the selector is executing within the context of the correct page.
Type:
- jQuery
Example
This selects all elements with a CSS class of my_class, in the context of the current page.
apex.jQuery( ".my_class", apex.gPageContext$ );(static) jQuery :function
This namespace property holds the jQuery function that APEX uses. Ideally there is just one copy of jQuery on a page but it is possible to have multiple copies and even different versions of jQuery on a page. This is sometimes necessary when using third party plugins that only work with an older version of jQuery. Use this property in place of global variables $ or jQuery to ensure you are using the same jQuery library that Application Express is using.
Type:
- function
Example
The following function creates a local variable $ as a convenient way to reference jQuery while ensuring that it is using the same jQuery that APEX uses.
function myFunction() {
var $ = apex.jQuery;
// use $ to access jQuery functionality
}Events
apexafterrefresh
This event is triggered by a number of page or column items just after they are refreshed with new content or data from the server. It is equivalent to the Dynamic Action event After Refresh. Specifically any item that supports the Cascading LOV Parent Item(s) attribute should trigger this event. This event can also be triggered by the apex.server.plugin and apex.server.process APIs if the refreshObject option is provided. The event is triggered on the item element or the element given by the refreshObject. The event handler receives the data given in refreshObjectData if any.
Properties:
| Name | Type | Attributes | Description |
|---|---|---|---|
event |
Event | jQuery event object. |
|
data |
Object |
<optional> |
The refresObjectData if any. |
Example
This example disables the button with static id B1 while any refresh is in progress.
apex.jQuery( "body" ).on( "apexbeforerefresh", function() {
apex.jQuery( "#B1" ).prop( "disabled", true);
} ).on( "apexafterrefresh", function() {
apex.jQuery( "#B1" ).prop( "disabled", false);
} );apexbeforepagesubmit
This event is triggered when the page is submitted with apex.page.submit or apex.page.confirm. This includes buttons with action Submit Page and Dynamic Action Submit Page action. It is equivalent to the Dynamic Action event Before Page Submit. It is triggered before the page is validated. It is triggered on apex.gPageContext$, which is the document for Desktop UI pages and the page div for jQuery Mobile UI pages. This event can be canceled by a Dynamic Action Confirm or Cancel Event action so you cannot rely on the page actually being submitted. If you need code to run just before the page is actually submitted see the apexpagesubmit event.
The event handler should not do any long running or asynchronous processing. Specifically it should not make a synchronous or asynchronous Ajax request. The event handler receives a string argument that is the request value.
Properties:
| Name | Type | Description |
|---|---|---|
event |
Event | jQuery event object. |
request |
string | The request string. |
Example
This example performs an extra validation on page item P1_CHECK_ME. For this to work the Submit button Execute Validations attribute must be Yes and the application compatibility mode must be greater than or equal to 5.1 or the validate option to apex.submit or apex.confirm must be true.
apex.jQuery( apex.gPageContext$ ).on( "apexbeforepagesubmit", function() {
var item = apex.item("P1_CHECK_ME" ),
value = item.getValue();
if ( value !== "valid" ) { // replace with desired constraint check
item.node.setCustomValidity( "Text field needs to be valid" );
} else {
item.node.setCustomValidity( "" );
}
} );apexbeforerefresh
This event is triggered by a number of page or column items just before they are refreshed with new content or data from the server. It is equivalent to the Dynamic Action event Before Refresh. Specifically any item that supports the Cascading LOV Parent Item(s) attribute should trigger this event. This event can also be triggered by the apex.server.plugin and apex.server.process APIs if the refreshObject option is provided. The event is triggered on the item element or the element given by the refreshObject. The event handler receives the data given in refreshObjectData if any.
Properties:
| Name | Type | Attributes | Description |
|---|---|---|---|
event |
Event | jQuery event object. |
|
data |
Object |
<optional> |
The refresObjectData if any. |
Example
This example disables the button with static id B1 while any refresh is in progress.
apex.jQuery( "body" ).on( "apexbeforerefresh", function() {
apex.jQuery( "#B1" ).prop( "disabled", true);
} ).on( "apexafterrefresh", function() {
apex.jQuery( "#B1" ).prop( "disabled", false);
} );apexbeginrecordedit
This event is triggered when a model row/record is about to be edited (when a new row/record is selected or enter edit mode).
Properties:
| Name | Type | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
event |
Event | jQuery event object. |
||||||||||||
data |
object | Additional event data.
Properties
|
apexendrecordedit
This event is triggered when a model row/record is done being edited (when a new row/record is selected or exit edit mode).
Properties:
| Name | Type | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
event |
Event | jQuery event object. |
||||||||||||
data |
object | Additional event data.
Properties
|
apexpagesubmit
This event is triggered when the page is submitted with apex.page.submit or apex.page.confirm. This includes buttons with action Submit Page and Dynamic Action Submit Page action. It is triggered after the page is validated. It is triggered on apex.gPageContext$, which is the document for Desktop UI pages and the page div for jQuery Mobile UI pages. This event is the last chance to set or modify page items before the page is submitted.
The event handler should not do any long running or asynchronous processing. Specifically it should not make a synchronous or asynchronous Ajax request. The event handler receives a string argument that is the request value.
Properties:
| Name | Type | Description |
|---|---|---|
event |
Event | jQuery event object. |
request |
string | The request string. |
Example
<caption>This example makes the page item P1_VALUE upper case before the page is submitted.<caption>
apex.jQuery( apex.gPageContext$ ).on( "apexpagesubmit", function() {
var item = apex.item("P1_VALUE");
item.setValue( item.getValue().toUpperCase());
} );apexwindowresized
This event is triggered on the window a couple hundred milliseconds after the window stops resizing. Listen for this event to adjust or resize page content after the window is done resizing. In some cases this is a better alternative to the window resize event, which is triggered many times as the window is being resized, because it is triggered just once after the window stops resizing.
Properties:
| Name | Type | Description |
|---|---|---|
Event |
Event | jQuery event object |
Example
This example responds to the apexwindowresized event and updates page content based on the new height and width.
apex.jQuery( window ).on( "apexwindowresized", function( event ) {
var window$ = apex.jQuery( this ),
height = window$.height(),
width = window$.width();
// update page content based on new window height and width
});Functions
(static) confirm()
(static) item(pNd) → {item}
This API returns an Application Express item interface that is used to access item related methods and properties.
Plug-in developers can override much of the item behavior, by calling apex.item.create with their overrides.
Parameters:
| Name | Type | Description |
|---|---|---|
pNd |
Element | string | The DOM Element or string id (item name) of the item. |
Returns:
- Type
- item
Example
This function is not used by itself. See the examples for methods of the item interface.
(static) region(pRegionId) → {region|null}
Return a region object for the given region id. The returned region object can then be used to access region related functions and properties.
Region plug-in developers can define the behavior of their region by calling apex.region.create.
Parameters:
| Name | Type | Description |
|---|---|---|
pRegionId |
string | Region id or region static id. It is a best practice to give a region a Static ID if it is going to be used from JavaScript otherwise an internally generated id is used. The region id is substituted in the region template using the #REGION_STATIC_ID# string. The region id can be found by viewing the page source in the browser. |
Returns:
- Type
- region | null
Example
This function is not used by itself. See the examples for methods of the region interface.
(static) submit()
(static) userHasTouched() → {boolean}
Determine if the user is or has been interacting with this web app using touch since the browser session began. Note: it is possible for the user to touch for the first time after this function is called.
It is rare to need know this information since the app should be designed to work for both touch and non-touch environments.
Returns:
- Type
- boolean