JavaScript Bible, Gold Edition part 40 pot

Example on the CD-ROM frameElement NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 If the current window exists as a result of a or tag, the win-dow’s frameElementproperty returns a referenc

To learn more about the externalobject and how to extend the MS object model, visit http://msdn.microsoft.com.workshop/browser/overview/ Overview.asp#Extending_the_Dynami

Example on the CD-ROM

frameElement

NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5

If the current window exists as a result of a <FRAME>or <IFRAME>tag, the win-dow’s frameElementproperty returns a reference to the hosting element As is made clear in the discussion later in this chapter about the FRAME element object,

a reference to a FRAME or IFRAME element object provides access to the properties that echo the attributes of the HTML element object For a window that is not part

of a frameset, the frameElement property returns null The convenience of this property becomes apparent when a single document is loaded into multiple framesets A script in the document can still refer to the con-taining FRAME element, even when the ID of the element changes from one frame-set to another The FRAMESET element is also accessible via the parentElement

property of the frameElementproperty:

var frameSetObj = self.frameElement.parentElement

A reference to the FRAMESET element opens possibilities of adjusting frame sizes

Related Items: FRAME, IFRAME objects.

frames

NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5

Compatibility ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓

In a multiframe window, the top or parent window contains any number of separate frames, each of which acts as a full-fledged windowobject The frames

property (note the plural use of the word as a property name) plays a role when a statement must reference an object located in a different frame For example, if a

On the

CD-ROM

windowObject.frames

button in one frame is scripted to load a document in another frame, the button’s

event handler must be able to tell JavaScript precisely where to display the new

HTML document The framesproperty assists in that task

To use the framesproperty to communicate from one frame to another, it

should be part of a reference that begins with the parentor topproperty This lets

JavaScript make the proper journey through the hierarchy of all currently loaded

objects to reach the desired object To find out how many frames are currently

active in a window, use this expression:

parent.frames.length

This expression returns a number indicating how many frames the parent

win-dow defines This value does not, however, count further nested frames, should a

third generation of frame be defined in the environment In other words, no single

property exists that you can use to determine the total number of frames in the

browser window if multiple generations of frames are present

The browser stores information about all visible frames in a numbered (indexed)

array, with the first frame (that is, the topmost <FRAME>tag defined in the

frameset-ting document) as number 0:

parent.frames[0]

Therefore, if the window shows three frames (whose indexes are frames[0],

frames[1], and frames[2], respectively), the reference for retrieving the title

property of the document in the second frame is

parent.frames[1].document.title

This reference is a road map that starts at the parent window and extends to the

second frame’s document and its titleproperty Other than the number of frames

defined in a parent window and each frame’s name (top.frames[i].name), no

other values from the frame definitions are directly available from the frame object

via scripting until you get to IE4 and NN6 (see the FRAME element object later in

this chapter) In these browsers, individual FRAME element objects have several

properties that reveal <FRAME>tag attributes

Using index values for frame references is not always the safest tactic, however,

because your frameset design may change over time, in which case the index

val-ues will also change Instead, you should take advantage of the NAMEattribute of the

<FRAME>tag, and assign a unique, descriptive name to each frame A value you

assign to the NAMEattribute is also the name that you use for TARGETattributes of

links to force a linked page to load in a frame other than the one containing the link

You can use a frame’s name as an alternative to the indexed reference For example,

in Listing 16-7, two frames are assigned distinctive names To access the title of a

document in the JustAKid2frame, the complete object reference is

parent.JustAKid2.document.title

with the frame name (case-sensitive) substituting for the frames[1]array

refer-ence Or, in keeping with JavaScript flexibility, you can use the object name in the

array index position:

parent.frames[“JustAKid2”].document.title

windowObject.frames

The supreme advantage to using frame names in references is that no matter how the frameset structure may change over time, a reference to a named frame will always find that frame, although its index value (that is, position in the frame-set) may change

Example (with Figure 16-5 and Listings 16-7 and 16-8) on the CD-ROM

Related Items:frame, framesetobjects; window.parent, window.topproperties

history

NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5

Compatibility ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓

See the discussion of the historyobject in Chapter 17

