Handling dialog windows

JS extension ui.dialogs.messagebox

JS extension ui.dialogs.messagebox provides API for creating standard Alert and Confirm dialog window types. (UI module version 19.0.500).

Connecting at PHP page

\Bitrix\Main\UI\Extension::load("ui.dialogs.messagebox");

Connecting in ES6

import { MessageBox } from 'ui.dialogs.messagebox';

Options

• 4 button variants: ОК, Yes, No, Cancel.
• Several variants of button sets: Ок, Yes, No, Cancel, Ок-Cancel, Yes-Cancel, Yes/No, Yes-No-Cancel.
• Each button text can be customized and its callback specified.
• Button is automatically blocked (disabled) for debounce protection.
• When button's callback returns a promise, button transitions to "loading" status.
• Dialog window title support. In this case, buttons become bigger and are separated from content by a line.
• Arbitrary buttons (objects or class descendants BX.UI.Button) can replace standard buttons.
• Mode modal adds an overlay.
• Additionally, options can be passed for BX.PopupWindow.

Basic use

To quickly create dialog windows, use static methods Alert and Confirm.

Note: When dialog window contains multiline text or layout elements (images, checkboxes and etc.), always specify a title.

Informational dialog window (alert)

This method allows quickly create an informational dialog window (Alert).

BX.UI.Dialogs.MessageBox.alert("Message", (messageBox, button, event) => {});
BX.UI.Dialogs.MessageBox.alert("Message", (messageBox, button, event) => {}, "Continue");
BX.UI.Dialogs.MessageBox.alert("Message", "Title");
BX.UI.Dialogs.MessageBox.alert("Message", "Title", (messageBox, button, event) => {});
BX.UI.Dialogs.MessageBox.alert("Message", "Title", (messageBox, button, event) => {}, "Continue");

BX.UI.Dialogs.MessageBox.alert(
    message: string | Element | Node, 
    okCallback?: Function, 
    okCaption?: string
);

//Method signature with specified dialog window title
BX.UI.Dialogs.MessageBox.alert(
    message: string | Element | Node, 
    title?: string, 
    okCallback?: Function, 
    okCaption?: string
);

Asynchronous callback

BX.UI.Dialogs.MessageBox.alert(
    "Asynchronous processing of button click", 
    (messageBox, button, event) => {
        return new Promise((resolve, reject) => {
            console.log("async job started.");
            setTimeout(() => {
                console.log("async job ended.");
                resolve(true);
            }, 3000);
        });
    }
);

The same example, but without promises.

BX.UI.Dialogs.MessageBox.alert(
    "Manual asynchronous button click processing", 
    (messageBox, button, event) => {

        console.log("async job started.");
        button.setWaiting();

        setTimeout(() => {
            button.setWaiting(false);
            messageBox.close();
            console.log("async job ended.");
        }, 3000);
    }
);

Confirmation dialog window

This method allows quickly created a confirmation dialog window.

BX.UI.Dialogs.MessageBox.confirm("Message");
BX.UI.Dialogs.MessageBox.confirm("Message", () => {});
BX.UI.Dialogs.MessageBox.confirm("Message", () => {}, "Continue");
BX.UI.Dialogs.MessageBox.confirm("Message", () => {}, "Continue", () => {});
BX.UI.Dialogs.MessageBox.confirm("Message", "Title");
BX.UI.Dialogs.MessageBox.confirm("Message", "Title", () => {});
BX.UI.Dialogs.MessageBox.confirm("Message", "Title", () => {}, "Continue", () => {});

BX.UI.Dialogs.MessageBox.confirm(
    message: string | Element | Node, 
    okCallback?: Function, 
    okCaption?: string, 
    cancelCallback?: Function
);

//Method signature with specified dialog window title
BX.UI.Dialogs.MessageBox.confirm(
    message: string | Element | Node, 
    title?: string, 
    okCallback?: Function, 
    okCaption?: string, 
    cancelCallback?: Function
);

Creating dialog windows

All dialog window settings can be passed via static method show.

BX.UI.Dialogs.MessageBox.show(
{
    message: "Text with popup content description, located here.",
    modal: true,
    buttons: BX.UI.Dialogs.MessageBoxButtons.OK_CANCEL,
    onOk: function(messageBox)
    {
        console.log("onOk");
        messageBox.close();
    },
    onCancel: function(messageBox)
    {
        console.log("onCancel");
        messageBox.close();
    },
}
);

Arbitrary set of buttons:

BX.UI.Dialogs.MessageBox.show(
{
   message: `
      <label class="ui-ctl ui-ctl-checkbox">
         <input type="checkbox" class="ui-ctl-element">
            <div class="ui-ctl-label-text">delete settings and app data</div>
      </label>
   `,
   title: "Are you sure you want to delete the app?",
   buttons: [
      new BX.UI.Button(
      {
         color: BX.UI.Button.Color.DANGER,
         text: "Delete"
      }
      ),
      new BX.UI.CancelButton()
   ],
}
);

When you need to get link to a dialog object, there is a method create.

const messageBox = BX.UI.Dialogs.MessageBox.create(
{
    message: "Are you sure you want to delete the file?",
    title: "Confirm deleting",
    buttons: BX.UI.Dialogs.MessageBoxButtons.OK_CANCEL,
    onOk: function(messageBox)
    {
        console.log("onOk");
        messageBox.close();
    },
}
);

messageBox.show();

Or create a class object BX.UI.Dialogs.MessageBox.

const messageBox = new BX.UI.Dialogs.MessageBox(
{
    message: "Are you sure you want to delete the file?",
    title: "Deleting confirmation",
    buttons: BX.UI.Dialogs.MessageBoxButtons.OK_CANCEL,
    okCaption: "Yes",
    onOk: function() 
    {
        console.log("onOk");
    },
}
);


messageBox.show();

Button click processing

Default clicking on any button closes the dialog window. When handler is defined for a button, dialog window behaviour depends on returned value:

• true — close dialog window.
• false — disabled status removed from the button, dialog window stays opened.
• undefined (void) — no automatic actions, dialog window closing or removal of disabled button status must be done manually.
• Promise — button transitions to "loading" status. Promise resolve closes dialog window; rejected promise returns button to original state.

BX.UI.Dialogs.MessageBox.alert("Message", (messageBox, button, event) => 
{
    messageBox.close();
}
);

Button handlers have the arguments as follows:

• messageBox — dialog object (class instance BX.UI.Dialogs.MessageBox).
• button — button object (class instance BX.UI.Button).
• event — click event object (MouseEvent).