Skip to Main Content

# Namespace: apex

## QuickNav

## apex

The apex namespace is the top level Oracle APEX namespace and contains a number of sub namespaces, and a few common functions and properties.

The apex namespace also contains information on APEX specific events.

### Namespaces

actions
da
date
debug
event
item
lang
locale
message
model
navigation
page
pwa
region
server
storage
theme
util
widget

### Properties

#### (static) env :object

This object holds various environment values related to the APEX instance, current application and page.

##### Type:

- object

##### Properties:

Name | Type | Description
--- | --- | ---
`APP_USER` | string | The current username
`APP_ID` | string | The application ID
`APP_PAGE_ID` | string | The page ID
`APP_SESSION` | string | The session ID
`APP_FILES` | string | The relative path of the application static files
`WORKSPACE_FILES` | string | The relative path of the workspace static files
`APEX_FILES` | string | The relative path of the files distributed with Oracle APEX
`APEX_VERSION` | string | The full version of the Oracle APEX instance
`APEX_BASE_VERSION` | string | The base version of the Oracle APEX instance

Since:
  - 21.2

##### Example

Redirect to page 2 in the current application.

    apex.navigation.redirect( "f?p=" + apex.env.APP_ID + ":2:" + apex.env.APP_SESSION );

#### (static) gPageContext$ :jQuery

This namespace property stores the current page context. The current page context is set to the HTML document (same as apex.jQuery(document)).

##### 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) items

This namespace property holds all the item interfaces that have been created on this page. See apex.item for details.

Since:
  - 21.2

#### (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 APEX 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
    }

#### (static) regions

This namespace property holds all the region interfaces that have been created on this page. See apex.region for details.

Since:
  - 21.2

### Events

#### apexafterclosecanceldialog

This event is triggered when an APEX modal dialog page is closed or cancelled by either the Dynamic Action Close Dialog action, the Dynamic Action Cancel Dialog action, the Close Dialog process, the Close (X) button of an dialog or by pressing the escape (ESC) key inside a dialog. This is equivalent to the Dialog Closed Dynamic Action event. This event is triggered on the element that opened the dialog.

For buttons it is the button element. For links to dialog pages in lists it is the list region element. For lists used in global top or side navigation or in any other case where the triggering element cannot be determined the event is triggered on the document apex.gPageContext$.

##### Properties:

Name | Type | Description
--- | --- | ---
`Event` | Event | `jQuery` event object
`data` | object | The event handler receives an object argument with these properties. ###### Properties
Name | Type | Description
--- | --- | ---
`dialogPageId` | string | The page number of the dialog page that closed.
`closeAction` | string | The action which triggered closing the dialog. Either "close" or "cancel".
`*` | string | For each page item listed in the Close Dialog process or dynamic action setting Items to Return there is a property with the same name as the item. The value is the value of the item.

##### Example

This example refreshes the region with HTML DOM id emp when any modal dialog page closes.

    apex.gPageContext$.on( "apexafterclosecanceldialog", function( event, data ) {
       apex.region( "emp" ).refresh();
    });

#### apexafterclosedialog

This event is triggered when an APEX modal dialog page is closed by either the Dynamic Action Close Dialog action or the Close Dialog process. This is equivalent to the Dialog Closed Dynamic Action event. This event is triggered on the element that opened the dialog.

For buttons it is the button element. For links to dialog pages in lists it is the list region element. For lists used in global top or side navigation or in any other case where the triggering element cannot be determined the event is triggered on the document apex.gPageContext$.

Note: This event is triggered in the parent or calling page not in the modal dialog page. If you want to know when the dialog is closed regardless of how it is closed use the `apexafterclosecanceldialog` event.

##### Properties:

Name | Type | Description
--- | --- | ---
`Event` | Event | `jQuery` event object
`data` | object | The event handler receives an object argument with these properties. ###### Properties
Name | Type | Description
--- | --- | ---
`dialogPageId` | string | The page number of the dialog page that closed.
`closeAction` | string | The action which triggered closing the dialog. In this case it is "close".
`*` | string | For each page item listed in the Close Dialog process or dynamic action setting Items to Return there is a property with the same name as the item. The value is the value of the item.

##### Example

This example refreshes the region with HTML DOM id emp when any modal dialog page closes.

    apex.gPageContext$.on( "apexafterclosedialog", function( event, data ) {
       apex.region( "emp" ).refresh();
    });

#### 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 `refreshObjectData` if any.

##### Example

This example disables the button with HTML DOM 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. 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 apex.event: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 `refreshObjectData` if any.

##### Example

This example disables the button with HTML DOM 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 enters edit mode).

##### Properties:

Name | Type | Description
--- | --- | ---
`event` | Event | `jQuery` event object.
`data` | object | Additional event data. ###### Properties
Name | Type | Description
--- | --- | ---
`model` | model | The model that is being edited.
`record` | model.Record | The record that is beginning to be edited.
`recordId` | string | The record id that is beginning to be edited.

