The FRAME Element | Inside JavaScript

The <FRAME> Element

Like the <FRAMESET> element, the <FRAME> element, which you use to create individual frames , shares JavaScript's core HTML properties, methods , and events that we covered in Chapters 5 and 6. And like the <FRAMESET> element, the <FRAME> element also has some additional properties beyond the core ones, and you can see them in overview in Table 7.6, and in detail in Table 7.7. We'll see methods and events for this element in the next chapter.

Table 7.6. Overview of the Properties of the <FRAME> Element (See Chapter 5 and 6 for the JavaScript core HTML properties, methods, and events that also apply to this element.)

Properties
`allowTransparency`	`borderColor`	`contentDocument`
`contentWindow`	`frameBorder`	`height`
`longDesc`	`marginHeight`	`marginWidth`
`noResize`	`scrolling`	`src`
`width`

Table 7.7. The Properties of the <FRAME> Element (See Chapter 5 and 6 for the JavaScript core HTML properties, methods, and events that also apply to this element.)

Property	NS2	NS6	IE4	IE5	IE5.5	IE6
`allowTransparency`					x	x
	Read/write
	Specifies whether a frame can be transparent. When the property is set to false, the `backgroundColor` style property of the frame can only be that of the window. When the property is set to true, the `backgroundColor` property of the frame can be set to any value, including the default value of `transparent` .
`borderColor`			x	x	x	x
	Read/write
	Holds the color of the frame's border (the `BORDERCOLOR` attribute). Set to a color the browser can recognize (color triplet or predefined color).
`contentDocument`		x
	Read-only
	Holds the `document` object that corresponds to the content of the frame.
`contentWindow`					x	x
	Read-only
	Retrieves the `window` object of the specified frame.
`frameBorder`			x	x	x	x
	Read/write
	Specifies the value of the `FRAMEBORDER` attribute. May be set to "yes," "no," 1 (means yes), or 0 (means no).
`height`			x	x	x	x
	Read/write
	Holds the height of the frame, in pixels.
`longDesc`		x				x
	Read/write
	The property corresponds to the `LONGDESC` attribute, and holds the URL of a document with a long description of the frame.
`marginHeight`		x	x	x	x	x
	Read/write
	Holds the height of the margin between a frame's content and its frame, in pixels.
`marginWidth`		x	x	x	x	x
	Read/write
	Holds the width of the margin between a frame's content and its frame, in pixels.
`noResize`		x	x	x	x	x
	Read/write
	Set to false to allow the user to resize frames, true otherwise . Corresponds to the `NORESIZE` attribute.
`scrolling`		x	x	x	x	x
	Read/write
	Indicates whether the frame can be scrolled (and displays scrollbars if appropriate). May be set to "yes," "no," 1 (means yes), or 0 (means no).
`src`		x	x	x	x	x
	Read/write
	Enables you to set or read the `SRC` attribute of a frame, which sets the URL of the source document (as with images in the `<IMG>` element). Set to an URL.
`width`			x	x	x	x
	Read/write
	Holds the width of the frame, in pixels.

As you can see in Table 7.7, you have a lot of control over what happens in a frame using JavaScript. Here's one thing to note:You can use the src property to set the source URL for the frame's document, but this JavaScript property is still relatively new, and it's probably a better idea to use the location.href property for compatibility with old browsers.

Using Frame Properties

When you're working with frames, it's important to know your way aroundwhen you're in a <FRAMESET> window, for example, how do you access the child frames using JavaScript? When you're in a frame, how do you access the parent <FRAMESET> window? Here are the window object properties that enable you to move from frame to parent and back again:

frames . This property holds an array of the frames displayed in the window.
name . This property holds a name for a window. (There is no default value for this propertyit does not correspond to the <TITLE> element in <HEAD> sections.)
parent . The parent window of the current windowthis property is great for finding the <FRAMESET> that contains the current frame.
self . Refers to the current window.
top . This property holds the topmost window displayed. This is a good property if you have nested frames and don't want to work back through multiple parent propertiesyou can go right to the topmost window (which has the <FRAMESET> element that contains all the rest of the frames and their children) with this property.

