frame

NN 6 IE 4 DOM 1

The frame object reflects the frame element, which can only be generated inside a frameset element. Be sure to distinguish the difference between the frame element object (described here) and the window object that a frame makes possible. Properties and methods of a frame element object tend to reflect the aspects associated with the HTML element and its attributes. The content of the frame is a window (a view in the W3C DOM terminology), which has been scriptable from the beginning, and contains a document. Reference a frame element object via its ID, even if you assign the same identifier to a frame element's id and name attributes. For example, from a script residing in one frame's document, reach the frame element object via:

parent.document.getElementById("TOCFrame")

But to reach the same frame in its capacity as a window (and thus access its scripts and document), the reference from the same script would be either of the following:

parent.TOCFrame
parent.frames["TOCFrame"]

If a script is processing a reference to the frame element object, you can jump the fence between the element object and its content via the contentDocument or contentWindow properties described below.

Be aware that references to frame objects shown in this section may not work properly in the Windows 95 version of Internet Explorer 4. Also, the windowRef placeholder may be filled with parent or top if the reference is in a script contained by a child frame.

HTML Equivalent

<frame>

Object Model Reference

[windowRef.]document.getElementById("frameID")

Object-Specific Properties

allowTransparency	borderColor	contentDocument	contentWindow
dataFld	dataSrc	frameBorder	height
longDesc	marginHeight	marginWidth	name
noResize	scrolling	src	width

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

allowTransparency	NN n/a IE 6 DOM n/a
	Read/Write
Specifies whether the frame background can be transparent. Because an underlying frameset does not have a background color or image, this property is not helpful for a frame. It does apply, however, to the related iframe element object.

Value
Boolean value: true \| false.

Default
false

borderColor	NN n/a IE 4 DOM n/a
	Read/Write
Color of the frame's border. Each browser and operating system may resolve conflicts between different colored borders differently, so test any changes your scripts make to the color of individual frame borders.

Example

parent.document.getElementById("myFrame").borderColor = "salmon";

Value
A hexadecimal triplet or plain-language color name. A setting of empty is interpreted as "#000000" (black). See Appendix A for acceptable plain-language color names.

Default
Varies with operating system.

contentDocument	NN 6 IE n/a DOM 2
	Read-only
Returns a reference to the document object loaded into the frame element object. Through that document object, you can access one of the document's elements via the getElementById( ) method, or access the containing window object via the document's defaultView property. For IE/Windows, use the contentWindow property to jump from frame element object to its content.

Example

var frameElem = parent.document.getElementById("myFrame"); var doc = frameElem.contentDocument;

Value
Reference to a document node.

Default
Current document node.

contentWindow	NN 7 IE 5.5(Win) DOM n/a
	Read-only
Returns a reference to the window object generated by the frame element. Through that window object, you can access the document object and then any one of the document's elements. For Netscape 6, use the contentDocument property to jump from frame element object to its content. But if you are trying to reach script variables or functions in the frame, the contentWindow (or W3C DOM-friendly and Netscape 6-compatible contentDocument.defaultView) provides access to the script context.

Example

var frameElem = parent.document.getElementById("myFrame"); var win = frameElem.contentWindow;

Value
Reference to a window node.

Default
Current window node.

dataFld	NN n/a IE 4 DOM n/a
	Read/Write
Used with IE data binding to associate a remote data source column name to the frame's src attribute. A datasrc attribute must also be set for the element. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source. Works only with text file data sources in IE 5/Mac.

Example

parent.document.getElementById("myFrame").dataFld = "srcURL";

Value
Case-sensitive identifier of the data source column.

Default
None.

height, width	NN n/a IE 4 DOM n/a
	Read-only
Return the height and width in pixels of the frame. Dimensions include frame chrome (scrollbars). Adjust a frame's size via the frameset object's rows or cols properties.

Example

var frHeight = parent.document.getElementById("myFrame").height;

Value
Integer.

Default
Current height and width.

longDesc	NN 6 IE 5(Mac)/6(Win) DOM 1
	Read/Write
Reflects the longDesc attribute of the frame element. Version 6 browsers provide no significant functionality for this attribute or property.

Value
URL String.

Default
Empty string.

marginHeight, marginWidth	NN 6 IE 4 DOM 1
	Read/Write
Indicate the number of pixels between the inner edge of a frame and the content rendered inside the frame. The marginHeight property controls space along the top and (when scrolled) bottom edges of a frame; the marginWidth attribute controls space on the left and right edges of a frame.

Without any prompting, browsers automatically insert a small margin inside a frame (generally between 8 and 14 pixels depending on browser and operating system). But if you attempt to override the default behavior, be aware that setting any one of these two attributes causes the value of the other to go to zero. Therefore, unless you want the content to be absolutely flush with various frame edges, you need to assign values to both attributes.

Example

parent.document.getElementById("myFrame").marginHeight = 14; parent.document.getElementById("myFrame").marginWidth = 5;

Value
Positive integer value or zero.

Default
Varies with browser and operating system.

src	NN 6 IE 4 DOM 1
	Read/Write
Provides the URL of the external content file loaded into the frame. To change the content, assign a new URL to the property. For cross-platform applications, you can also set the location.href property of the frame to load a different document into the frame using window-related references (parent.frameName.location.href = "newDoc.html").

Example

parent.document.getElementById("myFrame").src = "images/altNavBar.jpg";

Value
Complete or relative URL as a string.

Default
None.

frameBorder	NN 6 IE 4 DOM 1
	Read/Write
Controls whether an individual frame within a frameset displays a border. Controlling individual frame borders appears to be a problem for most browsers in most operating system versions. Turning off the border of one frame may have no effect if all adjacent frames have their borders on. Feel free to experiment with the effects of turning some borders on and some borders off, but be sure to test the final effect on all browsers and operating systems used by your audience. Rely more comfortably on the frameborder attribute or frameBorder property of the entire frameset.

Example

parent.document.getElementById("frame2").frameBorder = "no";

Value
String values of 1 (on) and 0 (off) as well as yes and no.

Default
yes

scrolling	NN 6 IE 4 DOM 1
	Read/Write
Controls the treatment of scrollbars for a frame when the content exceeds the visible area of the frame. You can force a frame to display scrollbars at all times or never. Or you can let the browser determine the need for scrolling. In many supporting browsers, changing the value of this property has no effect.

Example

parent.document.getElementById("mainFrame").scrolling = "yes";

Value
String values of 1 (on) and 0 (off) as well as yes, no, and auto.

Default
auto