innerHeight

innerWidth

outerHeight

outerWidth

NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5

Compatibility ✓ ✓

Navigator 4+ lets scripts adjust the height and width of any window, including the main browser window by setting properties (NN4+ and IE4+ have methods that also resize the browser window) This adjustment can be helpful when your page shows itself best with the browser window sized to a particular height and width Rather than relying on the user to size the browser window for optimum viewing of your page, you can dictate the size of the window (although the user can always manually resize the main window) And because you can examine the operating system of the visitor via the navigatorobject (see Chapter 28), you can size a window to adjust for the differences in font and form element rendering on different platforms

Netscape provides two different points of reference for measuring the height and width of a window: inner and outer Both are measured in pixels The inner mea-surements are that of the active document area of a window (sometimes known as a

On the

CD-ROM

windowObject.innerHeight

window’s content region) If the optimum display of your document depends on the

document display area being a certain number of pixels high and/or wide, the

innerHeightand innerWidthproperties are the ones to set

In contrast, the outer measurements are of the outside boundary of the entire

window, including whatever chrome is showing in the window: scrollbars,

status-bar, and so on Setting the outerHeightand outerWidthis generally done in

con-cert with a reading of screenobject properties (Chapter 28) Perhaps the most

common usage of the outer properties is to set the browser window to fill the

available screen area of the visitor’s monitor

A more efficient way of modifying both outer dimensions of a window is with the

window.resizeTo()method, which is also available in IE4+ The method takes

pixel width and height (as integer values) as parameters, thus accomplishing a

window resizing in one statement Be aware that resizing a window does not adjust

the location of a window Therefore, just because you set the outer dimensions of a

window to the available space returned by the screenobject doesn’t mean that the

window will suddenly fill the available space on the monitor Application of the

window.moveTo()method is necessary to ensure the top-left corner of the window

is at screen coordinates 0,0

Despite the freedom that these properties afford the page author, Netscape has

built in a minimum size limitation for scripts that are not cryptographically signed

You cannot set these properties such that the outer height and width of the

window is smaller than 100 pixels on a side This limitation is to prevent an

unsigned script from setting up a small or nearly invisible window that monitors

activity in other windows With signed scripts, however, windows can be made

smaller than 100 ×100 pixels with the user’s permission IE4+ maintains a smaller

minimum size to prevent resizing a window to zero size

Example (with Listing 16-9) on the CD-ROM

Related Items:window.resizeTo(), window.moveTo()methods; screenobject;

navigatorobject

loading

NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓

This NN4-specific property allows you to query whether the window is still

load-ing content The property returns trueif the page is still loading and falseif the

page has completed loading all of its content

On the

CD-ROM

windowObject.loading

NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5

Compatibility ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓

See the discussion of the locationobject in Chapter 17

locationbar

See directories

name

NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓

All windowobjects can have names assigned to them Names are particularly useful for working with frames, because a good naming scheme for a multiframe environment can help you determine precisely which frame you’re working with in references coming from other frames

The main browser window, however, has no name attached to it by default Its value is an empty string There aren’t many reasons to assign a name to the win-dow, because JavaScript and HTML provide plenty of other ways to refer to the

windowobject (the topproperty, the _topconstant for TARGETattributes, and the

openerproperty from subwindows)

If you want to attach a name to the main window, you can do so by setting the

window.nameproperty at any time But be aware that because this is one window property whose life extends beyond the loading and unloading of any given docu-ment, chances are that your scripts would use the reference in only one document

or frameset Unless you restore the default empty string, your programmed window name will be present for any other document that loads later My suggestion in this regard is to assign a name in a window’s or frameset’s onLoadevent handler, and then reset it to empty in a corresponding onUnloadevent handler:

<BODY onLoad=”self.name = ‘Main’” onUnload=”self.name = ‘’”>

You can see an example of this application in Listing 16-16, where setting a par-ent window name is helpful for learning the relationships among parpar-ent and child windows

Related Items:topproperty; window.open(), window.sizeToContent()methods

windowObject.name

NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5

Although the navigatorobject appears as a property of the windowobject only

in the most recent browsers, the navigatorobject has been around since the very

