Window.showModalDialog() (Method)

Display a modal dialog.

Availability:

JScript - 3.0
Internet Explorer - 4.0
Property/method value type:User defined
JavaScript syntax:IEmyWindow.showModalDialog(aURL, someArguments)
IEmyWindow.showModalDialog(aURL, someArguments, someFeatures)
IEshowModalDialog(aURL, someArguments)
IEshowModalDialog(aURL, someArguments, someFeatures)
Argument list:aURLA URL to load into the modal dialog
someArgumentsAggregated arguments to pass to the modal dialog
someFeaturesWindow adornment features

The MSIE browser supports a special window that behaves like a normal window, except that it does not permit any other action until it is dismissed.

To present a modal dialog, you call this method which does not return until the window is dismissed. When the window is dismissed, whatever the returnValue property of that window was set to will be returned as the result of this method call.

You must specify a URL to be loaded into the window and you can also pass arguments to it to control the behavior of any content with some scripts that get loaded with the page. It is that script code which will ultimately store something in the returnValue property of the window before calling window.close() to dismiss the window. The arguments are passed by aggregating them into an array or object which is then 'unpacked' inside the modal dialog's context.

This is only supported on MSIE but you can simulate most of its functionality quite easily in Netscape Navigator. Passing values in and out becomes somewhat tricky but you can accomplish that by passing property values via calls to scripts in other windows or by setting properties belonging to objects that you know will persist long enough for them to be retrieved. However, note that you may not be able to simulate the interlocking modality quite as easily.

A third optional argument can be specified in a similar way to the feature list of a window.open() method. You might put values such as this in the third argument to control the size of the new dialog:

"dialogWidth:5cm; dialogHeight:10cm; dialogTop:0cm; dialogLeft:0cm"

Note that they are a number and a measurement unit in the manner of the CSS positioning style controls. If you don't specify a measurement unit, then MSIE 4 assumes you are measuring in ems and MSIE 5 assumes pixels.

Here is a list of the features that can be applied to a modal dialog window as it is opened:

FeatureRangeDefaultDescription
center:yes, no, 1, 0, on, offyesControls dialog window centering within the desktop.
dialogHeight:height valuenoneSets the dialog window height
dialogHide:yes, no, 1, 0, on, offnoControls the dialog window visibility when printing or using print preview. This feature is only available when a dialog box is opened from a trusted application.
dialogLeft:left positionnoneSets the left edge coordinate of the dialog window relative to the upper-left corner of the desktop.
dialogTop:top positionnoneSets the top edge coordinate of the dialog window relative to the upper-left corner of the desktop.
dialogWidth:width valuenoneSets the dialog window width
edge:sunken, raisedraisedDefines the dialog window edge style
help:yes, no, 1, 0, on, offyesControls the context-sensitive Help icon.
resizable:yes, no, 1, 0, on, offnoControls the resize box.
scroll:yes, no, 1, 0, on, offyesDefines whether the dialog window has scrollbars.
status:yes, no, 1, 0, on, offVariesDefines whether the dialog window has a status bar. The default is yes for dialog windows that aren't trusted and no for trusted dialog windows.
unadorned:yes, no, 1, 0, on, offnoControls the border window chrome. This feature is only available when a dialog box is opened from a trusted application.

The result of this method call is the value stored in the returnValue property of the modal window before it is dismissed.

The example demonstrates how to pass some argument values in an array and how to return a value entered by the user.

Warnings:

Example code:

   <!-- Save this in demo.html -->
   <HTML>
   <HEAD>
   </HEAD>
   <BODY>
   <SCRIPT>
   myArray = new Array(100, 200, "XXX", "YYY");
   myReturnValue = showModalDialog("./page.html", myArray);
   alert("Value returned from window is "+myReturnValue);
   </SCRIPT>
   </BODY>
   </HTML>
   ---------------------------------------------------------------
   <!-- Save this in page.html in the same folder -->
   <HTML>
   <HEAD>
   </HEAD>
   <BODY>
   Hi there!!
   <HR>
   Input values are:<BR><BR>
   <SCRIPT>
   for(myEnum=0; myEnum<dialogArguments.length; myEnum++)
   {
      document.write(myEnum);
      document.write(" - ");
      document.write(dialogArguments[myEnum]);
      document.write("<BR>");
   }
   returnValue = prompt("What do you want to send back");
   </SCRIPT>
   </BODY>
   </HTML>

See also:Dialog boxes, Dialog object, Frame object, Window object, Window.dialogArguments, Window.returnValue, Window.setZOptions()