$.udb.dialog()

note

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

$.udb.dialog()

Displays a dialog in a dialog window. The dialog shows a message or starts a conversation with the user. It can also be a Dialog Control embedded in the current page.

Calling .dialog() with a message while another message dialog is already being displayed will result in both messages being displayed in the same dialog.

Returns a UdbPromise object. To its .then() clause following, an object is passed that contains information about the button that was pressed to close the dialog.

tip

The $.udb.dialog() function is similar to $.udb.input(), which allows you to display an input form besides just a message.

To display a HTML structure built with Web Designer as a dialog, or when more control of how dialog content is styled, the .usdialog() may be preferred instead.

Syntax

$.udb.dialog( *dialog-control-id* )
$.udb.dialog( *options* )
.then( *result* => {
    ...
.catch(() => {
     // failure
})
.finally(() => {
     // executed after success / failure is handled
});

options   ::=  {
    *message*:     *dialog-message*,
    [title]:       *dialog-title*,
    [icon]:        *dialog-icon*,
    [buttons]:     *buttons-list*,
    [useOpacity]:  *use-opacity*,
    [closeButton]: *close-button*
}

*dialog-message* ::= { *string* | *message-object* }
*message-object* ::= {
    [code]:     *string*,
    [params]:   Array[*string*],
    [string]:   *string*
}

*dialog-title*   ::= { ['Warning'] | *string* }
*dialog-icon*    ::= { ['bi-exclamation-triangle-fill'] | *string* }
*use-opacity*    ::= { [true] | false }
*close-button*   ::= { [true] | false }

*button-list*    ::=   Array[*button*]
*button*         ::=   { *string* | *button-object* }
*button-object*  ::= {
    *id*:       *string*,
    [label]:    *string*,
    [func]:     *button-function*,
    [class]:    *button-class*,
    [default]:  *button-default*
}

*result*  ::= {
    answer: *answer*,
    caller: *options*
}

The first use of this function is with a dialog-control-id parameter which is a string that must be the exact value of the 'Id' property of a Dialog Control used in the currently displayed page. If this control is found, then the dialog is displayed.

The other use of this function is with an options struct, in which all items are optional except for the message option which must have a value to display.

Dialog-message is the message that the dialog must display. This can be either a string, or an object with either a code string (referring to a translatable message in the JSON file that contains these messages), or a message parameter string and an optional params array. Both options are processed by the translation engine to create the required end user message. Passing an empty message (or omitting it) will result in no dialog being displayed.

Dialog-title is the title of the dialog. The default value is 'Warning'. The title is displayed in a title bar across the top of the dialog. If set to '' (the empty string), this title bar will not be displayed. In the same way as with dialog-message, the title can be either a string, or an object with a message parameter string with an optional params array, and both are processed by the translation engine to create the required title string.

Dialog-icon is a string which designates a CSS icon class used in the dialog to be displayed, indicating what kind of dialog is displayed (e.g. a warning message). The default is 'bi-exclamation-triangle-fill' which displays a warning icon.

Button-list is an array of button definitions for one or more buttons displayed at the bottom of the dialog. For each button you can pass either a string value or a button-object:

• If a string is passed, its value is considered to be both the button 'id' and its text label. This text label is also processed by the translation engine.
• If a button-object is passed, its parameters will be used to create a customised button. The default is a single 'OK' button without any special customisation. The syntax of these button objects is the listed above, and is also same as for the .usdialog() function:
  • the id and label properties are strings, of which at least id is mandatory.
  • the button-function is a function that must be executed if that button gets pressed.
  • the button-class is a string which designates a CSS class that must be added to the button. It could be used to add an icon on the button, or e.g. to change its background color.
  • the button-default is a boolean to indicate if the button must be selected on default. The first button in the list to have this property set to true is considered default. If none have it, this is always the first button.

When one of these buttons in the button-list is pressed, the id property of that button is stored in the result.answer property sent to its .then() clause afterwards.

Use-opacity is a boolean that determines if the dialog is displayed as a modal dialog, in which case a modal backdrop layer is displayed behind the dialog so that anything on the underlying page becomes inaccessible. The dialog is modal if use-opacity is true (the default), and non-modal otherwise.

Close-button is a boolean that determines if a close icon ( 'X' ) is displayed in the top-right corner of the dialog. If the user presses this icon, then its consecutive .then() clause gets executed with the result.answer value being empty, because none of the buttons was pressed.

After pressing any button (including the close button at the top-right), the .then() clause of the UdbPromise resulting from the .dialog() function is called, with its result parameter filled with the id value of the pressed button in its answer field, and the original options passed to the function in the caller parameter of result.

::: note If you use $.udb.dialog() with a fields option, it will this will in the $.udb.input() being called instead, so that the input fields can be properly displayed. However it is preferable to just call $.udb.input() directly then.

:::

Example 1

$.udb.dialog({
    message: 'Are you sure you want to delete this record?',
    title: 'Confirm delete',
    buttons: ['YES', 'NO']
}).then((result) => {
    if (result.answer === 'YES') {
        return $.udb('PERSON').rows('current').rowDelete();
    }
});

Example 2

$.udb.dialog({
    message: {
        message: 'You have {{1}} changed rows pending',
        params: [changedRows.length]
    },
    title: 'Information',
    buttons: ['SAVE', 'DISCARD', {id: 'CANCEL', default: true}],
    closeButton: false,
    icon: 'bi-exclamation-triangle-fill'
})
.then((result) => {
    if (result.answer === '' || result.answer === 'CANCEL') {
        console.log('Commit was cancelled');
    } else
    if (result.answer === 'SAVE') {
        return $.udb.commit({ quiet: true });
    } else {
        //...
    }
});

Related events

Event	Applies to	Occurs when
dialogopen	Dialog controls	Right after a dialog has been shown
dialogclose	Dialog controls	Right after a dialog has closed
dialogbeforeclose	Dialog controls	Immediately before a dialog closes

note

When .dialog() is called with an options struct (rather than a dialog-control-id string), it triggers these events by displaying the dialog through the same underlying "message" control that $.udb.input() uses (a DataInputControl). When it is instead called with a dialog-control-id string identifying a pre-existing dialog on the page, it only triggers dialogopen; closing that kind of dialog is handled elsewhere on the page and is not part of .dialog() itself.