Skip to Main Content

# Namespace: navigation

## QuickNav

## apex.navigation

This namespace contains functions related to dialog, popup, and redirect functionality of Oracle APEX.

### Namespaces

dialog
popup

### Functions

#### (static) dialog(pUrl, pOptions, pCssClasses, pTriggeringElement)

Opens the specified page ( pUrl ) in a dialog. The `modal` option determines if the page is a modal page or a non-modal page.

A modal page is loaded in an iframe using jQuery UI dialog widget. It is an overlay window positioned within the same browser window. When a modal dialog is active, the user is unable to interact with the rest of the page, until the dialog is closed.

A non-modal page is loaded in a new window using the apex.navigation.popup function. A user can interact with a non-modal dialog and content on the page.

Note: Typically this API is called internally via a special URL syntax generated by the server when the target page is a dialog. At a minimum the url of the dialog page must be generated on the server so that the correct dialog checksum can be generated.

##### Parameters:

Name | Type | Description
--- | --- | ---
`pUrl` | string | The URL of the page to load as a dialog. The URL can be the return value of `APEX_PAGE.GET_PAGE` even for dialog pages.
`pOptions` | Object | Identifies the attributes of the dialog, such as height, width, maxWidth, title, modal. ###### Properties
Name | Type | Attributes | Description
--- | --- | --- | ---
`title` | string | <optional> | The title of the dialog. The default is the name of the page. This option only applies to a modal dialog.
`height` | number | <optional> | The height of dialog content area, in pixels. The default is 500. This option only applies to a non-modal dialog.
`width` | number | <optional> | The width of window content area, in pixels. The default is 500. This option only applies to a non-modal dialog.
`maxWidth` | number | <optional> | The maximum width of window content area, in pixels. The default is 1500.
`modal` | boolean | <optional> | If true (the default), the url will be opened in a modal dialog. If false, the url will be opened in a non-modal popup.
`*` | * | <optional> | Additional options supported by the underlying dialog implementation. For example, to define jQuery UI Dialog attribute `resizable`, set to `resizable:true` See Also : See jQuery UI documentation of Dialog widget for all other available options for a modal dialog. http://api.jqueryui.com/dialog/
`pCssClasses` | string | Identifies the CSS classes, if any, to be applied to the dialog, and appended on to the dialogClass attribute. Look in the corresponding page template to determine what classes to use.
`pTriggeringElement` | string | jQuery selector to identify the APEX page element opening the dialog. The `apexafterclosedialog` or `apexafterclosecanceldialog` event is triggered on this page element.

##### Examples

This example demonstrates opening a resizable APEX modal dialog page, with a defined height and width. The value of P1_DIALOG_URL is generated by the server using `APEX_PAGE.GET_URL` with the `p_plain_url` parameter set to `true`. A button with HTML DOM id `mybutton` is used to launch the modal dialog. Using an associated Dynamic Action, the click of the button invokes the execution of the following JavaScript code:

        apex.navigation.dialog(
            apex.items.P1_DIALOG_URL.value,
            {
                title:'Orders',
                height:'480',
                width:'800',
                modal:true,
                resizable:true
            },
            't-Dialog-page--standard',
            '#mybutton' );

This example demonstrates opening an APEX modal dialog page with a defined height and width. The value of P1_DIALOG_URL is generated by the server using `APEX_PAGE.GET_URL` with the `p_plain_url` parameter set to `false`. The URL contains the values for the other options, CSS classes, and triggering Element:

        apex.navigation.dialog(
             apex.items.P1_DIALOG_URL.value,
             {
                height:'480',
                width:'800',
             } );

#### (static) popup(pOptions) → {Object|null}

Opens the given URL in a new typically named popup window. If a window with that name already exists, it is reused. If no name is given or the name is "_blank" then a new unnamed popup window is opened. The names "_self", "_parent" and "_top" should not be used. The window name is made unique so that it cannot be shared with other apps.

Every effort is made to focus the window. The intention is that the window will be a popup window and not a tab. The default window features are such that most browsers should open a new window.

Note: To avoid being suppressed by a popup blocker, call this from a click event handler on a link or a button.

##### Parameters:

Name | Type | Description
--- | --- | ---
`pOptions` | Object | An object with the following optional properties: ###### Properties
Name | Type | Attributes | Description
--- | --- | --- | ---
`url` | string | <optional> | The page URL to open in the window. The default is "about:blank".
`name` | string | <optional> | The name of the window. The default is "_blank", which opens a new unnamed window.
`height` | number | <optional> | The height of window content area in pixels. The default is 600.
`width` | number | <optional> | The width of window content area in pixels. The default is 600.
`scroll` | string | <optional> | "yes" or "no". The default is "no".
`resizeable` | string | <optional> | "yes" or "no". The default is "yes".
`toolbar` | string | <optional> | "yes" or "no". The default is "no".
`location` | string | <optional> | "yes" or "no". The default is "no".
`statusbar` | string | <optional> | "yes" or "no". The default is "no". This controls the status feature.
`menubar` | string | <optional> | "yes" or "no". The default is "no".

##### Returns:

