$.udb.navigateTo()

note

This article is about the navigateTo() function of the udb object.

$.udb.navigateTo()

Navigates to a different page.

Returns a UdbPromise object.

danger

If you navigate away from a page, asynchronous operations are in risk of being annulled if they do not return a promise (as opposed to just executing with an undefined result).

Syntax

$.udb.navigateTo( *pageName*, [*options*] )
.then(() => {
     // success (executed on new page)
})
.catch(() => {
     // failure (executed on original page)
})
.finally(() => {
     // executed after success / failure is handled
});

*options*       ::=  {
    [applyChanges]:  *apply-changes*,
    [newPage]:       *new-page*,
    [pageTarget]:    *page-target*,
    [quiet]:         *quiet*,
    [targetFrame]:   *target-frame*
}

*apply-changes*  ::=  { [true] | false }
*new-page*       ::=  { true | [false] }
*page-target*    ::=  { ["Current"] | "Page" | "Dialog" }
*quiet*          ::=  { true | [false] }
*target-frame*   ::=  String

The required pageName is a string that identifies the page being navigated to.

Options is a struct that can have the following items, all of which are optional.

Apply-changes is a boolean that defines whether changes to values made on the current page must be applied. The default is true.

New-page determines if the record data on the previous page must replace the initial data on the target page or not.

• If new-page is false (the default), all data from the previous page are merged with data sources that exist on both pages. Data sources that do not exist on the new page are discarded. Data sources are matched by name and path.
• If new-page is true, all data of the previous page are discarded and re-queried where requested. This the default behavior with navigation for pages displayed on a Menu Control.

Page-target is a string specifying whether the page must be displayed as a dialog or a regular page. As dialog, the page is displayed as a modal dialog. As regular page, the page is displayed as the contents of the targetted frame context. The option page-target considers these strings as valid values:

• "Dialog" : the page is displayed as modal dialog
• "Page" : the page is displayed normally
• "Current" (default) : the page is displayed in the same manner that is used for the previous displayed page.

Quiet is a boolean that determines whether or not a message is displayed if an error occurs. Default is false, meaning that a message is displayed by default.

Target-frame is a string identifying the target frame in which page is to be opened. If not specified, the page is opened in the current context.

note

The option target-frame is considered deprecated, because page navigation can now be executed directly on the frame context in which the page must be displayed:

$.udb.context('ApplicationFrame').navigateTo(
    'MyNextPage',
    { quiet:true }
);

It is highly recommended to upgrade to the above syntax.

Example

$.udb.navigateTo('MyNextPage', {quiet: true} );

Related events

Event	Applies to	Occurs when
beforenavigate	Page objects	Before navigation to a different page takes place
startpagecomplete	Page objects	After the new page is displayed