Windows and Frames

13.5.1 The MimeType and Plugin Objects

As you probably noticed, Figure 13.2 shows that the Navigator object has properties other than those we have discussed so far. Many of these properties are incompatible extensions in Internet Explorer and are not discussed here. If you want to make use of the properties, be sure that you first use code like that in Example 13.3 to ensure that your code is running in Internet Explorer 4 or later. Two properties, mimeTypes and plugins, do bear further discussion, however. These properties are supported in Navigator 3 and later. In IE 4, the properties are defined for compatibility but are not truly supported: the arrays they refer to are always empty.

The navigator.mimeTypes[] property is an array of MimeType objects, each of which describes one MIME data format (text/html and image/gif, for example) that the web browser can display (either directly, with an external helper application, or with a plugin). The MimeType object itself contains properties that describe the data format.

The mimeTypes[] array is indexed numerically, but it is also an associative array, indexed by the name of the MIME type. Thus, you can easily check for support of a given data format on the browser:

// Check to see if the browser can display MPEG files.
var show_movie = (navigator.mimeTypes["video/mpeg"] != null);

The navigator.plugins[] property is an array of Plugin objects, each of which represents one plugin module that has been installed in the browser. The properties of the Plugin object provide various details about the plugin. The Plugin object also contains array elements, which are MimeType objects describing each of the data formats supported by that particular plugin. Note that this array is different than the navigator.mimeTypes[] array described earlier.

You can use the plugins[] property as an associative array, just as you can the mimeTypes[] property. This lets you check for the existence of a particular plugin without having to loop through the array numerically and check every element:

// Check to see if the browser has the Shockwave plugin installed.
var shocked = (navigator.plugins["Shockwave"] != null);

13.5.2 Navigator Methods

In addition to its properties, the Navigator object defines methods that provide further information about the browser. In JavaScript 1.1 and later, the javaEnabled() method returns true if the browser supports Java and if Java support is enabled; otherwise it returns false. Navigator 4 adds the preference() method, which allows signed scripts to query and set user preferences.

13.7.1 Opening Windows

You can open a new web browser window with the open() method of the Window object. This method takes four optional arguments and returns a Window object that represents the newly opened window. The first argument to open() is the URL of the document to display in the new window. If this argument is omitted (or is null or the empty string), the window will be empty.

The second argument to open() is the name of the window. As we'll discuss later in the chapter, this name can be useful as the value of the TARGET attribute of a <FORM> or <A> tag. If you specify the name of a window that already exists, open() simply uses that existing window rather than opening a new one.

The third optional argument to open() is a list of features that specify the window size and GUI decorations. If you omit this argument, the new window is given a default size and has a full set of standard features: a menubar, status line, toolbar, and so on. On the other hand, if you specify this argument, you can explicitly specify the size of the window and the set of features it includes. For example, to open a small resizeable browser window with a status bar but no menubar, toolbar, or locationbar, you could use the following line of JavaScript:

var w = window.open("smallwin.php", "smallwin", 
                    "width=400,height=350,status=yes,resizeable=yes");

The fourth argument to open() is useful only when the second argument names an already existing window. This fourth argument is a boolean value that specifies whether the URL specified as the first argument should replace the current entry in the window's browsing history (true) or create a new entry in the window's browsing history (false), which is the default behavior.

The return value of the open() method is the Window object that represents the newly created window. You can use this Window object in your JavaScript code to refer to the new window, just as you use the implicit Window object window to refer to the window within which your code is running. But what about the reverse situation? What if JavaScript code in the new window wants to refer back to the window that opened it? In JavaScript 1.1 and later, the opener property of a window refers to the window from which it was opened. If the window was created by the user instead of by JavaScript code, the opener property is null.

An important point about the open() method is that it is almost always invoked as window.open(), even though window refers to the global object and should therefore be entirely optional. The reason that window is specified explicitly is that the Document object also has an open() method, so specifying window.open() helps to make it very clear what we are trying to do. This is not only a helpful habit; it is required in some circumstances, because, as we'll learn in Chapter 15, event handlers execute in the scope of the object that defines them. When the event handler of an HTML button executes, for example, the scope chain includes the Button object, the Form object that contains the button, the Document object that contains the form, and, finally, the Window object that contains the document. Thus, if such an event handler refers merely to the open() method, this identifier ends up being resolved in the Document object, and the event handler opens a new document rather than opening a new window!

