Working with Windows: Dialog Boxes

Working with Windows

Dialog Boxes

JavaScript features several built-in dialog boxes: window.alert(), window.confirm(), and window.prompt(). When a dialog box pops up, the user cannot focus on the original page until the box is terminated. In other words, a dialog box is always focused. Internet Explorer supports a few methods that enable you to apply this feature to any new window:

showModalDialog() (Internet Explorer 4 and above)
showModelessDialog() (Internet Explorer 5 and above)

Here's the syntax for these methods:

vReturnValue = window.showModalDialog(sURL[, vArguments][, sFeatures]);
vReturnValue = window.showModelessDialog(sURL[, vArguments][, sFeatures]);

The first argument is a string that specifies the URL of the document to load and display in the new window. The second argument, vArguments, is a variant that specifies the arguments to use when displaying the document. Use this parameter to pass a value of any type, including an array of values. The dialog box can extract the values passed by the caller from the dialogArguments property of the window object.

When a new window is opened by one of these methods, the window object of the new window (the dialog box) features the dialogArguments property, which holds the value that was assigned to the vArguments parameter of the calling method. Take a look at the following statement:

window.showModalDialog("modalurl.html", window);

Notice that the second argument is actually the window object of the current browser window. Here's the code for modalurl.html:

<HTML>
<HEAD>
<TITLE>Change the URL</TITLE>
<SCRIPT LANGUAGE="JavaScript">
<!--
function load(menu) {
  if (window.dialogArguments && dialogArguments.location) {
    dialogArguments.location.href = menu.options[menu.selectedIndex].value;
    window.close();
  }
}
// -->
</SCRIPT>
</HEAD>
<BODY>
Pick your favorite investment site:<P>
<FORM><SELECT NAME="menu">
<OPTION VALUE="https://www.fool.com/">Fool.com (The Motley Fool)
<OPTION VALUE="https://www.investor.com/">MoneyCentral Investor
<OPTION VALUE="https://www.thestreet.com/">TheStreet.com
</SELECT>
<INPUT TYPE="button" VALUE="Load" onClick="load(this.form.menu)"></FORM>
</BODY>
</HTML>

When the user clicks the "Load" button in the dialog box, the URL of the opener window is changed to the selected value. In order to set the URL of a window's document, we must assign a value to the desired window object's location.href property. In this case, we specified the window object of the caller as the second argument of the showModalDialog() method, so the dialogArguments property in the new window (the dialog box) reflects the caller's window object.

Notice the object detection routine at the beginning of the function. Since the dialogArguments property only exists in windows created by the showModalDialog() and showModelessDialog() methods, we must make sure this property exists before attempting to access it. Furthermore, we need to look for a location.href property to be sure that the dialogArguments property really reflects a valid window object.

The final statement of the load() function closes the dialog box so the specified document can load in the original window. Note that if we use the showModelessDialog() method instead of showModalDialog(), we don't need to explicitly close the window, because the new URL loads in the underlying window (the opener) even if the dialog box is still open. In this case, the dialog box automatically closes when the URL of the caller window changes (when the new page loads). Here's a live example:

When you invoke showModelessDialog() (Internet Explorer 5), a dialog box appears, layered in front of the browser window. The user can still handle the underlying window, but the dialog window stays on top. The dialog box is associated with the browser window that opened it, so if the user raises a different window, the dialog box hides back with its opener window. Note that a modeless dialog box is actually connected to the document containing the script that launched it, so if the user load a different URL in the opener window, the dialog box automatically closes.

The showModalDialog() method (Internet Explorer 4) is quite different. It creates a modal dialog box that remains focused until it is closed. The user cannot access the opener window at all. A modal dialog box is associated with a specific window (the one that opened it), so if the user brings up a different browser window, the dialog box sticks with its original window and hides behind the active window.

It's time to head back to our discussion about the arguments of the showModalDialog() and showModelessDialog() methods. The third argument, sFeatures, is a string that specifies the window ornaments for the dialog box, using one or more of the following semicolon-delimited values:

dialogHeight: iHeight: Sets the height of the dialog window. Although a user can manually adjust the height of a dialog box to a smaller value (provided the dialog box is resizable), the minimum dialogHeight you can specify is 100 pixels. Note that the default unit of measure for dialogHeight and dialogWidth in Internet Explorer 4.0 is the "em," whereas in Internet Explorer 5 it is the "px" (pixel). For consistent results, specify the dialogHeight and dialogWidth in pixels when designing modal dialog boxes.
dialogWidth: iWidth: Sets the width of the dialog window.
dialogLeft: iXPos: Sets the left position of the dialog window relative to the upper-left corner of the desktop.
dialogTop: iYPos: Sets the top position of the dialog window relative to the upper-left corner of the desktop.
center: {yes | no | 1 | 0 }: Specifies whether to center the dialog window within the desktop. The default is "yes." To override center, even though the default for center is "yes," you can specify either dialogLeft and/or dialogTop.
help: {yes | no | 1 | 0 }: Specifies whether the dialog window displays the context-sensitive Help icon. The default is "yes."
resizable: {yes | no | 1 | 0 } (Internet Explorer 5 and above): Specifies whether the dialog window has set dimensions. The default for both trusted and untrusted dialog windows is "no."
status: {yes | no | 1 | 0 } (Internet Explorer 5 and above): Specifies whether the dialog window displays a status bar. The default is "yes" for untrusted dialog windows and "no" for trusted dialog windows.

Object Detection

The showModalDialog() and showModelessDialog() methods aren't supported by all JavaScript-enabled browsers. Before we call one of these methods, we must make sure it is supported:

if (window.showModalDialog) {
  ...
}
if (window.showModelessDialog) {
  ...
}

You'll probably want to consider an alternative action if the user's browser doesn't support the desired method, by invoking our window.open() friend:

if (window.showModalDialog) {
  win = window.showModalDialog("mydialog.html", ...);
} else {
  win = window.open("mydialog.html", ...);
}

A Cross-Browser Modal Dialog

Take a look at the following definition (Navigator only):

<BODY onBlur="window.focus()">

If you use the above event handler in the <BODY> tag, the window holding the document remains focused until the user closes it. There are several differences between this Navigator-only technique and Internet Explorer's showModalDialog() method. First of all, the focused window isn't associated with a specific window (or document). That is, the user cannot bring up any other browser window, even if it isn't the window that opened the dialog window. In addition, the user can still bring up a different window for a moment, which is enough to close the opener window while the "modal" dialog is open.

Next: How to create a popup window

Produced by Yehuda Shiran and Tomer Shiran

Created: April 10, 2000
Revised: April 10, 2000

URL: https://www.webreference.com/js/tutorial1/dialog.html

Working with Windows: Dialog Boxes

Working with Windows

Dialog Boxes

Object Detection

A Cross-Browser Modal Dialog

Find a programming school near you