JavaScript Bible, Gold Edition part 47 ppsx

308 Part III ✦ Document Objects Reference Example on the CD-ROM Related Items: FRAME.borderColor, FRAMESET.frameBorder properties. cols rows Value: String Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ The cols and rows properties of a FRAMESET element object let you read and modify the sizes of frames after the frameset has loaded. These two properties are defined in the W3C DOM. Values for both properties are strings, which may include percent symbols or asterisks. Therefore if you are trying to increase or decrease the size of a frame column or row gradually, you must parse the string for the nec- essary original values before performing any math on them (or, in IE4+, use the FRAME element object’s height and width properties to gauge the current frame size in pixels). IE4+ lets you completely modify the frameset by adjusting these properties. This includes adding or removing columns or rows to the frameset grid. Because a change in the frameset structure could impact scripts by changing the size of the frames array associated with the parent window or unloading documents that con- tain needed data, be sure to test your scripts with both states of your frameset. If you want to remove a frame from a frameset view, you might be safer to specify the size of zero for that particular row or column in the frameset. Of course a size of zero still leaves a one-pixel frame, but it is essentially invisible if borders are not turned on and the one-pixel frame shares the same background color as the other frames. Another positive by-product of this technique is that you can restore the other frame with its document state identical from when it was hidden. When you have nested framesets defined in a single document, be sure to refer- ence the desired FRAMESET element object. One object may be specifying the columns, while another (nested) one specifies the rows for the grid. Assign a unique ID to each FRAMESET element so that references can be reliably directed to the proper object. Example (with Listings 16-46, 16-47, and 16-48) on the CD-ROM Related Items: FRAME object. On the CD-ROM On the CD-ROM FRAMESET.cols 309 Chapter 16 ✦ Window and Frame Objects frameBorder Value: yes | no | 1 | 0 as strings Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ The frameBorder property offers scripted access to a FRAMESET element object’s FRAMEBORDER attribute setting. IE4+ does not respond well to modifying this property after the page has loaded. Values for the frameBorder property are strings that substitute for Boolean values. Values yes or 1 mean that the border is (supposed to be) turned on; no or 0 turn off the border. Example on the CD-ROM Related Items: FRAME.frameBorder properties. frameSpacing Value: Integer Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ The frameSpacing property of a FRAMESET element object lets you read the spacing (in pixels) between frames of a frameset. If you do not specify a FRAMES- PACING attribute in the frameset’s tag, the property is empty, rather than reflecting the actual border thickness applied by default (usually 2). Example on the CD-ROM Related Items: FRAMESET.border property. On the CD-ROM On the CD-ROM FRAMESET.frameSpacing 310 Part III ✦ Document Objects Reference IFRAME Element Object For HTML element properties, methods, and event handlers, see Chapter 15. Properties Methods Event Handlers align contentDocument Document frameBorder frameSpacing hspace longDesc marginHeight marginWidth scrolling src vspace Syntax Accessing properties or methods of an IFRAME element object from a containing document: (IE4+) document.all.iframeID. property | method([parameters]) (IE4+/NN6) window.frames[“iframeName”]. property | method([parameters]) (IE5+/NN6) document.getElementById(“iframeID”). property | method([parameters]) Accessing properties of methods of an IFRAME element from a document inside the IFRAME element: (IE4+) parent.document.all.iframeID. property | method([parameters]) (IE5+/NN6) parent.document.getElementById(“iframeID”). property | method([parameters]) About this object An IFRAME element (IE4+ and NN6) allows HTML content from a separate source to be loaded within the body of another document. In some respects, the NN4 LAYER element was a precursor to the IFRAME concept, but unlike the LAYER, an IFRAME element is not inherently positionable. It is positionable, the same way as any other HTML element, by assigning positioning attributes to a style sheet associ- ated with the IFRAME. Without explicit positioning, an IFRAME element appears in IFRAME 311 Chapter 16 ✦ Window and Frame Objects the body of a document in normal source code order of elements. Unlike a frame of a frameset, you can place an IFRAME arbitrarily in the middle of any document. If the FRAME changes size under script control, the surrounding content moves out of the way or cinches up. What truly separates the IFRAME apart from other HTML elements is its ability to load and display external HTML files and, with the help of scripts, have different pages loaded into the IFRAME without disturbing the rest of the content of the main document. Pages loaded into the IFRAME can also have scripts and any other fea- tures that you may like to put into an HTML document (including XML). The IFRAME element has a rich set of attributes that let the HTML author control the look, size ( HEIGHT and WIDTH), and, to some degree, behavior of the frame. Most of those are accessible to scripts as properties of an IFRAME element object. It is important to bear in mind that an IFRAME element is in many respects like a FRAME element, especially when it comes to window kinds of relationships. If you plant an IFRAME element in a document of the main window, that element shows up in the main window’s object model as a frame, accessible via common frames termi- nology: window.frames[i] window.frames[frameName] Within that IFRAME frame object is a document and all its contents. All refer- ences to the document objects inside the IFRAME must flow through the “portal” of the IFRAME frame. Conversely, scripts in the document living inside an IFRAME can communicate with the main document via the parent reference. Of course, you cannot replace the content of the main window with another HTML document (using location.href, for instance) without destroying the IFRAME that was in the origi- nal document. Properties align Value: String Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ The align property governs how an IFRAME element aligns itself with respect to surrounding content on the page. Two of the possible values ( left and right) position the IFRAME along the left and right edge (respectively) of the IFRAME’s containing element (usually the BODY). Just as with an image, when an IFRAME is floated along the left and right edges of a container, other content wraps around the element. Table 16-5 shows all possible values and their meanings. IFRAME.align 312 Part III ✦ Document Objects Reference Table 16-5 Values of the align Property Value Description absbottom Aligns the bottom of the IFRAME with the imaginary line that extends along character descenders of surrounding text. absmiddle Aligns the middle of the IFRAME with the center point between the surrounding text’s top and absbottom. baseline Aligns the bottom of the IFRAME with the baseline of surrounding text. bottom Same as baseline in IE. left Aligns the IFRAME flush with left edge of the containing element. middle Aligns the imaginary vertical centerline of surrounding text with the same for the IFRAME element. right Aligns the IFRAME flush with the right edge of the containing element. texttop Aligns the top of the IFRAME element with the imaginary line that extends along the tallest ascender of surrounding text. top Aligns the top of the IFRAME element with the surrounding element’s top. As your script changes the value of the align property, the page automatically reflows the content to suit the new alignment. Example on the CD-ROM Related Items: IFRAME.hspace, IFRAME.vspace properties. contentDocument Value: document object reference Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ The contentDocument property of an IFRAME element object is nothing more than a reference to the document contained by that frame. If your script finds that it has a reference to an IFRAME element object, you can use the contentDocument property to get a valid reference to the document, and therefore any other content of the frame. On the CD-ROM IFRAME.contentDocument 313 Chapter 16 ✦ Window and Frame Objects Example on the CD-ROM Related Items: document object. Document Value: document object Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ See the FRAME.Document property for details on this property of the ActiveX Web Browser object. You find less need for this property with an IFRAME element, because you can use the window object behavior of IFRAMEs to transcend the doc- ument object hierarchies of the main window and the IFRAME window. Related Items: FRAME.Document property. frameBorder Value: yes | no | 1 | 0 as strings Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ The frameBorder property offers scripted access to an IFRAME element object’s FRAMEBORDER attribute setting. IE4+ does not respond well to modifying this prop- erty after the page has loaded. Values for the frameBorder property are strings that substitute for Boolean val- ues. Values yes or 1 mean that the border is (supposed to be) turned on; no or 0 turn off the border. Example on the CD-ROM Related Items: FRAME.frameBorder properties. On the CD-ROM On the CD-ROM IFRAME.frameBorder 314 Part III ✦ Document Objects Reference frameSpacing Value: Integer Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ The frameSpacing property is included in IE5 for backward compatibility to IE4’s erroneous inclusion of this property for an IFRAME element. Do not use it. hspace vspace Value: Integer Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ These IE-specific properties allow for margins to be set around an IFRAME ele- ment. In general, hspace and vspace properties (and their HTML attributes) have been replaced by CSS margins and padding. These properties and their attributes are not recognized by any W3C standard (including HTML 4.0). Values for these properties are integers representing the number of pixels of padding between the element and surrounding content. The hspace value assigns the same number of pixels to the left and right sides of the element; the vspace value is applied to both the top and bottom edges. Scripted changes to these values have no effect in IE5/Windows. Example on the CD-ROM Related Items: style.padding property. longDesc Value: URL String Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ The longDesc property is the scripted equivalent of the LONGDESC attribute of the <IFRAME> tag. This HTML 4.0 attribute is intended to provide browsers with a URL to a document that contains a long description of the element. Future browsers On the CD-ROM IFRAME.longDesc 315 Chapter 16 ✦ Window and Frame Objects can use this feature to provide information about the frame for visually impaired site visitors. marginHeight marginWidth Value: Integer Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ Browsers tend to automatically insert content within a frame by adding a margin between the content and the edge of the frame. These values are represented by the marginHeight (top and bottom edges) and marginWidth (left and right edges) properties. Although the properties are not read-only, changing the values after the frameset has loaded does not alter the appearance of the document in the frame. If you need to alter the margin(s) of a document inside a frame, adjust the docu- ment.body.style margin properties. Also be aware that although the default values of these properties are empty (that is, when no MARGINHEIGHT or MARGINWIDTH attributes are set for the <IFRAME> tag), margins are built into the page. The precise pixel count of those margins varies with different operating systems. Related Items: style object (Chapter 30). scrolling Value: yes | no | 1 | 0 as strings Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ The scrolling property lets scripts turn scrollbars on and off inside an IFRAME element. By default, scrolling is turned on unless overridden by the SCROLL attribute of the <IFRAME> tag. Values for the scrolling property are strings that substitute for Boolean values. Values yes or 1 mean that scrollbars are visible (provided there is more content than can be viewed without scrolling); no or 0 hide scrollbars in the frame. IE4+ also recognizes (and sets as default) the auto value. Example on the CD-ROM Related Items: FRAME.scrolling property. On the CD-ROM IFRAME.scrolling 316 Part III ✦ Document Objects Reference src Value: URL String Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ The src property of an IFRAME element object offers an additional way of navi- gating to a different page within an inline frame (that is, other than assigning a new URL to the location.href property of the frame object). Remember that the src property belongs to the IFRAME element object, not the window object it repre- sents. Therefore, references to the src property must be via the element’s ID and/or node hierarchy. Example on the CD-ROM Related Items: location.href property. popup Object Properties Methods Event Handlers document hide() isOpen show() Syntax Creating a popup object: var popupObj = window.createPopup() Accessing properties or methods of a popup object from a document in the win- dow that created the pop-up: popupObj.property | method([parameters]) NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ On the CD-ROM popup 317 Chapter 16 ✦ Window and Frame Objects About this object A popup object is a chrome-less window space, which overlaps the window whose document generates the pop-up. A pop-up also appears in front of any dialog boxes. Unlike the dialog box windows generated via IE’s showModalDialog() and showModelessDialog() methods, your scripts must not only create the window, but also put content into it, and then define where on the screen and how big it will be. Because the pop-up window has no chrome (that is, title bar, resize handles, and so forth), you should populate its content with a border and/or background color so that it stands out from the main window’s content. The following statements reflect a typical sequence of creating, populating, and showing a popup object: var popup = window.createPopup() var popupBody = popup.document.body popupBody.style.border = “solid 2px black” popupBody.style.padding = “5px” popupBody.innerHTML = “<P>Here is some text in a popup window</P>” popup.show(200,100, 200, 50, document.body) The pop-up window that IE creates is, in fact, a window, but only from the point of view of the document that it contains. In other words, while the number of prop- erties and methods for the popup object is small, the parentWindow property of the document inside the pop-up points to a genuine window property. Even so, be aware that this pop-up does not appear as a distinct window among windows listed in the Windows Taskbar. If a user clicks outside of the pop-up or switches to another application, the pop-up disappears, and you must reinvoke the show() method by script (complete with dimension and position parameters) to force the pop-up to reappear. When you assign content to a pop-up, you are also responsible for making sure that the content fits the size of the pop-up you specify. If the content runs past the rectangular space (body text word wraps within the pop-up’s rectangle), no scroll- bars appear. Properties document Value: document object reference Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ Use the document property as a gateway to the content of a pop-up window. This property is the only access point available from the script that creates the pop-up to the pop-up itself. The most common application of this property is to set docu- ment properties governing the content of the pop-up window. For example, to give the pop-up a border (because the pop-up itself has no window chrome), the script popupObject.document . 308 Part III ✦ Document Objects Reference Example on the CD-ROM Related Items: FRAME.borderColor, FRAMESET.frameBorder. to remove a frame from a frameset view, you might be safer to specify the size of zero for that particular row or column in the frameset. Of course a size of zero still leaves a one-pixel frame,. that references can be reliably directed to the proper object. Example (with Listings 16-46, 16 -47, and 16-48) on the CD-ROM Related Items: FRAME object. On the CD-ROM On the CD-ROM FRAMESET.cols 309 Chapter