Beta Draft: 2016-09-09

30.7 apex.navigation namespace

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

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

Parameters

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

Returns

Not applicable.

Example

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

30.7.2 apex.navigation.dialog.cancel

Closes the dialog window.

Parameters

pIsModal {Boolean} to identify whether the dialog is modal.

Returns

Not applicable.

30.7.3 apex.navigation.dialog.close

Executes an action and then closes the dialog window.

Parameters

pIsModal {Boolean} to identify whether the dialog is modal.
pAction {String, Function, Object} 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

Returns

Not applicable.

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'));
 
});

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

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.

Returns

Not applicable.

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

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.

Returns

Not applicable.

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

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");

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

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"

Returns

Not applicable.

Example

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

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

pItem (DOM node | string ID)
pValue (string)

Returns

Not applicable.

30.7.9 apex.navigation.redirect

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

Parameters

pWhere {String} the url of the page to open in the current window

Returns

Not applicable.