Path // www.yourhtmlsource.comJavaScript → SCRIPTING FRAMES

Scripting Frames


Frames are a special case in JavaScript — each frame behaving like the separate document that it is. This means that to modify anything in another frame, you first need to gain control of this frame by working with something called the frame tree.

Clock This page was last updated on 2012-08-21



Setting it Up

As you probably know, frames are a HTML technique which allow you to split one page into a number of contained windows, each of which hold a separate HTML file. While all of the component pages are displayed together they don't actually share any connections. A function executed in one will have no effect across in another. So we need to gain control of each frame through a part of the Document Object Model which assumes the place of the window level.

First, you'll need to make sure that all of your frames have been given a name attribute. They probably all will have one installed since it's necessary for cross-frame linking, but just make sure. Something like this is fine:

<frame src="navigation.html" name="nav">
<frame src="maincontent.html" name="content">

The Frame Tree

When a frameset is loaded into the main window a frame tree is created. The window, which JavaScript calls top, holds some frames underneath it. If these frames have nested framesets inside themselves, then a further level is added to the tree. A page with frames set up as on the left will have a frame tree as on the right:

nav

content

Diagram of hierarchal frame tree with parent top and two children, nav and content

Pretty simple, right? The top object has two elements, which are referenced by the name values you have given them previously. All you need to glean from this is each frame's position relative to the others. A more complex example would mean opening a new frameset inside an existing frame. Below we have something a bit more tricky, where the content frame has had three new frames opened inside it.

nav

one
two
three
Diagram of frame tree with three frameset levels

A bit more complex, that. As you can see, three new frames have been added on a new level underneath content, which retains its place in the tree, even though it isn't seen by the user.

Traversing the Tree

To modify something in another frame you must first travel along the frame tree from the frame you're in to the frame you want to control. This involves some keywords.

Every frame has what's known as a parent frame — that is, the frame above it in the hierarchy. one's parent is content; nav's parent is top; and top's parent is top too (there aren't any more levels up, so it takes itself as a parent). To access a parent frame, we use just that:

parent

From three, to get to top, we could write

parent.parent

Some frames also have children, predictably the frames held underneath them. Above, top has two children, nav and content; while content has itself three children. To access a child frame from its parent, we use

self.childName

We now have enough to move between frames This is all very similar to relative linking, if you're looking for an analogy. To get from three to nav, we'd write

parent.parent.nav

To go to three from top, we could write

self.content.three

The final method of addressing a frame is to start at the top and drill down to the frame you want. This is a useful shortcut if you're far down a complex tree and want to access a frame that's higher up. Simply start off with top and work down to the frame you want.

top.content.two

In Practice

Now that you know the syntax, I can show you a real example. Say we were in the frame one, and we wanted to execute a function that's in nav. We traverse the frame tree, and then once we're in the right place we execute the code as if we're in the same document after that point. Think of the frames part of the following lines as equivalent to window. A function call might look like this (sending 6 as an arbitrary parameter):

parent.parent.nav.functionName(6);

Accessing variables and the rest is much the same:

parent.parent.nav.document.var = "Hooray";

And yeah, parent.parent could be replaced with top if you're smart. If you're having any trouble, Peter-Paul Koch has written a fine » frame tree parser which you can use to print out a diagram of your tree while you're working with it.