388 Part III ✦ Document Objects Reference Table 18-4 (continued) Command Parameter Description SelectAll None Selects all text of the document. UnBookmark None Removes anchor tags that surround the current selection. Unlink None Removes link tags that surround the current selection. Unselect None Deselects the current selection anywhere in the document. Example on the CD Related Items: queryCommandEnabled(), queryCommandIndterm(), queryCommandState(), queryCommandSupported(), queryCommandText(), queryCommandValue() methods. getElementById(“elementID”) Returns: Element object reference. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ The document.getElementById() method is the W3C DOM syntax for retriev- ing a reference to any element in a document that has a unique identifier assigned to its ID attribute. If the document contains more than one instance of an ID, the method returns a reference to the first element in source code order with that ID. Because this method is such an important avenue to writing references to objects that are to be modified under script control, you can see how important it is to assign unique IDs to elements. This method’s name is quite a finger twister for scripters, especially compared to the IE4+ convention of letting a reference to any element begin simply with the object’s ID. But unless you utilize the document.all normalization trick for NN6 as described in Chapter 15, the getElementById() method is the cross-browser way of gaining an element’s reference for IE5+ and NN6+. When you type this method, be sure to use a lowercase “d” as the last character of the method name. Unlike some other element-oriented methods (for example, getElementsByTagName()), which can be invoked on any element in a document, the getElementById() method works exclusively with the document object. On the CD-ROM document.getElementById() 389 Chapter 18 ✦ The Document and Body Objects Example on the CD Related Items: getElementsByTagName() method (Chapter 15). getElementsByName(“elementName”) Returns: Array. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ The document.getElementsByName() method returns an array of references to objects whose NAME attribute is assigned the element name passed as the method’s attribute. Although NN6 recognizes NAME attributes even for elements that don’t have them by default, IE5+ does not. Therefore, for maximum cross-browser com- patibility, use this method only to locate elements that have NAME attributes defined for them by default, such as form control elements. If the element does not exist in the document, the method returns an array of zero length. For the most part, you are best served by using IDs on elements and the getElementById() method to unearth references to individual objects. But some elements, especially the INPUT element of type radio, use the NAME attribute to group elements together. In that case, a call to getElementsByName() returns an array of all elements that share the name — facilitating perhaps a for loop that inspects the checked property of a radio button group. Thus, instead of using the old-fashioned (although entirely backward compatible) approach by way of the containing form object var buttonGroup = document.forms[0].radioGroupName you can go more directly: var buttonGroup = document.getElementsByName(radioGroupName) In the latter case, you operate independently of the containing form object’s index number or name. This assumes, of course, that a group name is not shared elsewhere on the page. Example on the CD Related Items: document.getElementsById(), getElementsByTagName() methods. On the CD-ROM On the CD-ROM document.getElementsByName() 390 Part III ✦ Document Objects Reference getSelection() Returns: String. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ Many Web browser users aren’t aware that they can select and copy body text in a document for pasting into other application documents. Even so, NN4+ offers a scripted way of capturing the text selected by a user in a page. The document. getSelection() method returns the string of text selected by the user. If nothing is selected, an empty string is the result. Returned values consist only of the visible text on the page and not the underlying HTML or style of the text. The IE4+ equivalent involves the document.selection property, which returns an IE selection object (not implemented in IE5/Mac). To derive the text from this object, you must create a TextRange object from it and then inspect the text property: var selectedText = document.selection.createRange().text Example on the CD with Listing 18-15 Related Items: document.selection property. handleEvent(event) Returns: Nothing. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ When you explicitly capture NN4 events in the window, document, or layer object (by invoking the captureEvents() method for that object), you can control where the events go after their initial capture. To let an event continue to its original target (for example, a button that is clicked by a user), you use the routeEvent() method. But if you want to redirect an event (or class of events) to a particular event handler elsewhere in the document, use the handleEvent() method. See the discussion of the handleEvent() method for the window object in Chapter 16. The behavior of the handleEvent() method for all objects is the same. Related Items: document.captureEvents(), document.releaseEvents(), document.routeEvent() methods; event object (Chapter 29). On the CD-ROM document.handleEvent() 391 Chapter 18 ✦ The Document and Body Objects open([“mimeType”] [, replace]) Returns: Nothing. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓✓ ✓ ✓ ✓✓✓ Opening a document is different from opening a window. In the case of a window, you’re creating a new object, both on the screen and in the browser’s memory. Opening a document, on the other hand, tells the browser to get ready to accept some data for display in the window named or implied in the reference to the document.open() method. (For example, parent.frames[1].document.open() may refer to a different frame in a frameset, whereas document.open() implies the current window or frame.) Therefore, the method name may mislead newcomers because the document.open() method has nothing to do with loading documents from the Web server or hard disk. Rather, this method is a prelude to sending data to a window via the document.write() or document.writeln() methods. In a sense, the document.open() method merely opens the valve of a pipe; the other methods send the data down the pipe like a stream, and the document.close() method closes that valve as soon as the page’s data has been sent in full. The document.open() method is optional because a document.write() method that attempts to write to a closed document automatically clears the old document and opens the stream for a new one. Whether or not you use the document.open() method, be sure to use the document.close() method after all the writing has taken place. An optional parameter to the document.open() method lets you specify the nature of the data being sent to the window. A MIME (Multipurpose Internet Mail Extension) type is a specification for transferring and representing multimedia data on the Internet (originally for mail transmission, but now applicable to all Internet data exchanges). You’ve seen MIME depictions in the list of helper applications in your browser’s preferences settings. A pair of data type names separated by a slash represent a MIME type (such as text/html and image/gif). When you specify a MIME type as a parameter to the document.open() method, you’re instructing the browser about the kind of data it is about to receive, so that it knows how to render the data. Common values that most browsers accept are text/html text/plain image/gif image/jpeg image/xbm If you omit the parameter, JavaScript assumes the most popular type, text/html — the kind of data you typically assemble in a script prior to writing to the window. The text/html type includes any images that the HTML references. Specifying any of the image types means that you have the raw binary representa- tion of the image that you want to appear in the new document — possible, but unlikely. document.open() 392 Part III ✦ Document Objects Reference Another possibility is to direct the output of a write() method to a plug-in. For the mimeType parameter, specify the plug-in’s MIME type (for example, application/ x-director for Shockwave). Again, the data you write to a plug-in must be in a form that it knows how to handle. The same mechanism also works for writing data directly to a helper application. IE3 does not accept any parameters for the document.open() method. IE4 accepts only the text/html MIME type parameter. NN4+ and IE5+ include a second, optional parameter to the method: replace. This parameter does for the document.open() method what the replace() method does for the location object. For document.open(), it means that the new document you are about to write replaces the previous document in the win- dow or frame from being recorded to that window or frame’s history. Avoid document.open() entirely for NN2 in the same window or frame as the one containing the script that invokes the document.open() method. Attempting to reopen the script’s own document with this method in Navigator 2 usually leads to a crash of the browser. Example on the CD Related Items: document.close(), document.clear(), document.write(), document.writeln() methods. queryCommandEnabled(“commandName”) queryCommandIndterm(“commandName”) queryCommandCommandState(“commandName”) queryCommandSupported(“commandName”) queryCommandText(“commandName”) queryCommandValue(“commandName”) Returns: Various values. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ These six methods (not implemented in IE5/Mac) lend further support to the execCommand() method for document and TextRange objects. If you choose to use On the CD-ROM Tip Note document.queryCommandEnabled() 393 Chapter 18 ✦ The Document and Body Objects the execCommand() method to achieve some stylistic change on a text selection, you can use some of these query methods to make sure the browser supports the desired command and to retrieve any returned values. Table 18-5 summarizes the purpose and returned values for each of the methods. Table 18-5 IE Query Commands queryCommand Returns Description Enabled Boolean Reveals whether the document or TextRange object is in a suitable state to be invoked. Indterm Boolean Reveals whether the command is in an indeterminate state. CommandState Boolean | null Reveals whether the command has been completed (true), is still working (false), or is in an indeterminate state (null). Supported Boolean Reveals whether the command is supported in the current browser. Text String Returns any text that may be returned by a command. Value Varies Returns whatever value (if any) is returned by a command. Because the execCommand() method cannot be invoked on a page while it is still loading, any such invocations that may collide with the loading of a page should check with queryCommandEnabled() prior to invoking the command. Validating that the browser version running the script supports the desired command (especially for commands that have been introduced after IE4) is also a good idea. Therefore, you may want to wrap any command call with the following conditional structure: if (queryCommandEnabled(commandName) && queryCommandSupported(commandName)) { } When using a command to read information about a selection, use the queryCommandText() or queryCommandValue() methods to catch that informa- tion (recall that the execCommand() method itself returns a Boolean value regard- less of the specific command invoked). Example on the CD Related Items: TextRange object (Chapter 19); execCommand() method. On the CD-ROM document.queryCommandEnabled() 394 Part III ✦ Document Objects Reference recalc([allFlag]) Returns: Nothing. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ IE5 introduced the concept of dynamic properties. With the help of the setExpression() method of all elements and the expression() style sheet value, you can establish dependencies between object properties and potentially dynamic properties, such as a window’s size or a draggable element’s location. After those dependencies are established, the document.recalc() method causes those dependencies to be recalculated — usually in response to some user action, such as resizing a window or dragging an element. The optional parameter is a Boolean value. The default value, false, means that the recalculations are performed only on expressions for which the browser has detected any change since the last recalculation. If you specify true, however, all expressions are recalculated whether they have changed or not. Example on the CD Related Items: getExpression(), removeExpression(), setExpression() methods (Chapter 15). releaseEvents(eventTypeList) Returns: Nothing. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ If your NN4 scripts have enabled event capture for the document object (or window or layer, for that matter), you can turn off that capture with the releaseEvents() method. This method does not inhibit events from reaching their intended target. In fact, by releasing capture from a higher object, released events don’t bother stopping at those higher objects anymore. See the discussion of the releaseEvents() method for the window object in Chapter 16. The behavior of the releaseEvents() method for all objects is the same. Related Items: document.captureEvents(), document.routeEvent() methods. On the CD-ROM document.releaseEvents() 395 Chapter 18 ✦ The Document and Body Objects routeEvent(event) Returns: Nothing. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ If you turn on NN4 event capturing in the window, document, or layer object (via their respective captureEvents() methods), the event handler you assign to those events really captures those events, preventing them from ever reaching their intended targets. For some page designs, this capturing is intentional, for it allows the higher-level object to handle all events of a particular type. But if your goal is to perform some preprocessing of events before they reach their destination, you need a way to pass that event along its regular path, which is what the routeEvent() method is for. See the discussion of the routeEvent() method for the window object in Chapter 16. The behavior of the routeEvent() method for all objects is the same. Related Items: document.captureEvents(), document.releaseEvents() methods. write(“string1” [,”string2” [, “stringn”]]) writeln(“string1” [,”string2” [, “stringn”]]) Returns: Boolean true if successful. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓✓ ✓ ✓ ✓✓✓ Both of these methods send text to a document for display in its window. The only difference between the two methods is that document.writeln() appends a carriage return to the end of the string it sends to the document. This carriage return is helpful for formatting source code when viewed through the browser’s source view window. For new lines in rendered HTML that is generated by these methods, you must still write a <BR> to insert a line break. Not all browsers and versions display the source code that is dynamically gener- ated by a client-side script when you attempt to view the source. In NN3 and NN4, the browser frequently shows the source code of such a page to have a wysiwyg: protocol, meaning that the document exists only in memory. Don’t fool yourself into believing that this is a way to hide scripts from nosey visitors. Other browsers or versions (perhaps on a different operating system) are able to view the ren- dered source without any problem. Plus, a browser with scripting turned off is able to view the page that dynamically generated the code in the first place. See the section “Hiding scripts entirely?” in Chapter 13. Note document.write() 396 Part III ✦ Document Objects Reference A common, incorrect conclusion that many JavaScript newcomers make is that these methods enable a script to modify the contents of an existing document, which is not true. As soon as a document has loaded into a window (or frame), the only fully backward compatible text that you can modify without reloading or rewriting the entire page is the content of text and TEXTAREA objects. In IE4+, you can modify HTML and text via the innerHTML, innerText, outerHTML, and outerText properties of any element. For NN6 and IE5+, you can modify an ele- ment’s text by setting its nodeValue or innerHTML properties; strict adherence to the W3C DOM requires creating and inserting or replacing new elements, as described in Chapter 15. The two safest ways to use the document.write() and document.writeln() methods are to ✦ Write some or all of the page’s content by way of scripts embedded in the document ✦ Send HTML code either to a new window or to a separate frame in a multi- frame window For the first case, you essentially interlace script segments within your HTML. The scripts run as the document loads, writing whatever scripted HTML content you like. This task is exactly what you did in script1.htm in Chapter 3. This task is also how you can have one page generate browser-specific HTML when a particular class of browser requires unique syntax. In the latter case, a script can gather input from the user in one frame and then algorithmically determine the layout and content destined for another frame. The script assembles the HTML code for the other frame as a string variable (including all necessary HTML tags). Before the script can write anything to the frame, it can optionally open the layout stream (to close the current document in that frame) with the parent.frameName.document.open() method. In the next step, a parent.frameName.document.write() method pours the entire string into the other frame. Finally, a parent.frameName.document.close() method ensures that the total data stream is written to the window. Such a frame looks just the same as if it were created by a source document on the server rather than on the fly in memory. The document object of that window or frame is a full citizen as a stan- dard document object. You can, therefore, even include scripts as part of the HTML specification for one of these temporary HTML pages. NN2 has some nasty bugs when you use document.write() to write to the cur- rent window, but in NN3+ and IE3+, you can write to the current window without problems. Even so, you should be prepared for the consequences. After an HTML document (containing the script that is going to do the writing) loads completely, the page’s incoming stream closes automatically. If you then attempt to apply a series of document.write() statements, the first document.write() method com- pletely removes all vestiges of the original document. That includes all of its objects and scripted variable values. Therefore, if you try to assemble a new page with a series of document.write() statements, the script and variables from the original page will be gone before the second document.write() statement executes. To get around this potential problem, assemble the content for the new screen of content as one string variable and then pass that variable as the parameter to a single document.write() 397 Chapter 18 ✦ The Document and Body Objects document.write() statement. Also be sure to include a document.close() state- ment in the next line of script. Assembling HTML in a script to be written via the document.write() method often requires skill in concatenating string values and nesting strings. A number of JavaScript String object shortcuts facilitate the formatting of text with HTML tags (see Chapter 34 for details). If you are writing to a different frame or window, you are free to use multiple document.write() statements if you like. Whether your script sends lots of small strings via multiple document.write() methods or assembles a larger string to be sent via one document.write() method depends partly on the situation and partly on your own scripting style. From a performance standpoint, a fairly standard pro- cedure is to do more preliminary work in memory and place as few I/O (input/out- put) calls as possible. On the other hand, making a difficult-to-track mistake is easier in string concatenation when you assemble longer strings. My personal pref- erence is to assemble longer strings, but you should use the system that’s most comfortable for you. You may see another little-known way of passing parameters to these methods. Instead of concatenating string values with the plus ( +) operator, you can also bring string values together by separating them with commas. For example, the following two statements produce the same results: document.write(“Today is “ + new Date()) document.write(“Today is “,new Date()) Neither form is better than the other, so use the one that feels more comfortable to your existing programming style. Dynamically generating scripts requires an extra trick, especially in NN. The root of the problem is that if you try code, such as document. write(“<SCRIPT></SCRIPT>”), the browser interprets the end script tag as the end of the script that is doing the writing. You have to trick the browser by sep- arating the end tag into a couple of components. Escaping the forward slash also helps. For example, if you want to load a different .js file for each class of browser, the code looks similar to the following: // variable ‘browserVer’ is a browser-specific string and // ‘page’ is the HTML your script is accumulating for document.write() page += “<SCRIPT LANGUAGE=’JavaScript’ SRC=’” + browseVer + “.js’><” + “\/SCRIPT>” Using the document.open(), document.write(), and document.close() methods to display images in a document requires some small extra steps. First, any URL assignments that you write via document.write() must be complete (not relative) URL references (especially for users of Navigator 2). Alternatively, you can write the <BASE> tag for the dynamically generated page so that its HREF attribute value matches that of the file that is writing the page. Note document.write() . scripts entirely?” in Chapter 13. Note document.write() 396 Part III ✦ Document Objects Reference A common, incorrect conclusion that many JavaScript newcomers make is that these methods enable a. or assembles a larger string to be sent via one document.write() method depends partly on the situation and partly on your own scripting style. From a performance standpoint, a fairly standard. document.getElementsById(), getElementsByTagName() methods. On the CD-ROM On the CD-ROM document.getElementsByName() 390 Part III ✦ Document Objects Reference getSelection() Returns: String. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2