beginning (see Chapter 28) In previous browsers, the navigatorobject was

refer-enced as a standalone object And because you can omit any reference to the

windowobject for a windowobject’s properties, you can use the same window-less

reference syntax for compatibility across all scriptable browsers (at least for the

navigatorobject properties that exist across all browsers) That’s the way I

recommend referring to the navigatorobject

Example on the CD-ROM

Related Items:navigatorobject

offscreenBuffering

NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5

Internet Explorer 4+ (for Win32 platforms) by default initially renders a page in a

buffer (a chunk of memory) before it is blasted to the video screen You can control

this behavior explicitly by modifying the window.offscreenBufferingproperty

The default value of the property is the string auto You can also assign Boolean

trueor falseto the property to override IE’s normal automatic handling of this

behavior

Example on the CD-ROM

onerror

Value: Function Read/Writ

On the

CD-ROM

On the

CD-ROM

windowObject.onerror

NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5

The onerrorproperty is an exception to the rule of this book to not describe event handlers as properties within object reference sections The reason is that the onErrorevent brings along some special properties that are useful to control

by setting the event handler property in scripts

Recent browsers (IE5+ and NN4+) are designed to prevent script errors from being intrusive if a user encounters a script error while loading or interacting with a page Even so, even the subtle hints about problems (messages or icons in the statusbar) can be confusing for users who have no idea what JavaScript is JavaScript lets you turn off the display of script error windows or messages as someone executes a script on your page The question is: When should you turn off these messages? Script errors generally mean that something is wrong with your script The error may be the result of a coding mistake or, conceivably, a bug in JavaScript (perhaps

on a platform version of the browser that you haven’t been able to test) If such errors occur, often the script won’t continue to do what you intended Hiding the script error from yourself during development would be foolhardy, because you’d never know whether unseen errors are lurking in your code It can be equally dan-gerous to turn off error dialog boxes for users who may believe that the page is operating normally, when, in fact, it’s not Some data values may not be calculated

or displayed correctly

That said, I can see some limited instances of when you may want to keep such dialog box windows from appearing For example, if you know for a fact that a plat-form-specific bug trips the error message without harming the execution of the script, you may want to prevent that error alert dialog box from appearing in the files posted to your Web site You should do this only after extensive testing to ensure that the script ultimately behaves correctly, even with the bug or error

IE fires the onError event handler only for runtime errors This means that if you have a syntactical error in your script that trips the browser as the page loads, the onErrorevent doesn’t fire, and you cannot trap that error message Moreover, if the user has the IE script debugger installed, any code you use to prevent browser error messages from appearing will not work

When the browser starts, the window.onerrorproperty is <undefined> In this state, all errors are reported via the normal JavaScript error window or message To turn off error alerts, set the window.onerrorproperty to invoke a function that does absolutely nothing:

function doNothing() {return true}

window.onerror = doNothing

To restore the error messages, reload the page

You can, however, also assign a custom function to the window.onerror prop-erty This function then handles errors in a more friendly way under your script control Whenever error messages are turned on (the default behavior), a script

Note

windowObject.onerror

error (or Java applet or class exception) invokes the function assigned to the

onerrorproperty, passing three parameters:

✦ Error message

✦ URL of document causing the error

✦ Line number of the error

You can essentially trap for all errors and handle them with your own interface

(or no user notification at all) The last statement of this function must be return

trueif you do not want the JavaScript script error message to appear

NN6 does not pass error-related parameters to a function invoked by onError This

may be an attempt to lure scripters to the more modern try-catch error trapping

mechanism (see Chapter 39) But it means that NN6 cannot take complete

advan-tage of older error reporting code, including that shown in Listing 16-10

If you are using LiveConnect to communicate with a Java applet or (in NN3+) to

call up Java class methods directly from your scripts, you can use the same scheme

to handle any exception that Java may throw A Java exception is not necessarily a

mistake kind of error: Some methods assume that the Java code will trap for

excep-tions to handle special cases (for example, reacting to a user’s denial of access

when prompted by a signed script dialog box) See Chapter 44 for an example of

trapping for a specific Java exception Also, see Chapter 39 for JavaScript exception

