38.8 apex.navigation namespace

The apex.navigation namespace contains popup and redirect related functions of Oracle Application Express.

Parent topic: JavaScript APIs

38.8.1 apex.navigation.dialog

Opens the specified page in a dialog. For mobile UI, the page is loaded using a role 'dialog' in a mobile.changePage call. For desktop UI, a modal page is loaded in an iframe using jQuery UI dialog widget. For desktop UI, a non-modal page is loaded in a popup browser window. 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 window.

Note:

Typically this API call is generated by the server when the page target is a modal page or by using APEX_UTIL.PREPARE_URL. 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

Table 38-36 apex.navigation.dialog

Name Type Description

pUrl

String

The url of the page to load.

pOptions

Object

Object to identify the attributes of the dialog, with the following properties:

  • title - the title of the dialog. The default is the name of the page.

  • height - height of dialog content area, in pixels, default is 500.

  • width - width of window content area, in pixels, default 500.

  • maxWidth - maximum width of window content area, in pixels, default 1500.

  • modal - true or false. Default is true.

  • dialog_attributes - optional attribute, to allow the setting of any additional options supported by the underlying dialog implementation.

For example, to define jQuery UI Dialog attribute resizable:

resizable:false

See Also : See jQuery UI documentation of Dialog widget for all other available options for a modal dialog in a desktop user interface. http://api.jqueryui.com/

See jQuery Mobile documentation of Dialog widget for all other available options for a modal dialog in a mobile user interface. http://jquerymobile.com/

pCssClasses

String

To identify the CSS classes, if any, to be applied to the dialog, and appended on to the dialogClass attribute.

pTriggeringElement

String

jQuery selector to identify APEX page element opening the dialog.

Example

apex.navigation.dialog(url, {
    title:'About',
    height:'480',
    width:'800',
    maxWidth:'1200',
    modal:true,
    resizable:false },
    'a-Dialog--uiDialog',
    '#myregion_static_id');

Parent topic: apex.navigation namespace

38.8.2 apex.navigation.dialog.cancel

Closes the dialog window.

Parameters

Table 38-37 apex.navigation.dialog.cancel

Name Type Description

pIsModal

Boolean

To identify whether the dialog is modal.

Parent topic: apex.navigation namespace

38.8.3 apex.navigation.dialog.close

Executes an action and then closes the dialog window.

Parameters

Table 38-38 apex.navigation.dialog.close

Name Type Description

pIsModal

Boolean

To identify whether the dialog is modal.

pAction

String, Function, Object

This can be:

  • a URL which will trigger a redirect in the parent page

  • a function to redirect to a different dialog page

  • false to cancel the dialog

  • an object of page items and values which will be exposed in the 'Dialog Closed dynamic action event

Example

To handle chaining from one modal dialog page to another:

apex.navigation.dialog.close(true, function( pDialog ) {
    apex.navigation.dialog(url, {
        title:'About',
        height:'480',
        width:'800',
        maxWidth:'1200',
        modal:true,
        dialog:pDialog,
        resizable:false },
        'a-Dialog--uiDialog',
        '#myregion_static_id');
 
});

Parent topic: apex.navigation namespace

38.8.4 apex.navigation.dialog.fireCloseHandler

Fires the internal close event of a dialog which was registered with the registerCloseHandler when the dialog was opened.

Parameters

Table 38-39 apex.navigation.dialog.fireCloseHandler

Name Type Description

pOptions

Object

pOptions has to contain the following attributes:

  • "handler$" jQuery object where the event will be registered for.

  • "dialog" DOM/jQuery/... object of the current dialog instance which will be passed into the open dialog call if the existing dialog should be re-used.

  • "closeFunction" Function which is used to close the dialog.

Parent topic: apex.navigation namespace

38.8.5 apex.navigation.dialog.registerCloseHandler

Registers the internal "close" event of a dialog. The event will be triggered by fireCloseEvent and depending on the passed in pAction, it will:

  • Re-use the existing dialog and navigate to a different dialog page

  • Navigate to a different page in the caller

  • Cancel the dialog

  • Close the dialog and trigger the "apexafterclosedialog" event

Parameters

Table 38-40 apex.navigation.dialog.registerCloseHandler

Name Type Description

pOptions

Object

pOptions has to contain the following attributes :

  • "handler$" jQuery object where the event will be registered for.

  • "dialog" DOM/jQuery/... object of the current dialog instance which will be passed into the open dialog call if the existing dialog should be re-used.

  • "closeFunction" Function which is used to close the dialog.

Parent topic: apex.navigation namespace

38.8.6 apex.navigation.openInNewWindow

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

Note:

Firefox and IE will not focus a tab if that tab is not the currently active tab in its browser window. This is why, unless favorTabbedBrowsing is true, this API forces the url to open in a new window so that it has a better chance of being focused.

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

Table 38-41 apex.navigation.openInNewWindow

Name Type Description

pUrl

String

The url of the page to load.

pWindowName

String

The name of the window (optional) The default is "_blank"

pOptions

Object

Optional object with the following properties:

  • favorTabbedBrowsing - {Boolean} if true don't try to force a new window for the benefit of being able to focus it. This option only affects Firefox and IE.

Returns

Returns the window object of the named window or null if for some reason the window isn't opened.

Example

apex.navigation.openInNewWindow(url, "MyWindow");

Parent topic: apex.navigation namespace

38.8.7 apex.navigation.popup

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

Note:

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

Parameters

Table 38-42 apex.navigation.popup

Name Type Description

pOptions

Object

An object with the following optional properties:

  • url - the page url to open in the window. The default is "about:blank".

  • name - the name of the window. The default is "_blank", which opens a new unnamed window.

  • height - height of window content area in pixels. Default 600.

  • width - width of window content area in pixels. Default 600.

  • scroll - "yes" or "no" Default is "yes".

  • resizeable - "yes" or "no" . Default is "yes".

  • toolbar - "yes" or "no". Default is "no".

  • location - "yes" or "no". Default is "no".

  • statusbar - "yes" or "no". Default is "no". This controls the status feature.

  • menubar - "yes" or "no". Default is "no".

Example

apex.navigation.popup ({
    url: "about:blank",
     name: "_blank",
     width: 400,
     height: 400,
     scroll: "no",
     resizable: "no",
     toolbar: "yes" });

Parent topic: apex.navigation namespace

38.8.8 apex.navigation.popup.close

Sets the value of the item (pItem) in the parent window, with (pValue) and then closes the popup window.

Parameters

Table 38-43 apex.navigation.popup.close

Name Type Description

pItem

DOM node | string ID

The item to set.

pValue

string

The item value to set.

Parent topic: apex.navigation namespace

38.8.9 apex.navigation.redirect

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

Parameters

Table 38-44 apex.navigation.redirect

Name Type Description

pWhere

String

The url of the page to open in the current window.

Parent topic: apex.navigation namespace