JavaScript Bible, Gold Edition part 54 ppsx

378 Part III ✦ Document Objects Reference URL See location. URLUnencoded Value: String Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ The document.URL property returns a URL-encoded string, meaning that non- alphanumeric characters in the URL are converted to URL-friendly characters (for example, a space becomes %20). You can always use the unescape() function on the value returned by the document.URL property, but the URLUnencoded property does that for you. If there are no URL-encoded characters in the URL, then both properties return identical strings. Related Items: document.URL property. vlinkColor See alinkColor. width See height. Methods captureEvents(eventTypeList) Returns: Nothing. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ In Navigator 4 only, the natural propagation of an event is downward from the window object, through the document object, and eventually reaching its target. For example, if you click a button, the click event first reaches the window object; then it goes to the document object; if the button is defined within a layer, the event also filters through that layer; eventually (in a split second) the event reaches the button, where an onClick event handler is ready to act on that click. The NN4 mechanism allows window, document, and layer objects to intercept events and process them prior to reaching their intended targets (or preventing them from reaching their destinations entirely). But for an outer container to grab an event, your script must instruct it to capture the type of event your application document.captureEvents() 379 Chapter 18 ✦ The Document and Body Objects is interested in preprocessing. If you want the document object to intercept all events of a particular type, use the document.captureEvents() method to turn that facility on. Event capture with different syntax has been standardized in the W3C DOM and is implemented in NN6. See the addEventListener() method in Chapter 15 for the W3C counterpart to the NN4 captureEvents() method. Also, see Chapter 29 for more details on the combination of event capture and event bubbling in the W3C DOM. The document.captureEvents() method takes one or more event types as parameters. An event type is a constant value built inside the NN4 Event object. One event type exists for every kind of event handler that you see in all of the docu- ment objects of NN4. The syntax consists of a reference to the Event object and the event name in all uppercase letters. For example, if you want the document to inter- cept all click events, the statement is document.captureEvents(Event.CLICK) For multiple events, add them as parameters, separated by the pipe (|) character: document.captureEvents(Event.MOUSEDOWN | Event.KEYPRESS) After the document object is set to capture an event type, it must have a function ready to deal with the event. For example, perhaps the function looks through all Event.MOUSEDOWN events and looks to see if the right mouse button is the one that triggers the event and what form element (if any) is the intended target. The goal is perhaps to display a pop-up menu (as a separate layer) for a right-click. If the click comes from the left mouse button, then the event is routed to its intended target. To associate a function with a particular event type captured by a document object, assign a function to the event. For example, to assign a custom doClickEvent() function to click events captured by the wdocument object, use the following statement: document.onclick=doClickEvent Notice that the function name is assigned only as a reference name, unlike an event handler within a tag. The function, itself, is like any function, but it has the added benefit of automatically receiving the event object as a parameter. To turn off event capture for one or more event types, use the document.releaseEvent() method. See Chapter 29 for details of working with NN4 events. Capturing events at the window, document, or layer level in NN4 does not always work the way you may want, which is especially true if your page contains tables. For example, capturing mouse events has no effect in the Windows version of NN4 unless the cursor is atop a cell border. Event capture works most reliably when a scriptable object has an event handler defined for it (even if the handler is an empty string), and the element is the target of the event (for example, you are about to type into a text field). For all other elements, event capture may simply not be captured at the document or window level. Note Note document.captureEvents() 380 Part III ✦ Document Objects Reference Example on the CD Related Items: document.handleEvent(), document.releaseEvents(), document.routeEvent() methods; parallel window object event methods. clear() Returns: Nothing. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓✓ ✓ ✓ ✓✓✓ Ever since NN2, the document.clear() method was intended to clear the cur- rent document from the browser window. This method is quite impractical, because you typically need some further scripts to execute after you clear the document, but if the scripts are gone, nothing else happens. In practice, the document.clear() method never did what it was supposed to do (and in earlier browsers easily caused browser crashes). I recommend against using document.clear(), including in preparation for generating a new page’s con- tent with document.write(). The document.write() method clears the original document from the window before adding new content. If you truly want to empty a window or frame, then use document.write() to write a blank HTML document or to load an empty HTML document from the server. Related Items: document.close(), document.write(), document.writeln() methods. close() Returns: Nothing. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓✓ ✓ ✓ ✓✓✓ Whenever a layout stream is opened to a window via the document.open() method or either of the document writing methods (which also open the layout stream), you must close the stream after the document is written. This causes the Layout:Complete and Done messages to appear in the status line (although you may experience some bugs in the status message on some platforms). The docu- ment closing step is very important to prepare the window for the next potential round of replenishment with new script-assembled HTML. If you don’t close the document, subsequent writing is appended to the bottom of the document. On the CD-ROM document.close() 381 Chapter 18 ✦ The Document and Body Objects Some or all of the data specified for the window won’t display properly until you invoke the document.close() method, especially when images are being drawn as part of the document stream. A common symptom is the momentary appearance and then disappearance of the document parts. If you see such behavior, look for a missing document.close() method after the last document.write() method. Example on the CD Related Items: document.open(), document.clear(), document.write(), document.writeln() methods. createAttribute(“attributeName”) Returns: Attribute object reference NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ The document.createAttribute() method generates an attribute node object (formally known as an Attr object in W3C DOM terminology) and returns a reference to the newly created object. Invoking the method assigns only the name of On the CD-ROM document.createAttribute() Fixing the Sticky Wait Cursor IE4+ frequently fails to restore the cursor to normal after document.write() and document.close() (and some other content-modifying scripts). The cursor stubbornly remains in the wait mode when, in truth, all processing has been completed. One, albeit ugly, workaround that I have found effective is to force an extra document.close() via a javascript: pseudo-URL (just adding another document.close() to your script doesn’t do the trick). For use within a frameset, the javascript: URL must be directed to the top of the frameset hierarchy, while the document.close() is aimed at the frame that had its content changed. For example, if the change is made to a frame named content, create a function, such as the following: function recloseDoc() { if (isIE) { top.location.href=”javascript:void (parent.content.document.close())” } } This assumes, of course, that you have browser-sniffing working in the script that sets the isIE global variable to true when the browser is running in IE. If you place this function in the framesetting document, scripts that modify the content frame can invoke this script after any operation that prevents the normal cursor from appearing. 382 Part III ✦ Document Objects Reference the attribute, so it is up to your script to assign a value to the object’s nodeValue property and then plug the new attribute into an existing element via that element’s setAttributeNode() method (described in Chapter 15). The following sequence generates an attribute that becomes an attribute of a TABLE element: var newAttr = document.createAttribute(“width”) newAttr.nodeValue = “80%” document.getElementById(“myTable”).setAttributeNode(newAttr) Attributes do not always have to be attributes known to the HTML standard, because the method also works for XML elements, which have custom attributes. Example on the CD Related Items: setAttributeNode() method (Chapter 15). createElement(“tagName”) Returns: Element object reference NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ The document.createElement() method generates an element object for what- ever HTML (or XML) tag name you pass as the parameter. This object is not offi- cially part of the current document object model because it has not yet been placed into the document. But this method is the way you begin assembling an element object that eventually gets inserted into the document. The returned value is a reference to the object. Properties of that object include all properties (set to default values) that the browser’s object model defines for that element object. Your scripts can then address the object via this reference to set the object’s properties. Typically you do this before the object is inserted into the document, especially because otherwise read-only properties can be modified before the element is inserted into the document. After the object is inserted into the document, the original reference (for exam- ple, a global variable used to store the value returned from the createElement() method) still points to the object, even while it is in the document and being dis- played for the user. To demonstrate this effect, consider the following statements that create a simple paragraph element containing a text node: var newText = document.createTextNode(“Four score and seven years ago ”) var newElem = document.createElement(“P”) newElem.id = “newestP” newElem.appendChild(newText) document.body.appendChild(newElem) On the CD-ROM document.createElement() 383 Chapter 18 ✦ The Document and Body Objects At this point, the new paragraph is visible in the document. But you can now modify, for example, the style of the paragraph by addressing either the element in the document object model or the variable that holds the reference to the object you created: newElem.style.fontSize = “20pt” or document.getElementById(“newestP”).style.fontSize = “20pt” The two references are inextricably connected and always point to the exact same object. Therefore, if you want to use a script to generate a series of similar elements (for example, a bunch of LI elements), then you can use createElement() to make the first one and set all properties that the items have in common. Then use cloneNode() to make a new copy, which you can then treat as a separate element (and probably assign unique IDs to each one). Scripting in the W3C DOM environment (to the extent that it is supported in both IE5 and NN6), you may rely on document.createElement() frequently to generate new content for a page or portion thereof (unless you prefer to use the convenience innerHTML property to add content in the form of strings of HTML). In a strict W3C DOM environment, creating new elements is not a matter of assembling HTML strings, but rather creating genuine element (and text node) objects. Example on the CD Related Items: document.createTextNode() method. createEventObject([eventObject]) Returns: event Object. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ The IE-specific createEventObject() method creates an event object, which can then be passed as a parameter to the fireEvent() method of any element object. The event object created by this event is just like an event object created by a user or system action. An optional parameter lets you base the new event on an existing event object. In other words, the properties of the newly created event object pick up all the properties of the event object passed as a parameter, which lets you then modify properties of your choice. If you provide no parameter to the method, then you must fill the essential properties manually. For more about the properties of an event object, see Chapter 29. On the CD-ROM document.createEventObject() 384 Part III ✦ Document Objects Reference Example on the CD Related Items: fireEvent() method (Chapter 15); event object (Chapter 29). createStyleSheet([“URL”[, index]]) Returns: styleSheet object reference. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ The IE-specific createStyleSheet() method creates a styleSheet object, a type of object that includes STYLE element objects as well as style sheets that are imported into a document via the LINK element. Thus you can dynamically load an external style sheet even after a page has loaded. Note that this method does not work in IE4 for the Macintosh. Unlike the other “create” methods entering W3C DOM usage, the createStyleSheet() method not only creates the style sheet, but it inserts the object into the document object model immediately. Thus, any style sheet rules that belong (or are assigned to) that object take effect on the page right away. If you’d rather create a style sheet and delay its deployment, you should use the createElement() method and element object assembly techniques. If you don’t specify any parameters to the method, an empty styleSheet object is created. It is assumed that you will then use styleSheet object methods, such as addRule() (not implemented in IE5/Mac) to add the details to the style sheet. To link in an external style sheet file, assign the file’s URL to the first parameter of the method. The newly imported style sheet is appended to the end of the docu- ment.styleSheets array of styleSheet objects. An optional second parameter lets you specify precisely where in the sequence of style sheet elements the newly linked style sheet should be inserted. A style sheet rule for any given selector is overridden by a style sheet for the same selector that appears later in the sequence of style sheets in a document. Example on the CD with Listing 18-13 Related Items: styleSheet object (Chapter 30). On the CD-ROM On the CD-ROM document.createStyleSheet() 385 Chapter 18 ✦ The Document and Body Objects createTextNode(“text”) Returns: Text node object. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ A text node is a W3C DOM object that contains body text without any HTML (or XML) tags, but is usually contained by (meaning, is a child of) an HTML (or XML) element. Without the IE innerText convenience property for modifying the text of an element, the W3C DOM relies on the node hierarchy of a document (NN6 exceeds the W3C DOM by providing an innerHTML property, which you can use to replace text in an element). To insert or replace text inside an HTML element in the W3C DOM way, you create the text node and then use methods of the parent element (for example, appendChild(), insertBefore(), and replaceChild(), all described in Chapter 15) to modify the document’s content. To generate a fresh text node, use document.createTextNode(). The sole parameter of the createTextNode() method is a string whose text becomes the nodeValue of the text node object returned by the method. You can also create an empty text node (passing an empty string) and assign a string to the nodeValue of the object later. As soon as the text node is present in the document object model, scripts can simply change the nodeValue property to modify text of an existing element. For more details on the role of text nodes in the W3C DOM, see Chapter 14. Example on the CD Related Items: document.createElement() method. elementFromPoint(x, y) Returns: Element object reference. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ The IE-specific elementFromPoint() method returns a reference to whatever element object occupies the point whose integer coordinates are supplied as parameters to the method. The coordinate plane is that of the document, whose top-left corner is at point 0,0. This coordinate plane can be very helpful in interac- tive designs that need to calculate collision detection between positioned objects or mouse events. On the CD-ROM document.elementFromPoint() 386 Part III ✦ Document Objects Reference When more than one object occupies the same point (for example, one element is positioned atop another), the element with the highest z-index value is returned. A positioned element always wins when placed atop a normal body-level element. And if multiple overlapping positioned elements have the same z-index value (or none by default), the element that comes last in the source code order is returned for the coordinate that they share in common. Example on the CD with Listing 18-14 Related Items: event.clientX, event.clientY properties; positioned objects (Chapter 31). execCommand(“commandName”[, UIFlag] [, param]) Returns: Boolean. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ IE4+ includes a large set of commands that are outside of the methods defined for objects in the object model. These commands are also accessible to program- mers who build an Internet Explorer ActiveX control into their applications. The execCommand() method (not implemented in IE5/Mac) is the JavaScript gateway to those commands. A series of related methods ( queryCommandEnable() and oth- ers) also facilitate management of these commands. The syntax for the execCommand() method requires at least one parameter, a string version of the command name. Command names are not case-sensitive. An optional second parameter is a Boolean flag to instruct the command to display any user interface artifacts that may be associated with the command. The default is false. For the third parameter, some commands require that an attribute value be passed for the command to work. For example, to set the font size of a text range, the syntax is myRange.execCommand(“FontSize”, true, 5) The execCommand() method returns Boolean true if the command is successful; false if not successful; undefined in IE5/Mac. Some commands can return values (for example, finding out the font name of a selection), but those are accessed through the queryCommandValue() method. Most of these commands operate on body text selections that are TextRange objects. As described in Chapter 19, a TextRange object must be created under script control. But a TextRange object can be done in response to a user selecting some text in the document. Because a TextRange object is independent of the ele- ment hierarchy (indeed, a TextRange can spread across multiple nodes), it cannot On the CD-ROM document.execCommand() 387 Chapter 18 ✦ The Document and Body Objects respond to style sheet specifications. Thus, many of the commands that can oper- ate on a TextRange object have to do with formatting or modifying the text. For a list of commands that work exclusively on TextRange objects, see the TextRange.execCommand() method in Chapter 19. While many of the commands intended for the TextRange also work when invoked from the document object, in this section the focus is on those commands that have scope over the entire document. Table 18-4 lists those few commands that work with the document. Also listed are many commands that work exclusively on text selections in the document, whether the selections are made manually by the user or with the help of the TextRange object (see Chapter 19). Table 18-4 document.execCommand() Commands Command Parameter Description Refresh None Reloads the page. SelectAll None Selects entire page content. Unselect None Unselects any page selection. BackColor Color String Encloses the current selection with a FONT element whose STYLE attribute sets the background-color style to the parameter value. CreateBookmark Anchor String Encloses the current selection (or text range) with an anchor element whose NAME attribute is set to the parameter value. CreateLink URL String Encloses the current selection with an A element whose HREF attribute is set to the parameter value. FontName Font Face(s) Encloses the current selection with a FONT element whose FACE attribute is set to the parameter value. FontSize Size String Encloses the current selection with a FONT element whose SIZE attribute is set to the parameter value. FontColor Color String Encloses the current selection with a FONT element whose COLOR attribute is set to the parameter value. Indent None Indents the current selection. JustifyCenter None Centers the current selection. JustifyFull None Full-justifies the current selection. JustifyLeft None Left-justifies the current selection. JustifyRight None Right-justifies the current selection. Outdent None Outdents the current selection. RemoveFormat None Removes formatting for the current selection. Continued document.execCommand() . especially when images are being drawn as part of the document stream. A common symptom is the momentary appearance and then disappearance of the document parts. If you see such behavior, look for. extra document.close() via a javascript: pseudo-URL (just adding another document.close() to your script doesn’t do the trick). For use within a frameset, the javascript: URL must be directed. DOM and is implemented in NN6. See the addEventListener() method in Chapter 15 for the W3C counterpart to the NN4 captureEvents() method. Also, see Chapter 29 for more details on the combination