Section 25.138. Frame: a frame in an HTML document

25.138. Frame: a <frame> in an HTML document

DOM Level 2 HTML: Node Element HTMLElement Frame

25.138.1. Properties

As explained in the Description, HTML frames can be accessed as Frame objects or as Window objects. When accessed as Frame objects, they inherit properties from HTMLElement and define these additional properties:

Document contentDocument

The document that holds the content of the frame.

String src

The URL from which the frame's content was loaded. Setting this property causes the frame to load a new document. This property simply mirrors the src attribute of the HTML <frame> tag: it is not a Location object like Window.location.

In addition to these properties, the Frame object also defines the following properties, which correspond directly to HTML attributes:

Property	Attribute	Description
String frameBorder	frameborder	Set to "0" for borderless frames
String longDesc	longdesc	The URL of a frame description
String marginHeight	marginheight	Top and bottom frame margin, in pixels
String marginWidth	marginwidth	Left and right frame margin, in pixels
String name	name	The name of the frame, for DOM Level 0 lookup and form and link targets
boolean noResize	noresize	If true, user cannot resize frame
String scrolling	scrolling	Frame scroll policy: "auto", "yes", or "no"

25.138.2. Description

Frames have a dual nature and may be represented in client-side JavaScript by either Window or Frame objects. In the traditional Level 0 DOM, each <frame> is treated as an independent window and is represented by a Window object, referenced by name, or as an element of the frames[] array of the containing Window:

 // Get a frame as a Window object var win1 = top.frames[0];     // Index frames[] array by number var win2 = top.frames['f1'];  // Index frames[] array by name var win3 = top.f1;            // Get frame as a property of its parent 

When frames are looked up this way, the returned object is a Window, and the properties listed in the previous section are not available. Instead, use Window properties, such as document to access the frame's document and location to access the URL of that document.

In the Level 2 DOM, <frame> elements can be looked up by ID or tag name, just as any other document element can be:

 // Get a frame as a Frame object var frame1 = top.document.getElementById('f1');               // by id var frame2 = top.document.getElementsByTagName('frame')[1];   // by tag name 

When frames are looked up using DOM methods like these, the result is a Frame object rather than a Window object, and the properties listed previously are available. Use contentDocument to access the frame's document, and use the src property to query the URL of that document or to make the frame load a new document. To obtain the Window object of a Frame object f, use f.contentDocument.defaultView.

<iframe> elements are very similar to <frame> elements. See the IFrame reference page.

Note that the same-origin policy (see Section 13.8.2) applies to multiframed documents. Browsers do not allow you to access the content of frames loaded from a different origin than that of the content that includes the script. This is true whether the frame is represented by a Window or a Frame object.

25.138.3. See Also

IFrame, Window; Chapter 14