If you're in one frame, for example, how do you refer to the document in another frame? You can use syntax like this: parent.frames[2].document . What about reading the name of the topmost window? You can use top.name . How about the value of a text field in a child frame? You can use syntax like frames[1].document.form1.text1.value . Here's an example that takes a look at the properties in the preceding list in a browser (note that I'm explicitly setting the name property of the top window hereotherwise, the name property of that window would be empty):

(Listing 07-11.html on the web site)

 <HTML>      <HEAD>          <TITLE>Frame Properties</TITLE>          <SCRIPT LANGUAGE="JavaScript">              <!--  self.name = "Top Dog"  // -->           </SCRIPT>      </HEAD>      <FRAMESET COLS="50%, 50%">          <FRAME NAME="frame1" SRC="07-12.html">          <FRAME NAME="frame2" SRC="07-12.html">      </FRAMESET>  </HTML>

(Listing 07-12.html on the web site)

 <HTML>      <HEAD>          <TITLE>Frame</TITLE>      </HEAD>      <BODY>          <H1>Frame Properties</H1>          <SCRIPT LANGUAGE="JavaScript">              <!--  document.write(   "window.name: " + window.name + "<BR>" +   "parent.frames.length: " + parent.frames.length + "<BR>" +   "parent.frames[0].name: " + parent.frames[0].name + "<BR>" +   "parent.frames[1].name: " + parent.frames[1].name + "<BR>" +   "window.name: " + window.name + "<BR>" +   "self.name: " + self.name + "<BR>" +   "self.document.title: " + self.document.title +   "parent.name: " + parent.name + "<BR>" +   "top.name: " + top.name + "<BR>" +   "parent.document.title: " + parent.document.title + "<BR>"   )  // -->          </SCRIPT>      </BODY>  </HTML>

You can see the results in Figure 7.9, showing the properties that let you get from frame to frame.

Figure 7.9. Looking at frame properties in the Netscape Navigator.

graphics/07fig09.gif

Insisting on Frames

Here's a useful thing to do with frames in JavaScriptif you've designed a window to be displayed only as a frame, you can make sure the user doesn't sneakily view it without frames, using code like this:

 <HTML>      <HEAD>          <TITLE>Welcome to my frame!</TITLE>          <SCRIPT LANGUAGE="JavaScript">              <!--  if(self == top){   top.location.href="frames.html"  }           // -->          </SCRIPT>      </HEAD>      <BODY>          <H1>Welcome to my frame!</H1>      </BODY>  </HTML>

Avoiding Framing

Conversely, you can make sure a document is not viewed in a frame (as when someone jumps to your site from a site that uses frames)here's how that might look in code:

 <HTML>      <HEAD>          <TITLE>Welcome to my page!</TITLE>          <SCRIPT LANGUAGE="JavaScript">              <!--  if(self != top){   top.location.href = self.location.href   }  // -->          </SCRIPT>      </HEAD>      <BODY>          <H1>Welcome to my page!</H1>      </BODY>  </HTML>

Creating Frames in JavaScript: JavaScript URLs

The document you load into the SRC attribute of a <FRAME> element doesn't have to be an actual HTML document. For example, you can use an URL built in to browsers "about:blank" to display a blank page:

 <HTML>      <HEAD>          <TITLE>Frame Properties</TITLE>      </HEAD>      <FRAMESET COLS="50%, 50%">          <FRAME NAME="frame1" SRC="frame1.html">  <FRAME NAME="frame2" SRC="about:blank">  </FRAMESET>  </HTML>

You also can create a document to display in a frame using a JavaScript URL . A JavaScript URL is actually a JavaScript function that the browser treats as a URLyou just preface the function name with "javascript:" . When the browser jumps to that URL, it just runs the JavaScript function. If you want to create a frame document using a JavaScript function, you just return the HTML from the function you want in the document.

Tip

We'll see more on JavaScript URLs in Chapter 14, "Working with Links, Lists, and Tables."

Here's an examplein this case, I'm using a JavaScript function I'll name filler to create a new frame with an <H1> header in it that displays the text A New Frame :

(Listing 07-13.html on the web site)

 <HTML>      <HEAD>          <TITLE>Frame Properties</TITLE>          <SCRIPT LANGUAGE="JavaScript">              <!--             self.name = "Top Dog"  function filler()   {   return "<HTML><HEAD><TITLE>Frame</TITLE></HEAD>" +   "<BODY><H1>A New Frame</H1></BODY></HTML>"   }  // -->          </SCRIPT>      </HEAD>      <FRAMESET COLS="50%, 50%">          <FRAME NAME="frame1" SRC="07-12.html">  <FRAME NAME="frame2" SRC="javascript:parent.filler()">  </FRAMESET>  </HTML>

You can see the results in Figure 7.10, where we're creating the frame on the right in JavaScript. Pretty cool.

Figure 7.10. Creating a frame in JavaScript.

graphics/07fig10.gif

Tip

Note that you also can use the document.write method to rewrite a frame's contents on-the-fly .