A dialog box is a special window that you create by using the showModalDialog method on the window object. Dialog boxes are useful for soliciting input from the user in a way that does not obscure the information in the current window. They are also useful for displaying important information that the user should act upon or acknowledge before proceeding.
The showModalDialog method is similar to the open method in that it takes the URL of an HTML document and displays the document in a new window. One of the main differences, however, is that the dialog box is modal, meaning it does not release the input focus until it is closed. This means the user cannot switch back to the window that created the dialog box until she closes the dialog box. However, this does not prevent the user from switching to other windows or applications.
You typically create dialog boxes in response to user input, such as clicking a button or choosing an item in a menu. The following example calls showModalDialog directly from the onclick attribute of a BUTTON element.
<button onclick="window.showModalDialog ( 'dialog.htm' )">Search</button>
The method in the example above creates a dialog box having the standard dialog box size and features, and loads the document dialog.htm into the new window.
You can load any valid HTML document into a dialog box, but most dialog documents contain one or more controls with which the user supplies input or directs an action. For example, the following document provides a text control for letting the user specify a string to search for and buttons to confirm or cancel the search. Notice that the string is returned to the main window by assigning it to returnValue.
<html>
<head>
<title>Search For</title>
<script language="JavaScript">
function doOK ( ) {
window.returnValue = window.document.all.MySearch.value;
window.close ( );
}
function doCancel ( ) {
window.returnValue = "";
window.close ( );
}
</script>
</head>
<body>
<p><b>Search For:</b> <input id=mysearch type=text>
<center>
<button onclick="doOK ( )">OK</button>
<button onclick="doCancel ( )">Cancel</button>
</center>
</body>
</html>
Show me
When the document above is displayed, the user can type a string into the text control ( identified by MySearch ) and click either the OK or Cancel button to carry out an action. Clicking OK calls the doOK function, which retrieves the text from the text control and assigns it to the returnValue property of the dialog box. Clicking Cancel calls doCancel, which assigns an empty string to this property. Both functions then call the close method to close the dialog box and return the input focus to the original window.
The returnValue property on the window object specifies the value to be returned by the showModalDialog method after the dialog box closes. Setting this property is one way a dialog box can return information to the original window. Assuming the document in the previous example is in a file named "search.htm", the following example can use the returned string to carry out a search.
function doSearch ( ) {
var str = showModalDialog ( "search.htm" );
if ( str == "" )
return; // user canceled search
else {
// search for the string
}
}
You can pass arguments to a dialog box by using the second parameter of showModalDialog. This parameter accepts any valid type, so an array can be passed just as easily as a discrete type.
var aCafeArgs = new Array ( "Tall", "Decaf", "Non-fat", "Mocha" );
var cResult = window.showModalDialog ( "barista.htm", aCafeArgs );
A dialog box can retrieve the arguments through the dialogArguments property of the window object. Passing arguments is a useful way for the original window to specify the initial values for the controls in the dialog box. For example, consider the dialog document in the search example. By scripting the onload event of the BODY element to call the following function, the dialog can set the initial search string to a value supplied by the original window.
function doInit ( ) {
if ( window.dialogArguments != null )
window.document.all.MySearch.value = window.dialogArguments;
}
.
.
.
<body onload="doInit ( )">
To set the initial search string to the words "Sample Text", the original window calls showModalDialog as in the following example:
var str = showModalDialog ( "search.htm", "Sample Text" );
A better way to make use of the dialog arguments for this document is to store the search string in a variable within the document of the original window, as in the following example.
var str = "";
function doSearch ( ) {
str = showModalDialog ( "search.htm", str );
if ( str == "" )
return; // user canceled search
else {
// search for the string
}
}
Storing the returned string in the global variable ensures that the previous search string is available whenever the user requests another search. Remember that stored values are discarded when a document is unloaded, so you cannot store the previous string with the dialog document. This also means that the stored string in the original window is discarded when that document is unloaded.
In addition to setting initial values, you can also set the input focus to a specific control in the dialog box by using the focus method. This ensures that when the dialog document is loaded, the user can begin entering input immediately without first moving the focus to an appropriate control. The input focus is typically set in the same function that sets initial values for the dialog box. To set the focus to the text control in the previous example, use the following:
window.document.all.MySearch.focus ( );
If the original window has more that one value to exchange with the dialog box, it can do this by passing an object to the dialog as an argument. For example, the following dialog document prompts the user with both a Match Case check box and a Search For string. To receive the user's settings for these, the original window passes an object that the dialog sets when the user clicks OK or Cancel.
<html>
<head>
<title>Search For</title>
<script language="JScript">
function doInit ( ) {
if ( window.dialogArguments != null ) {
window.document.all.MySearch.value = window.dialogArguments.str;
window.document.all.MatchCase.checked = window.dialogArguments.caseSensitive;
}
window.document.all.MySearch.focus ( );
window.returnValue = false;
}
function doOK ( ) {
window.returnValue = true;
if ( window.dialogArguments != null ) {
window.dialogArguments.str = window.document.all.MySearch.value;
window.dialogArguments.caseSensitive = window.document.all.MatchCase.checked;
}
window.close ( );
}
function doCancel ( ) {
window.returnValue = false;
window.close ( );
}
</script>
</head>
<body onload="doInit ( )">
<input id=matchcase type=checkbox><b>Match Case</b>
<p><b>Search For:</b> <input id=mysearch type=text>
<center>
<button onclick="doOK ( )">OK</button>
<button onclick="doCancel ( )">Cancel</button>
</center>
</body>
</html>
Show me
Be careful! Any document that uses this dialog document needs to properly declare and initialize the object. The following example declares the myDialog object and initializes the object before calling showModalDialog.
function myDialog ( ) {
var str;
var caseSensitive;
}
function doSearch ( ) {
myDialog.str = "";
myDialog.caseSensitive = false;
if ( showModalDialog ( "search.htm", myDialog ) == false )
return; // user canceled search
else {
// search for the string
}
}
An alternate way to pass multiple values between the original window and the dialog box is to concatenate those values into a single string, and leave it to the documents to parse the string and extract the values.
The appearance and size of a dialog box can be set from the third parameter of the showModalDialog method. The following example creates a dialog box that uses a default font size of 10 pixels and a dialog width and height of 10 ems.
window.showModalDialog ( "dialog.htm",null, "font-size:10px;dialogWidth:10em;dialogHeight:10em" )
As you can see in the example above, the third parameter takes a string, consisting of one or more settings separated by semicolons ( ; ). Each setting consists of a name and a value separated by a colon ( : ) or equal sign ( = ). The value depends on the ornament. If it is a number, it takes a units designator, such as px or em.
You use the dialogWidth and dialogHeight properties to set the initial width and height of the dialog box. Similarly, you can use dialogLeft and dialogTop to set the initial position of the dialog box relative to the upper-left corner of the desktop ( not the parent window ). If you don't want to calculate the left and top positions for the dialog box, you can center it in the desktop by using the center keyword.
Although the position, width, and height of a dialog box are typically set by the parent document, you can retrieve and change these settings from within the dialog box itself by using the dialogLeft, dialogTop, dialogWidth, and dialogHeight properties. Changing these settings is important, for example, if you want to expand the content of the dialog box to show additional options that the user can choose from.
You can set the default font, font size, weight, and style for text in the dialog box by using the font, font-size, font-weight, and font-style properties. These take the same values as the CSS attributes of the same name. The default settings apply only to text in the dialog box that does not already have explicit font settings.