.dialog()

Previous Next

Displays a dialog in a dialog window. The dialog shows a message or starts a conversation with the user. The dialog is styled in the framework chosen in the publication configuration.

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

Returns a Promise object.

Syntax

.dialog( dialog-control )

 

dialog-control  ::=  dialog-control-name 

  {

       message:  dialog-message

  ,    title:  dialog-title

  ,    func:  close-dialog-function

  ,    fields:  fields-array

  ,    icon:  dialog-icon-class

  ,    buttons:  buttons

  ,    useOpacity:  use-opacity

  ,    closeButton:  close-button

  ,    promise:  promise

  }

 

buttons        ::=  button, button ...

button         ::=  { string | button-object }

 

use-opacity    ::=  true | false }

close-button   ::=  true | false }

promise        ::=  true | false }

The required dialog-control is either a string or a JSON object that can contain any of the items listed (with all the items except 'message' being optional)

If dialog-control is a string, the result will be a DialogControl with an "Id" property equal to the string value, if such a DialogControl exists.

If dialog-control is a JSON object, the variables described below come into play.

Dialog-message is the message that the dialog must display. This can be either a string, or an object with 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.

Close-dialog-function is a function called when a dialog button is pressed that causes the dialog to close. The function receives the string value (or the Id value of the button object, if used). This function is deprecated by the .then() clause of the Promise object returned by $.udb.dialog, which can perform the exact same action. See also close-botton below.

If you call $.udb.dialog() with a 'fields' fields-array, this will result in the call being transferred to $.udb.input() instead, so that the input fields can be properly displayed.

Dialog-icon-class is a string which designates a CSS icon class used in the dialog. It specifies what kind of dialog is to be displayed. This option is only supported if the JQuery-UI framework is specified (by the Framework publication property). The default is ‘ui-icon-alert’.

Buttons 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 will be used for the button's "Id" attribute and for the button's text label (which is also processed by the translation engine).

If a button object is passed, its parameters will be used to create a customised button. The syntax of these button objects is the same as for the .usdialog() framework API function. The default is a single "OK" button without any special customisation.

Use-opacity is a boolean that determines if the dialog is displayed as a modal dialog, in which case an Opacity Control 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, the dialog closes without the close-dialog-function being processed.

If promise is true (the default), a Promise object is returned. Otherwise, ‘undefined’ is returned.

 

Examples

$.udb.dialog({

    message: "Are you sure you want to delete this record?",

    title: "",

    buttons: ["YES", "NO"]

}).then(function(result) {

    if (result === "YES") {

        $.udb("TABLE").rows("current").rowDelete()

            .then(function() {

                $.udb.commit({quiet: true});

            });

    }

});

 

$.udb.dialog({

    message: {

        message: "PENDING",

        params: [changedRows.length]

    },

    title: "Information",

    buttons: ["SAVE", "DISCARD", {id: "CANCEL", default: true}],

    closeButton: false,

    icon: "ui-icon-info"

}).then(function(result) {

    if (result === "" || result === "CANCEL") {

     return;

    } else

    if (result === "SAVE") {

     $.udb.commit({quiet: this.params.quiet});

     return;

    } else

        //...

});

 

See also

.input()