468 Part III ✦ Document Objects Reference pasteHTML(“HTMLText”) Returns: Nothing. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ While the execCommand() method offers several commands that insert HTML elements into a text range, it is probably more convenient to simply paste fully formed HTML into the current text range (assuming you need to be working with a text range instead of even more simply setting new values to an element object’s outerHTML property). Provide the HTML to be inserted as a string parameter to the pasteHTML() method. Use the pasteHTML() method with some forethought. Some HTML that you may attempt to paste into a text range may force the method to wrap additional tags around the content you provide to ensure the validity of the resulting HTML. For example, if you were to replace a text range consisting of a portion of text of a P ele- ment with, for instance an LI element, the pasteHTML() method has no choice but to divide the P element into two pieces, because a P element is not a valid container for a solo LI element. This division can greatly disrupt your document object hierar- chy, because the divided P element assumes the same ID for both pieces. Existing references to that P element will break, because the reference now returns an array of two like-named objects. Example on the CD-ROM Related Items: outerHTML property; insertAdjacenHTML() method. queryCommandEnabled(“commandName”) queryCommandIndeterm(“commandName”) queryCommandState(“commandName”) queryCommandSupported(“commandName”) queryCommandText(“commandName”) queryCommandValue(“commandName”) Returns: See document.queryCommandEnabled() in Chapter 18. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ See descriptions under document.queryCommandEnabled() in Chapter 18. On the CD-ROM TextRange.queryCommandEnabled() 469 Chapter 19 ✦ Body Text Objects select() Returns: Nothing. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ The select() method selects the text inside the boundaries of the current text range. For some operations, such as prompted search and replace, it is helpful to show the user the text of the current range to highlight what text is about to be replaced. In some other operations, especially several commands invoked by execCommand(), the operation works only on a text selection in the document. Thus, you can use the TextRange object facilities to set the boundaries, followed by the select() method to prepare the text for whatever command you like. Text selected by the select() method becomes a selection object (covered earlier in this chapter). Example on the CD-ROM Related Items: selection object. setEndPoint(“type”, otherRangeRef) Returns: Nothing. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ In contrast to the moveEnd() method, which adjusts the end point of the current range with respect to characters, words, sentences, and the complete range, the setEndPoint() method sets a boundary of the current range (not necessarily the ending boundary) relative to a boundary of another text range whose reference is passed as the second parameter. The first parameter is one of four types that con- trol which boundary of the current range is to be adjusted and which boundary of the other range is the reference point. Table 19-3 shows the four possible values and their meanings. On the CD-ROM TextRange.setEndPoint() 470 Part III ✦ Document Objects Reference Table 19-3 setEndPoint() Method Types Type Description StartToEnd Moves the start point of the current range to the end of the other range StartToStart Moves the start point of the current range to the start of the other range EndToStart Moves the end point of the current range to the start of the other range EndToEnd Moves the end point of the current range to the end of the other range Note that the method moves only one boundary of the current range at a time. If you want to make two ranges equal to each other, you have to invoke the method twice, once with StartToStart and once with EndToEnd. At that instant, the isEqual() method applied to those two ranges returns true. Setting a boundary point with the setEndPoint() method can have unexpected results when the revised text range straddles multiple elements. Don’t be surprised to find that the new HTML text for the revised range does not include tags from the outer element container. Example on the CD-ROM Related Items: TextRange.moveEnd(), TextRange.moveStart(), TextRange. moveToElementText() methods. TextRectangle Object Properties Methods Event Handlers bottom left right top Syntax Accessing TextRectangle object properties: [window.]document.all.elemID.getBoundingClientRect().property [window.]document.all.elemID.getClientRects()[i].property On the CD-ROM TextRectangle 471 Chapter 19 ✦ Body Text Objects About this object The IE5+ TextRectangle object (not implemented in IE5/Mac) exposes to scripts a concept that is described in the HTML 4.0 specification, whereby an ele- ment’s rendered text occupies a rectangular space on the page just large enough to contain the text. For a single word, the rectangle is as tall as the line height for the font used to render the word and no wider than the space occupied by the text. But for a sequence of words that wraps to multiple lines, the rectangle is as tall as the line height times the number of lines and as wide as the distance between the left- most and rightmost character edges, even if it means that the rectangle encloses some other text that is not part of the element. If you extract the TextRectangle object for an element by way of, for example, the getBoundingClientRect() method, be aware that the object is but a snap- shot of the rectangle when the method was invoked. Resizing the page may very well alter dimensions of the actual rectangle enclosing the element’s text, but the TextRectangle object copy that you made previously does not change its values to reflect the element’s physical changes. After a window resize or modification of body text, any dependent TextRectangle objects should be recopied from the element. Properties bottom left right top Values: Integers Read-only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ The screen pixel coordinates of its four edges define every TextRectangle object. These coordinates are relative to the window or frame displaying the page. Therefore, if you intend to align a positioned element with an inline element’s TextRectangle, your position assignments must take into account the scrolling of the body. To my eye, the left edge of a TextRectangle does not always fully encompass the left-most pixels of the rendered text. You may have to fudge a few pixels in the measure when trying to align a real element with the TextRectangle of another element. TextRectangle.bottom 472 Part III ✦ Document Objects Reference Example (with Listing 19-12) on the CD-ROM Related Items: getBoundingClientRect(), getClientRects() methods of element objects (Chapter 15). ✦✦✦ On the CD-ROM TextRectangle.bottom HTML Directive Objects T hanks to the modern browser’s desire to expose all HTML elements to the document object model, we can now (in IE4+ and NN6) access a variety of objects that repre- sent many HTML elements that are normally invisible to the human viewer of a page. These elements are called directive elements because they predominantly contain instructions for the browser — instructions that direct the browser to locate associated content on the page, link in external specifications, treat content as executable script statements, and more. As you browse through the objects of this chapter, you may wonder why they have so many properties that normally indi- cate that the elements occupy space on the rendered page. After all, how can a META element have dimension or position on the page when it has no renderable content? The reason is that modern browsers internally employ some form of object- oriented behavior that lets all HTML elements — rendered or not — inherit the same set of properties, methods, and event handlers that any generic element has (see Chapter 15). The logical flaw is that unrendered elements can have properties and methods that don’t genuinely apply to them. In such cases, their property values may be zero, an empty string, or an empty array. Yet the properties and methods exist in the objects just the same. Therefore, despite the large number of objects covered in this chapter, there are relatively few prop- erties and methods that are not shared already with all HTML elements (as covered in Chapter 15). HTML Element Object For HTML element properties, methods, and event handlers, see Chapter 15. Properties Methods Event Handlers version 20 20 CHAPTER ✦✦✦✦ In This Chapter Accessing non- displayed element objects Linking operating- system specific style sheet definitions HTML, HEAD, LINK, TITLE, META, BASE, and SCRIPT elements ✦✦✦✦ 474 Part III ✦ Document Objects Reference Syntax Accessing HTML element object properties or methods: (IE4+) [window.]document.all.elemID.property | method([parameters]) (IE5+/NN6) [window.]document.getElementById(“elemID”).property | method([parameters]) (IE4+/NN6) [window.]document.body.parentElement.property | method([parameters]) About this object The HTML element is the big wrapper around all other elements of the page. In the object tree, the HTML element sits between the all-encompassing document object and the element’s most common children, the HEAD and BODY elements. Other than one deprecated property ( version), the HTML element object offers nothing of importance to the scripter — with one possible exception. When your script needs to use methods on the child nodes of the HTML element, you must invoke most of those methods from the point of view of the HTML element. Therefore, you should know how to create a reference to the HTML element object (shown in the preceding “Syntax” section) just in case you need it. Property version Value: String Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ The version property is an artifact of an “ancient” way an HTML document used to specify the HTML version of its content. These days, the preferred way to declare the HTML version for a document is through a Document Type Declaration (DTD) statement that precedes the <HTML> tag. An example of a modern DTD statement that accommodates HTML 4 plus deprecated elements and attributes as well as frameset support is <!DOCTYPE HTML PUBLIC “-//W3C//DTD HTML 4.0 Frameset//EN” “http://www.w3.org/TR/REC-html40/frameset.dtd”> See http://www.w3.org/TR/REC-html40/struct/global.html#h-7.2 for several other possibilities. A DTD statement does not affect the version property of an HTML element object. Related Items: None. HEAD Element Object For HTML element properties, methods, and event handlers, see Chapter 15. HEAD 475 Chapter 20 ✦ HTML Directive Objects Properties Methods Event Handlers profile Syntax Accessing HEAD element object properties or methods: (IE4+) [window.]document.all.elemID.property | method([parameters]) (IE5+/NN6) [window.]document.getElementById(“elemID”).property | method([parameters]) About this object The purpose of the HEAD element is primarily to act as a container for most of the other HTML directive elements. Other than as a reference point to the child elements nested within, the HEAD element object rarely comes into play when scripting a document. Properties profile Value: String Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ The profile property is the script version of the optional PROFILE attribute of a HEAD element. While the attribute and property are supported in NN6 (that is, they exist), they are not used in practice yet. You can find details about the attribute at http://www.w3.org/TR/REC-html40/struct/global.html#profiles. Related Items: META element object. BASE Element Object For HTML element properties, methods, and event handlers, see Chapter 15. Properties Methods Event Handlers href target BASE 476 Part III ✦ Document Objects Reference Syntax Accessing BASE element object properties or methods: (IE4+) [window.]document.all.elemID.property | method([parameters]) (IE5+/NN6) [window.]document.getElementById(“elemID”).property | method([parameters]) About this object The BASE element enables the page author to specify a default server directory and/or link target for the entire page. If you omit the BASE element from the HTML, browsers use the current page’s path as the base URL and the current window or frame as the default target. Occasionally, a page generated entirely by way of document.write() has difficulty establishing the same BASE URL as the docu- ment that generates the content, particularly if the primary page is written out by a server script (in Perl or in another language). Including a <BASE> tag in the dynamically written new page solves the problem; the new page can fetch images or other external elements via relative URLs within the page. The two distinctive properties of the BASE element object are rarely scripted, if ever. Properties href Value: URL String Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ The href property is generally an absolute URL to the directory you wish to declare as the default directory for the page. Even though browsers automatically set the BASE HREF to the document’s own directory, this object and property do not have any values unless you explicitly set them in a <BASE> tag. In IE, changing this property after a page loads causes the page to re-resolve all relative URLs on the page to the new BASE HREF. Therefore, if images have relative URLs assigned to their src properties (either by way of the tag attribute or script), a change to the BASE element’s href property forces the browser to look for those same relative URLs in the new directory. If the files aren’t there, then the images show up broken on the page. Example on the CD-ROM On the CD-ROM BASE.href 477 Chapter 20 ✦ HTML Directive Objects target Value: String Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ The target property governs the default window or frame that is to receive any content coming from a server in response to a click on a link or any other element that has its own TARGET attribute. Valid values include the name of any frame (as assigned to the NAME attribute of the <FRAME> tag) or window (as defined by the second attribute of the window.open() method). You can also assign standard HTML targets ( _blank, _parent, _self, and _top) to this property as strings. Example on the CD-ROM BASEFONT Element Object For HTML element properties, methods, and event handlers, see Chapter 15. Properties Methods Event Handlers color face size Syntax Accessing BASEFONT element object properties or methods: (IE4+) [window.]document.all.elemID.property | method([parameters]) (IE5+/NN6) [window.]document.getElementById(“elemID”).property | method([parameters]) About this object The BASEFONT element enables authors to define a font face, size, and color for an entire section of an HTML document — or the entire document. Although page authors still frequently use the BASEFONT element, font control in modern browsers should fall in the hands of style sheets. (The element is deprecated in HTML 4.0.) The paradox of this is that the BASEFONT element is accessible as a scriptable object only in browsers that support style sheets. Even so, I recommend On the CD-ROM BASEFONT . 468 Part III ✦ Document Objects Reference pasteHTML(“HTMLText”) Returns: Nothing. NN2 NN3 NN4 NN6 IE3/J1. 19-3 shows the four possible values and their meanings. On the CD-ROM TextRange.setEndPoint() 470 Part III ✦ Document Objects Reference Table 19-3 setEndPoint() Method Types Type Description StartToEnd. rightmost character edges, even if it means that the rectangle encloses some other text that is not part of the element. If you extract the TextRectangle object for an element by way of, for example, the