We'll see an example of the open() method in Example 13.4.

13.7.2 Closing Windows

Just as the open() method opens a new window, the close() method closes one. If we've created a Window object w, we can close it with:

w.close();

window.close();

You can only automatically close windows that your own JavaScript code has created. If you attempt to close any other window, the user is presented with a dialog box that asks him to confirm (or cancel) that request to close the window. This prevents inconsiderate web sites from closing your main browsing window.

In JavaScript 1.1 and later, a Window object continues to exist after the window it represents has been closed. You should not attempt to use any of its properties or methods, however, except to test the closed property. This property is true if the window has been closed. Remember that the user can close any window at any time, so to avoid errors, it is a good idea to check periodically that the window you are trying to use is still open. We'll see an example of doing just this in Example 13.4.

13.7.3 Window Geometry

In JavaScript 1.2, moveTo() moves the upper-left corner of the window to the specified coordinates. Similarly, moveBy() moves the window a specified number of pixels left or right and up or down. resizeTo() and resizeBy() resize the window by an absolute or relative amount; they are also new in JavaScript 1.2. Note that in Navigator 4, there are some security restrictions on how you can move and resize windows. We'll see more about this in Chapter 21, JavaScript Security, but basically, you are not allowed to move a window off screen or to make it too small. This is so that you can't create a hidden window that the user might forget about.

13.7.4 Keyboard Focus

The focus() and blur() methods also provide high-level control over a window. Calling focus() requests that the system give keyboard focus to the window and blur() relinquishes keyboard focus. These methods are defined in JavaScript 1.1 and later.

13.7.5 Scrolling

Window also contains some methods that control the scrollbars of the window, rather than the window itself. scrollBy() scrolls the document displayed in the window by a specified number of pixels left or right and up or down. scrollTo() scrolls the document to an absolute position. It moves the document so that the specified document coordinates are displayed in the upper-left corner of the document area within the window. These two methods are defined in JavaScript 1.2. In JavaScript 1.1, the scroll() method performs the same function as the JavaScript 1.2 scrollTo() method. scrollTo() is the preferred method, but scroll() remains for backwards compatibility.

In JavaScript 1.2, the elements of the anchors[] array of the Document object are Anchor objects. Each Anchor object has x and y properties that specify the location of the anchor within the document. Thus, you can use these values in conjunction with the scrollTo() method to scroll to known locations within the document.

13.7.6 Window Methods Example

Example 13.4 demonstrates the Window open(), close(), and moveTo() methods and several other window programming techniques that we've discussed. It creates a new window and then uses setInterval() to repeatedly call a function that moves it around the screen. It determines the size of the screen with the Screen object and then uses this information to make the window "bounce" when it reaches any edge of the screen.

<script>
// Here are the initial values for our animation. 
var x = 0, y = 0, w=200, h=200;  // Window position and size
var dx = 5, dy = 5;              // Window velocity   
var interval = 100;              // Milliseconds between updates

// Create the window that we're going to move around.
// The javascript: URL is simply a way to display a short document.
// The final argument specifies the window size.
var win = window.open('javascript:"<H1>BOUNCE!</H1>"', "", 
		      "width=" + w + ",height=" + h);

// Set the initial position of the window.
win.moveTo(x,y);

// Use setInterval() to call the bounce() method every interval 
// milliseconds. Store the return value so that we can stop the
// animation by passing it to clearInterval().
var intervalID  = window.setInterval("bounce()", interval);

// This function moves the window by (dx, dy) every interval ms.
// It bounces whenever the window reaches the edge of the screen.
function bounce() {
    // If the user closed the window, stop the animation.
    if (win.closed) {
        clearInterval(intervalID);
        return;
    }

    // Have we reached the right or left edge? 
    if ((x+dx > (screen.availWidth - w)) || (x+dx < 0)) dx = -dx;

    // Have we reached the bottom or top edge?
    if ((y+dy > (screen.availHeight - h)) || (y+dy < 0)) dy = -dy;

    // Update the current position of the window.
    x += dx;
    y += dy;

    // Finally, move the window to the new position.
    win.moveTo(x,y);
}
</script>

<!-- Clicking this button stops the animation! -->
<FORM>
<INPUT TYPE=button VALUE="Stop" 
       onClick="clearInterval(intervalID); win.close();">
</FORM>