#### apexcurrentrowchange

This event is triggered when the current item/row/record changes in a region that supports keyboard navigation and focus management. This event happens a few milliseconds after the last focused item/row/record changes.

Note that some widgets have their own more specific focus management event. See for example grid#event:currentcellchange.

##### Properties:

Name | Type | Description
--- | --- | ---
`event` | Event | `jQuery` event object.
`data` | object | Additional event data. ###### Properties
Name | Type | Description
--- | --- | ---
`currentValue` | Array.<string> | The value for the current item/row/record in the report or null if there is none. The value is typically configured to be the primary key of the record.

##### Example

A current item change event handler for a report region with HTML DOM id "myReport".

    apex.region( "myReport" ).element.on( "apexcurrentrowchange", function( event, data ) {
        console.log( "do something with current value", data.currentValue );
    } );

#### apexendrecordedit

This event is triggered when a model row/record is done being edited (when a new row/record is selected or exits edit mode).

##### Properties:

Name | Type | Description
--- | --- | ---
`event` | Event | `jQuery` event object.
`data` | object | Additional event data. ###### Properties
Name | Type | Description
--- | --- | ---
`model` | model | The model that is being edited.
`record` | model.Record | The record that is done being edited.
`recordId` | string | The record id that is done being edited.

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

This example makes the page item P1_VALUE upper case before the page is submitted.

    apex.jQuery( apex.gPageContext$ ).on( "apexpagesubmit", function() {
        var item = apex.item("P1_VALUE");
        item.setValue( item.getValue().toUpperCase());
    } );

#### apexreadyend

This event is triggered at the end of all APEX page load functionality. This events differs from the standard page load event in that it will not only wait for the DOM to be ready, but also for any delayLoading components to be ready.

Please see the delayLoading property of the apex.item.create API for further information about items that can delay loading.

##### Properties:

Name | Type | Description
--- | --- | ---
`event` | Event | `jQuery` event object.

##### Example

This example shows how to define an event handler for this event.

    apex.jQuery( apex.gPageContext$ ).on( "apexreadyend", function( e ) {
        // code here
    } );

#### apexselectionchange

This event is triggered when the selection changes in a region that supports selection. This event is debounced, which means that it is not triggered until up to a few hundred milliseconds after the last change in selection state. This avoids rapid event triggering while the user moves quickly through the report with the keyboard.

Note that some regions and widgets have their own more specific selection change event. See for example interactiveGrid#event:selectionchange.

##### Properties:

Name | Type | Description
--- | --- | ---
`event` | Event | `jQuery` event object.
`data` | object | Additional event data. ###### Properties
Name | Type | Description
--- | --- | ---
`selectedValues` | Array.<string> | An array of the values for the currently selected items/rows/records in the report. If nothing is selected the array is empty. The values are typically configured to be the primary key of the records.

##### Example

A selection change event handler for a report region with HTML DOM id "myReport".

    apex.region( "myReport" ).element.on( "apexselectionchange", function( event, data ) {
        console.log( "do something with selected values", data.selectedValues );
    } );

#### 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()

This function is an alias for apex.page.confirm.

#### (static) item(pItemId) → {item}

Return an item interface that is used to access item related methods and properties.

Item plug-in developers can override much of the item behavior, by calling apex.item.create with their overrides.

For items that are created with `apex.item.create` (which should be most items), the item interface can also be accessed from the apex.items collection by `pItemId`. So for an item with name "P1_NAME" the following are equivalent:

    let myItem = apex.items.P1_NAME;
    let myItem = apex.item( "P1_NAME" );

##### Parameters:

Name | Type | Description
--- | --- | ---
`pItemId` | Element | string | The item name. This is also the id of the main DOM element associated with the item. For backward compatibility this can also be the main item DOM Element. Passing in an element is deprecated and the id/name should be used instead.

##### Returns:

The item interface for the given item name. If there is no such item on the page the returned item interface `node` property will be false.

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 interface for the given region id. The returned region interface 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.

For regions that are created with `apex.region.create` (which is most native or plug-in regions that have significant dynamic behavior), the region interface can also be accessed from the apex.regions collection by `pRegionId`. So for a region with id "myRegion" the following are equivalent:

    let myRegion = apex.regions.myRegion;
    let myRegion = apex.region( "myRegion" );

##### Parameters:

Name | Type | Description
--- | --- | ---
`pRegionId` | string | Region id or region DOM id. It is a best practice to give a region an HTML DOM id if it is going to be used from JavaScript otherwise an internally generated id is used. The region DOM id is substituted in the region template using the #DOM_ID# string. The region id can be found by viewing the page source in the browser.

##### Returns:

The region interface or null if there is no element with the given `pRegionId`.

Type
  region | null

##### Example

This function is not used by itself. See the examples for methods of the region interface.

#### (static) submit()

This function is an alias for apex.page.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:

true if the user has been using touch to interact with the web app and false otherwise.

Type
  boolean