$.udb.navigateToLookup()

note

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

$.udb.navigateToLookup()

Navigates to a lookup 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.navigateToLookup( pageName [, options] )
.then(() => {
     // success (executed on the lookup page)
})
.catch(() => {
     // failure (executed on the original page)
})
.finally(() => {
     // executed after success / failure is handled
});

options ::= {
    [mode]: mode,
    [dsRef]: ds-ref,
    [$target]: ui-target,
    [pageTarget]: page-target,
    [quiet]: quiet,
    [title]: title
}

mode        ::= { ["edit"] | "search" }
ds-ref      ::= *string* | null
ui-target   ::= DOM | null
page-target ::= { ["Dialog"] | "Page" | "Current" }
quiet       ::= { true | [false] }
title       ::= *string* ["${PageTitle}"]

The required pageName is the name of the lookup page being navigated to.

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

Mode is a string that determines the whether the lookup value is copied in edit mode (as a manipulation) or in search mode (as a search value). The default is 'edit'.

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.

Title has an effect only if page-target is set to "Dialog". Title is a string representing the dialog title to be used. The string "${PageTitle}" denotes the page's 'Title' property in the Web Designer to be used.

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.

Ds-ref is a string that identifies the data source for which the lookup page is showing lookup data. It must be a valid data source reference (ID or name) of a data source that exists on the calling page. Its default is null, which means it may be ommitted, so that it will be automatically derived.

Ui-target is a DOM object on the calling page which will receive the lookup value when the lookup page is closed after selecting a value. It preferably contains data of the same data source as the ds-ref option, but this is not a requirement. The DOM object (often an input box of any kind) is also automatically re-focused when the lookup page gets closed.

Example 1

$.udb.navigateToLookup('MyLookupPage',{
    quiet: true,
    pageTarget: 'Dialog',
    title: 'My Lookup Page'
})
.then( () => {
  $.udb('Lookup DataSource').executeQuery();
});

Example 2

In this example, the effect of {mode: search} is that the value selected in the lookup page is used as a search condition on return to the calling page, as opposed to a value for data manipulation (a value used in an INSERT or UPDATE operation):

$.udb.navigateToLookup('MyLookupPage',
  { mode: 'search' }
)
.catch(() => {
  alert('Navigation to Lookup failed.');
});

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

note

lookup is not triggered by .navigateToLookup() itself. It works the other way around: lookup is the event fired when the user clicks an input control's lookup button, and its default handling is what calls .navigateToLookup(). See lookup for details.