13.10.1 Relationships Between Frames

We've already seen that the open() method of the Window object returns a new Window object representing the newly created window. We've also seen that this new window has an opener property that refers back to the original window. In this way, the two windows can refer to each other, and each can read properties and invoke methods of the other. The same thing is possible with frames. Any frame in a window can refer to any other frame through the use of the frames[], parent, and top properties of the Window object.

Every window has a frames property. This property refers to an array of Window objects, each of which represents a frame contained within the window. (If a window does not have any frames, the frames[] array is empty and frames.length is zero.) Thus, a window (or frame) can refer to its first subframe as frames[0], its second subframe as frames[1], and so on. Similarly, JavaScript code running in a window can refer to the third subframe of its second frame like this:

frames[1].frames[2]

Every window also has a parent property, which refers to the Window object in which it is contained. Thus, the first frame within a window might refer to its sibling frame (the second frame within the window) like this:

parent.frames[1]

parent == self;  // For any top-level window

If a frame is contained within another frame that is contained within a top-level window, that frame can refer to the top-level window as parent.parent. The top property is a general-case shortcut, however: no matter how deeply a frame is nested, its top property refers to the top-level containing window. If a Window object represents a top-level window, top simply refers to the window itself. For frames that are direct children of a top-level window, the top property is the same as the parent property.

Figure 13.4 illustrates these relationships between frames and shows how code running in any one frame can refer to any other frame through the use of the frames, parent, and top properties. With this understanding of the relationships between windows, you may want to revisit Example 13.6, paying particular attention this time to the way the second frame refers to the history and location properties of the first.

Figure 13.4: Relationships between frames

13.10.2 Window and Frame Names

The second, optional argument to the open() method discussed earlier is a name for the newly created window. When you create a frame with the HTML <FRAME> tag, you can specify a name with the NAME attribute. An important reason to specify names for windows and frames is that those names can be used as the value of the TARGET attribute of the <A>, <MAP>, and <FORM> tags. This tells the browser where you want the results of activating a link, clicking on an image map, or submitting a form to be displayed.

For example, if you have two windows, one named table_of_contents and the other named mainwin, you might have HTML like the following in the table_of_contents window:

<A HREF="chapter01.php" TARGET="mainwin">
Chapter 1, Introduction
</A>

The TARGET and NAME attributes are part of HTML and operate without the intervention of JavaScript, but there are also JavaScript-related reasons to give names to your frames. We've seen that every Window object has a frames[] array that contains references to each of its frames. This array contains all frames in a window (or frame) whether or not they have names. If a frame is given a name, however, a reference to that frame is also stored in a new property of the parent Window object. The name of that new property is the same as the name of the frame. Therefore, you might create a frame with HTML like this:

<FRAME NAME="table_of_contents" SRC="toc.php">

parent.table_of_contents

parent.frames[1]

The name property of any Window object contains the name of that window. In JavaScript 1.0, this property is read-only. In JavaScript 1.1, however, you can set this property, thereby changing the name of a window or a frame. One common reason to do this is to set the name of the initial browser window. When Navigator starts up, the initial window has no name, so it cannot be used with the TARGET attribute. If you set the name property of the window, however, you can then use that name in TARGET attributes.

13.10.3 JavaScript in Interacting Windows

Recall what we learned in Chapter 12: the Window object serves as the global object for client-side JavaScript code, and the window serves as the execution context for all JavaScript code it contains. This holds true for frames as well: every frame is an independent JavaScript execution context. Because every Window object is its own global object, each window defines its own namespace and its own set of "global" variables. When viewed from the perspective of multiple frames or windows, global variables do not seem all that global, after all!

Although each window and frame defines an independent JavaScript execution context, this does not mean that JavaScript code running in one window is isolated from code running in other windows. Code running in one frame has a different Window object at the top of its scope chain than code running in another frame. However, the code from both frames is executed by the same JavaScript interpreter, in the same JavaScript environment. As we've seen, one frame can refer to any other frame by using the frames, parent, and top properties. So, although JavaScript code in different frames is executed with different scope chains, this does not prevent the code in one frame from referring to, and using, the variables and functions defined by code in another frame.

For example, suppose code in frame A defines a variable i:

var i = 3;

window.i
self.i

parent.frames[0].i = 4;

Recall that the function keyword that defines functions declares a variable just like the var keyword does. If JavaScript code in frame A declares a function f, that function is defined only within frame A. Code in frame A can invoke f like this:

f();

parent.frames[0].f();

var f = parent.frames[0].f;

When you share functions between frames or windows like this, it is very important to keep the rules of lexical scoping in mind. A function is executed in the scope in which it was defined, not in the scope from which it is invoked. Thus, to continue with the example above, if the function f refers to global variables, these variables are looked up as properties of frame A, even when the function is invoked from frame B.[1]

[1] If you have read Chapter 11, Further Topics in JavaScript, you can probably think of a way to use the Closure() constructor of Navigator 4 to define a version of the function f that executes in the scope of frame B.

If you don't pay careful attention to this, you can end up with programs that behave in unexpected and confusing ways. For example, suppose you define the following function in the <HEAD> section of a multiframe document, with the idea that it will help with debugging:

function debug(msg) {
    alert("Debugging message from frame: " + name + "\n" + msg);
}

Remember that constructors are also functions, so when you define a class of objects with a constructor function and an associated prototype object, that class is only defined for a single window. Recall the Complex class we defined in Chapter 8, Objects, and consider the following multiframed HTML document:

<HEAD>
<SCRIPT SRC="Complex.js"></SCRIPT>
</HEAD>
<FRAMESET ROWS="50%,50%">
  <FRAME NAME="frame1" SRC="frame1.php">
  <FRAME NAME="frame2" SRC="frame2.php">
</FRAMESET>

var c = new Complex(1,2);  // Won't work from either frame

var c = new top.Complex(3,4);

var Complex = top.Complex;
var c = new Complex(1,2);

Unlike user-defined constructors, predefined constructors are automatically pre-defined in all windows. Note, however, that each window has an independent copy of the constructor and an independent copy of the constructor's prototype object. For example, each window has its own copy of the String() constructor and the String.prototype object. So, if you write a new method for manipulating JavaScript strings and make it a method of the String class by assigning it to the String.prototype object in the current window, all strings in that window can use the new method. However, the new method is not accessible to strings defined in other windows. Note that it does not matter which window holds a reference to the string, only which window the string was actually created in.

13.10.4 Example: Colored Frames

Example 13.7, a frame set that defines a grid of nine frames, demonstrates some of the techniques we've been discussing in this chapter. The <HEAD> section of the frame set includes a <SCRIPT> that defines a JavaScript function named setcolor(). The onLoad event handler of the <FRAMESET> tag invokes setcolor() once for each of the nine frames.

setcolor() is passed a Window object as its argument. It generates a random color and uses it as the new value of the bgColor property of the Document object. (We'll see more about the Document object and its properties in Chapter 14.) Finally, setcolor() uses the setTimeout() method to schedule itself to be called again in one second. This call to setTimeout() is the most interesting part of the example. Notice especially how it uses the parent and name properties of Window objects.

<HEAD>
<TITLE>Colored Frames</TITLE>
<SCRIPT>
function setcolor(w) {
    // Generate a random color.
    var r = (Math.random() * 256).toString(16);
    var g = (Math.random() * 256).toString(16);
    var b = (Math.random() * 256).toString(16);
    var colorString = "#" + r + g + b;

    // Set the frame background to the random color.
    w.document.bgColor = colorString;

    // Schedule another call to this method in one second.
    // Since we call the setTimeout() method of the frame, the string
    // will be executed in that context, so we must prefix properties
    // of the top-level window with "parent."
    w.setTimeout('parent.setcolor(parent.' + w.name + ')', 1000);

    // We could also have done the same thing more simply like this.
    // setTimeout('setcolor(' + w.name + ')', 1000);
}
</SCRIPT>
</HEAD>
<FRAMESET rows="33%,33%,34%" cols="33%,33%,34%"
  onLoad="for(var i = 0; i < 9; i++) setcolor(frames[i]);">
<FRAME NAME="f1" SRC="javascript:''"><FRAME NAME="f2" SRC="javascript:''">
<FRAME NAME="f3" SRC="javascript:''"><FRAME NAME="f4" SRC="javascript:''">
<FRAME NAME="f5" SRC="javascript:''"><FRAME NAME="f6" SRC="javascript:''">
<FRAME NAME="f7" SRC="javascript:''"><FRAME NAME="f8" SRC="javascript:''">
<FRAME NAME="f9" SRC="javascript:''">
</FRAMESET>