Dialog Windows

JavaScript recognizes two types of "dialog" windows. A modal dialog window remains on top of other windows until the user explicitly closes it. Until the window is closed, no access is possible to other open windows. A modeless dialog window remains on top of other windows; however, access is provided to underlying windows.

Modal Dialog Windows

A modal dialog window is a secondary window with the characteristic that it is always the top window until it is closed. Users cannot access the underlying window from which the modal dialog window was opened. Modal dialog windows force the user to respond to its contents, even if it means just closing the window. The operation of a modal dialog window is shown by the following button.

<input type="button" value="Show Modal"
  onclick='showModalDialog("Modal.htm","",
  "dialogWidth:400px; dialogHeight:225px; status:no; center:yes")'/>
Listing 7-11. Code to create a modal dialog window.

Modal dialog windows are created with the showModalDialog() method in the general format,

[var variable =] showModalDialog("url"[,arguments][,"window_settings]")
Figure 7-15. General format to create a modal dialog window.

where:

url location of the XHTML document to load into the modal dialog window.
arguments a string, usually, of values passed to a script on the modal dialog page. The script receives the string as property window.dialogArguments.
window_settings characteristics of the modal dialog window. Properties are set in style sheet fashion, property:value, with settings separated by semicolons. The follow properties can be set:

dialogWidth:npx - horizontal width of the window
dialogHeight:npx - vertical height of the window
dialogLeft:npx distance of window from left edge of screen
dialogTop:npx - distance of window from top edge of screen
center:yes|no - display window in middle of screen
status:yes|no - display window's status bar
edge:raised|sunken - style of the window border
help:yes|no - display a help icon in titlebar

If no properties are provided a default window is displayed.

Passing Arguments

There is no scripting relationship between a model dialog window and other windows. That is, one window cannot reference another window in a script. However, the opener window can pass data values to the modal dialog window, and the dialog window can return values to the opener window.

When a dialog window is opened, a string can be passed to it through the arguments parameter of the showModalDialog() method. This string value is received by a script on the modal dialog page through its window.dialogArguments property. In return, the dialog page can return a string value by setting its returnValue property. This property is accessible by the opener page by assigning the showModalDialog() statement to a variable that receives the returned value. It's not as confusing as it sounds.

The following button calls a function to open a modal dialog window. The script assigns the showModalDialog() method to variable ReturnedValue in order to received data passed back from the dialog page. When the window is opened, the dialog page is sent the string "Passed String" coded as the second parameter in the showModalDialog() method.

Opener page:

<script type="text/javascript">

function OpenModalDialog()
{
  var ReturnedValue = showModalDialog("Modal.htm","Passed String",
    "dialogWidth:400px; dialogHeight:225px; status:no; center:yes");
	
  alert("Modal Dialog returned '" + ReturnValued + "'");
}

</script>


<html>
<body>
<input type="button" value=" Open Modal Dialog" onclick="OpenModalDialog()"/>
</body>
</html>
Listing 7-12. Code to open a modal dialog window and pass a string value.

The modal dialog page contains a script to capture the passed value. Typically, the value is captured as a variable during the page's load event. In the following script, the passed value, window.dialogArguments, is captured as variable PassedString. This value is displayed on the page, and the script sets the window's returnValue property to "OK" in order to pass it to the opener page when the modal window is closed.

Modal dialog page: 
<script type="text/javascript">

function GetPassedValue()
{
  var PassedString = window.dialogArguments;
  document.getElementById("OutString").innerText = PassedString;
  returnValue = "OK";
}

</script>

<html>
<body onload="GetPassedValue()">

You sent me <span id="OutString"></span>.

</body>
</html>
Listing 7-13. Code for modal dialog window to receive a string value.

When the modal window is closed, the opener window has access to the returned value through variable ReturnedValue (since the open statement is assigned to it). In this script, the returned value is displayed in an alert() box. The following button demonstrates these operations.

Modeless Dialog Windows

Modeless dialog windows act like modal dialog windows—remaining on top of other windows until closed—except that users have access to underlying windows. A modeless dialog window is a good way to present help information, for example, remaining on top and in view while the user works in the underlying window.

Modal dialog windows are created with the showModelessDialog() method in the general format shown below.

[var variable =] showModelessDialog("url"[,arguments][,"window_settings]")
Figure 7-16. General format to create a modeless dialog window.

The same type of argument passing and window settings are available as for modal dialog windows.