The window object of named window or null, if window was not opened.

Type
  Object | null

##### Examples

This example demonstrates a very simple call to open an unnamed popup window. The new window can be accessed from variable `myPopupWindow`. It is best to supply the url, name and possibly the height and width; all other parameters will have their default value.

    var myPopupWindow = apex.navigation.popup (
        {
            url:    "about:blank",
            name:   "_blank",
            width:  400,
            height: 400
        }
        );

This example demonstrates a call to open the url in a named popup window, "Information". The new window can be accessed from variable `myPopupWindow`. Some additional parameters are also set in the call, to control scrolling, resizing and the visibility of a toolbar. The variable `myTriggeringElement` is used to define the triggering element of the popup, a button named `myButton`. Using a call to apex.navigation.dialog.registerCloseHandler, a new handler can be defined, to associate the close action of the dialog with the button.

    var myTriggeringElement,
        myPopupWindow;

    myTriggeringElement = apex.jQuery( '#myButton' );

    myPopupWindow = apex.navigation.popup ( {
        url:       "f?p=102:2:&APP_SESSION.:::2::",
        name:      "Information",
        scroll:    "no",
        resizable: "no",
        toolbar:   "yes"
    } );

    navigation.dialog.registerCloseHandler( {
        handler$:           myTriggeringElement,
        dialog:             myPopupWindow,
        triggeringElement$: myTriggeringElement,
        closeFunction:      function() {
            myPopupWindow.close();
        }
    });

#### (static) openInNewWindow(pURL, pWindowNameopt, pOptionsopt) → {Object|null}

Opens the given URL in a new named window or tab (the browser / browser user preference settings may control if a window or tab is used). If a window with that name already exists it is reused. The names "_self", "_parent" and "_top" should not be used. The window name is made unique so that it cannot be shared with other apps. Every effort is made to then focus the new window.

Unlike a popup, the new window is intended to be fully functional. This is intended to be as close as you can get to a normal anchor with a target (`<a target="name" href="...">`) behavior from JavaScript but with the feature of focusing the window in all browsers by default.

If option `favorTabbedBrowsing` is true: For IE, Edge, and Firefox, the user may need to manually focus the tab (assuming the browser is configured to open pages in tabs).

If option `favorTabbedBrowsing` is not true (the default): For IE and Firefox, the page will be opened in a new browser window (unless explicitly overridden by a browser setting). But it will very likely be able to focus the new page.

Once the named window is open the `favorTabbedBrowsing` setting doesn't apply to that window.

Note: Firefox, Edge, and IE will not focus a tab if that tab isn't the currently active tab in its browser window.

Note: For Opera the Advanced/content > JavaScript Options: "Allow raising of windows" must be checked in order for focus to work.

Note: To avoid being suppressed by a popup blocker call this from a click event handler on a link or button.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`pURL` | string |  | The URL of the page to load.
`pWindowName` | string | <optional> | The name of the window. The default is "_blank".
`pOptions` | Object | <optional> | Options object with these properties: ###### Properties
Name | Type | Attributes | Description
--- | --- | --- | ---
`altSuffix` | string | <optional> | An Alternative suffix to append to `pWindowName` to make it unique.
`favorTabbedBrowsing` | boolean | <optional> | If true, don't try to force a new window for the benefit of being able to focus it.
`noopener` | boolean | <optional> | If true the new opened window does not have access to this window via its `window.opener` property. The default is true if the new window name is "_blank" and false otherwise.

##### Returns:

The window object of named window or null if window was not opened. Note that if option `noopener` is true then the return value is always null.

Type
  Object | null

##### Example

This example opens the URL in variable `url` in a new window. The new window can be accessed from variable `myWindow`.

    var myWindow = apex.navigation.openInNewWindow( url, "MyWindow" );

#### (static) redirect(pWhere, pIgnoreUnsavedChanges)

Opens the specified page (pWhere) in the current window.

##### Parameters:

Name | Type | Description
--- | --- | ---
`pWhere` | string | The URL of the page to open.
`pIgnoreUnsavedChanges` | boolean | Whether to ignore the checks for unsaved changes. The default is false.

##### Examples

This example demonstrates a call to redirect to page 3 within the current application, in the current session, with debugging set to `NO` and setting `RP` to reset pagination for an Interactive Report on page 3. The substitution string, `APP_SESSION` is substituted on the server with the current session ID.

    apex.navigation.redirect ( "f?p=&APP_ID.:3:&APP_SESSION.::NO:RP::" );

This example demonstrates a very simple call to redirect to page 1 in application ID 102, in the current session. The substitution string, `APP_SESSION` is substituted on the server with the current session ID.

    apex.navigation.redirect ( "f?p=102:1:&APP_SESSION.:::::" );

This example demonstrates a call to redirect to page 3 within the current application, `apex.env.APP_ID` in the current session, `apex.env.APP_SESSION`, which is processed on the client. This example demonstrates calling this function from within a JavaScript file.

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

This example demonstrates a call to redirect to a URL defined in a page item, `P1_URL"`.

    apex.navigation.redirect( apex.item("P1_URL").getValue() );