handling introduced for W3C DOM-compatible browsers

Example (with Figure 16-6 and Listing 16-10) on the CD-ROM

Related Items:location.reload()method; JavaScript exception handling

(Chapter 39); debugging scripts (Chapter 45)

opener

NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓

Many scripters make the mistake of thinking that a new browser window created

with the window.open()method has a child–parent relationship similar to the one

that frames have with their parents That’s not the case at all New browser

win-dows, once created, have a very slim link to the window from whence they came:

via the openerproperty The purpose of the openerproperty is to provide scripts

in the new window with valid references back to the original window For example,

the original window may contain some variable values or general-purpose functions

that a new window at this Web site wants to use The original window may also

On the

CD-ROM

Note

windowObject.opener

have form elements whose settings are either of value to the new window or get set

by user interaction in the new window

Because the value of the openerproperty is a reference to a genuine window

object, you can begin references with the property name Or, you may use the more complete window.openeror self.openerreference But the reference must then include some object or property of that original window, such as a window method

or a reference to something contained by that window’s document

Although this property was new for Navigator 3 (and was one of the rare Navigator 3 features to be included in Internet Explorer 3), you can make your scripts backward compatible to Navigator 2 For every new window you create, make sure it has an openerproperty as follows:

var newWind = window.open()

if (newWind.opener == null) { newWind.opener = self }

For Navigator 2, this step adds the openerproperty to the windowobject refer-ence Then, no matter which version of JavaScript-enabled Navigator the user has, the openerproperty in the new window’s scripts points to the desired original window

If a subwindow opens yet another subwindow, the chain is still valid, albeit one step longer The third window can reach the main window with a reference that begins:

opener.opener

It’s a good idea for the third window to store in a global variable the value of

opener.openerwhile the page loads Thus, if the user closes the second window, the variable can be used to start a reference to the main window

When a script that generates a new window is within a frame, the opener prop-erty of the subwindow points to that frame Therefore, if the subwindow needs to communicate with the main window’s parent or another frame in the main window, you have to very carefully build a reference to that distant object For example, if the subwindow needs to get the checkedproperty of a checkbox in a sister frame

of the one that created the subwindow, the reference is

opener.parent.sisterFrameName.document.formName.checkboxName.checked

It is a long way to go, indeed, but building such a reference is always a case of mapping out the path from where the script is to where the destination is, step-by-step

Example (with Figure 16-7 and Listings 16-11 and 16-12) on the CD-ROM

Related Items:window.open(), window.focus()methods

On the

CD-ROM

windowObject.opener

outerWidth

See innerHeightand innerWidth, earlier

pageXOffset

pageYOffset

NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ ✓

The top-left corner of the content (inner) region of the browser window is an

important geographical point for scrolling documents When a document is scrolled

all the way to the top and flush left in the window (or when a document is small

enough to fill the browser window without displaying scrollbars), the document’s

location is said to be 0,0, meaning zero pixels from the top and zero pixels from the

left If you were to scroll the document, some other coordinate point of the

docu-ment would be under that top-left corner That measure is called the page offset,

and the pageXOffsetand pageYOffsetproperties let you read the pixel value of

the document at the inner window’s top-left corner: pageXOffsetis the horizontal

offset, and pageYOffsetis the vertical offset

The value of these measures becomes clear if you design navigation buttons in

your pages to carefully control paging of content being displayed in the window For

example, you might have a two-frame page in which one of the frames features

navi-gation controls, while the other displays the primary content The navinavi-gation

con-trols take the place of scrollbars, which, for aesthetic reasons, are turned off in the

display frame Scripts connected to the simulated scrolling buttons can determine

the pageYOffsetvalue of the document, and then use the window.scrollTo()

method to position the document precisely to the next logical division in the

docu-ment for viewing

IE4+ has corresponding values as bodyobject properties: body.scrollLeftand

body.scrollTop(see Chapter 18)

Example (with Listing 16-13) on the CD-ROM

Related Items:window.innerHeight, window.innerWidth, body.scrollLeft,

body.scrollTopproperties; window.scrollBy(), window.scrollTo()methods

On the

CD-ROM

windowObject.pageXOffset