The Dialog Control

This page is a first attempt of establishing a new documentation style for Phoenix
that is combining code samples, actually running Phoenix controls and explanations
for specific focus areas or controls.

Introduction and Definition

The Phoenix Dialog control is used to temporarily display some limited-size user interface parts in front of the "regular" application without modifying or entirely removing it.
In doing so it resembles concepts known from other UI technologies under a range of names: Dialog Box, Dialog window, Popup, Popup Window, Alert Box, Message Box,...
The Phoenix Dialog is (currently) always modal, this means while it is opened, no user input can be directed to the regular UI.

From application programmer's perspective, the Dialog comes in two flavors:

The regular Dialog: you instantiate it like any other control, modify its properties, and finally open it
An easier-to-use version: the MessageBox class which offers various methods for easily opening frequently used types of alert boxes with only one line of code

Both are explained below.

Basic Usage

Creating and opening a Dialog

You can create an instance of the regular Dialog like you do with any other control, using its constructor new sap.ui.commons.Dialog(). Then you can set properties like the title or the Dialog content.
The Dialog has an aggregation for the buttons to be displayed at the bottom, so you can create one or more buttons and add them to the Dialog using its .addButton(...) method.
When the Dialog is ready, you can make it appear calling its .open() method. This method immediately returns the control flow, so your next instruction will be executed immediately, while the Dialog is still opened and the user has not clicked any button.

Reacting on user input and closing the Dialog

The Dialog buttons are regular buttons where you can register for the press event and act accordingly. If one of those buttons should close the dialog, the event handler just needs to call the Dialog's .close() method.
There is also another means of closing the Dialog: unless you set .showCloseButton(false), there will be the X-like close button in the header of the Dialog, which always closes the dialog. You can react on this case using the closed event, which will be invoked whenever the Dialog is closed.

How it looks like

Try it

View and edit the code

(Reset Code)

Simple Alert Boxes

A much easier way to open simple Dialogs is using the MessageBox class. Its simplest method is .alert(sMessage, fnCallback, sTitle) where every parameter except for the first one is optional.
So you can say "Hello World!" with one short line of code.

How it looks like

Try it

View and edit the code

(Reset Code)

A Simple Confirmation Question

A simple way to request a user decision is using MessageBox.confirm(sMessage, fnCallback, sTitle). Such a MessageBox has a question mark icon and an "OK" and "Cancel" button.
The given callback will receive a boolean value as parameter, which is true if the user clicked "Ok" and false if the user clicked "Cancel" or the X-close button.

How it looks like

Try it

View and edit the code

(Reset Code)

General MessageBox Dialogs

A more flexible, but still simple way to display popup Dialogs containing error, success, information, or warning messages is offered by the MessageBox.show(sMessage, oIcon, sTitle, vActions, fnCallback, oDefaultAction) method.
All but the first parameter are optional, but the strength of this method is how oIcon and vActions let you choose from predefined enumerations:
For the icons you can use presets like sap.ui.commons.MessageBox.Icon.WARNING or sap.ui.commons.MessageBox.Icon.ERROR
For the buttons to display you can use values like sap.ui.commons.MessageBox.Action.YES or sap.ui.commons.MessageBox.Action.NO. The respectively labeled (and translated) buttons will be displayed and the dialog result given to the callback method will equal the value of the selected button.

How it looks like

Try it

View and edit the code

(Reset Code)