DHTML Tutorial

6.8 Using Internet Explorer Modal/Modeless Windows

NN n/a, IE 4

6.8.1 Problem

You want to stop script processing while a modal dialog window appears, and then capture user-entered values from the dialog window to continue processing.

6.8.2 Solution

Internet Explorer 4 and later (both Windows and Macintosh versions) provide a window object method that displays a true modal dialog window (preventing user access to the main window until the dialog window closes). IE 5 or later for Windows provides an additional choice that creates a modeless window, which always stays in front of the main window, but allows access to the main window's user interface elements. The methods are called window.showModalDialog( ) and window.showModelessDialog( ), respectively.

To use either method, begin by assembling the data or object references you wish to pass to the dialog window (if any) as a JavaScript object (of any data type) in a variable. We use dialogArgs here. Find the place in your script where you need to query the user for input, and then invoke the method:

var dialogAnswer = window.showModalDialog("dialog.html", dialogArgs,
    "dialogWidth:300px; dialogHeight:201px; center:yes");

Scripts in the document loaded into the dialog window can access the passed arguments by reading the window.dialogArguments property. To get values back to the main window's script from a modal dialog, assign those values (again, of any JavaScript data type) to the window.returnValue property of the dialog window's document. When the user closes the dialog window, the returned value is assigned to the variable at the left side of the expression (dialogAnswer in the preceding example).

6.8.3 Discussion

IE modal dialog windows do not maintain the same kind of live connection between main and dialog window as you use with full windows created via window.open( ). But the chord between main and dialog windows isn't entirely broken, either.

For example, a script in the main window can pass a reference to one of the main document's element objects to the showModalDialog( ) method; a script in the dialog window can then use the passed reference as a way to inspect a property of that object. Here is a simple example, starting with the main window that passes a reference to a form element to the modal dialog window:

<html>
<head>
<title>Launch a Modal Dialog</title>
<script type="text/javascript">
function openDialog(form) {
    var result = window.showModalDialog("dialogDoc.html", form, 
        "dialogWidth:300px; dialogHeight:201px; center:yes");
}
</script>
</head>
<body>
<form name="sample" action="#" onsubmit="return false">
Enter your name for the dialog box:<input name="yourName" type="text" />
<input type="button" value="Send to Dialog" onclick="openDialog(this.form)" />
</form>
</body>
</html>

The document in the dialog window can read the value of the main window's text box as needed:

<html>
<head>
<title>Modal Dialog</title>
</head>
<body>
<script type="text/javascript">
document.write("Greetings from " + window.dialogArguments.yourName.value + "!");
</script>
</body>
</html>

A modeless dialog window behaves slightly differently from a scripting point of view. Most important, main document script processing does not stop when the modeless window appears. This is logical because a modeless window is intended to allow user interaction in both windows, while the dialog window simply stays in front of the main window. Second, the value returned by the showModelessDialog( ) method is a reference to the modeless dialog window. This allows scripts in the main window to communicate with the modeless dialog after it is created.

It's not uncommon for a call that invokes showModelessDialog( ) to pass either a reference to the main window or a reference to a main window function that needs to be invoked from the dialog window while it is still open (similar to the notion of an Apply button in many Windows system dialog boxes). Passing the main window reference looks like the following:

var dialogWind = window.showModelessDialog("myModeless.html", window, 
    "dialogWidth:300px; dialogHeight:201px; center:yes");

A script in the dialog window's document can then use the value of window.dialogArguments as a starting point to any global variable, function, or element object in the main window's context:

var mainWind = window.dialogArguments;
mainWind.document.body.style.backgroundColor = "lightyellow";

The window.returnValue property is not used in the modeless dialog. Communicate back to the main window directly. In fact, you can invoke main document functions from the modeless window. One way is to use the window reference passed to the dialogArguments property:

# in main window script
window.showModelessDialog("myModeless.html", window, "...");
   
# in dialog window script
var mainWind = window.dialogArguments;
mainWind.myFunction( );

Or pass a reference to the main document function:

# in main window script
window.showModelessDialog("myModeless.html", myFunction, "...");
   
# in dialog window script
var mainFunc = window.dialogArguments;
mainFunc( );

When you open either type of dialog window, the optional third parameter is a comma-delimited string of properties for the window. The syntax for this string is reminiscent of CSS name:property formatting, as shown in the previous examples. Table 6-2 lists the properties you can use and a description of their values.

Table 6-2. Properties for showModalDialog( ) and showModelessDialog( )

Property

Value

Default

Description

center

yes | no | 1 | 0 | on | off

yes

Center the dialog

dialogHeight

Length/units

n/a

Outer height of dialog (must be >200 for IE/Mac)

dialogLeft

Integer

n/a

Left pixel offset (overrides center)

dialogTop

Integer

n/a

Top pixel offset (overrides center)

dialogWidth

Length/units

n/a

Outer width of dialog (must be >200 for IE/Mac)

edge

raised | sunken

raised

Transition style between border and content area

help

yes | no | 1 | 0 | on | off

yes

Display help icon in titlebar

resizable

yes | no | 1 | 0 | on | off

no

Dialog is resizable

status

yes | no | 1 | 0 | on | off

yes

Display status bar

As with any potentially intrusive user interface element, don't overuse the modal or modeless window.

6.8.4 See Also

Recipe 6.9 for a way to produce a modal window for IE and NN browsers with a subwindow; Recipe 6.10 for a layer-based modal window simulator.

Main Page

→