358 Part III ✦ Document Objects Reference Extra batches You may design a site that needs more than 20 cookies for a given domain. For example, in a shopping site, you never know how many items a customer may load into the shopping cart cookie. Because each named cookie stores plain text, you can create your own text- based data structures to accommodate multiple pieces of information per cookie. (But also watch out for a practical limit of 2,000 characters per name/value pair within the 4,000 character maximum for any domain’s combined cookies.) The trick is determining a delimiter character that won’t be used by any of the data in the cookie. In Decision Helper (in Chapter 55), for example, I use a period to separate multiple integers stored in a cookie. With the delimiter character established, you must then write functions that con- catenate these “subcookies” into single cookie strings and extract them on the other side. It’s a bit more work, but well worth the effort to have the power of persistent data on the client. Example on the CD Related Items: String object methods (Chapter 34). defaultCharset Value: String Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ The defaultCharset property reveals the character set used by the browser to render the current document. You can find possible values for this property at ftp://ftp.isi.edu/in-notes/iana/assignments/character-sets Each browser and operating system has its own default character set. Values may also be set via a <META> tag. The difference between the defaultCharset and charset properties is not clear, especially because both are read/write (although modifying the defaultCharset property has no visual effect on the page). However, if your scripts temporarily modify the charset property, you can use the defaultCharset property to return to the original character set: document.charset = document.defaultCharset Example on the CD Related Items: charset, characterSet properties. On the CD-ROM On the CD-ROM document.defaultCharset 359 Chapter 18 ✦ The Document and Body Objects designMode Value: String Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ The designMode property is applicable only when IE5 technology is being used as a component in another application. More information can be found at http:// msdn.microsoft.com/workshop/browser/default.asp . The property controls whether the browser module is being used for HTML editing. Modifying the prop- erty from within a typical HTML page in the IE5 browser has no effect. doctype Value: DocumentType object reference Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ The doctype property comes from the W3C Core DOM and returns a DocumentType object — a representation of the DTD information for the document. In IE5.5 and NN6, the DocumentType object (even if one is not explicitly defined in the source code) is the first child node of the root document node (and is thus a sibling to the HTML element). As of NN6, only a couple of properties of this still-evolving W3C DOM specifica- tion are implemented. Table 18-2 shows the typical DocumentType object property list and values for a generic HTML page. Future DOM specifications will allow these properties to be read/write. Table 18-2 DocumentType Object in NN6 Property Value entities null internalSubset (empty) name HTML notations null publicId -//W3C//DTD HTML 3.2 Final//EN systemId (empty) Related Items: Node object (Chapter 14). document.doctype 360 Part III ✦ Document Objects Reference documentElement Value: HTML or XML element object reference Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ The documentElement property returns a reference to the HTML (or XML) ele- ment object that contains all of the content of the current document. The naming of this property is a bit misleading, because the root document node is not an ele- ment, but its only child node is the HTML (or XML) element for the page. At best, you can think of this property as providing scripts with an “element face” to the document object and document node associated with the page currently loaded in the browser. Example on the CD Related Items: ownerDocument property (Chapter 15). domain Value: String Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ ✓✓✓ Security restrictions can get in the way of sites that have more than one server at their domain. Because some objects, especially the location object, prevent access to properties of other servers displayed in other frames, legitimate access to those properties are blocked. For example, it’s not uncommon for popular sites to have their usual public access site on a server named something such as www.popular.com. If a page on that server includes a front end to a site search engine located at search.popular.com, visitors who use browsers with these security restrictions are denied access. To guard against that eventuality, a script in documents from both servers can instruct the browser to think both servers are the same. In the preceding example, you would set the document.domain property in both documents to popular.com. Without specifically setting the property, the default value includes the server name as well, thus causing a mismatch between host names. Before you start thinking that you can spoof your way into other servers, be aware that you can set the document.domain property only to servers with the same domain (following the “two-dot” rule) as the document doing the setting. On the CD-ROM document.domain 361 Chapter 18 ✦ The Document and Body Objects Therefore, documents originating only from xxx.popular.com can set their document.domain properties to popular.com server. Related Items: window.open() method; window.location object; security (Chapter 46). embeds Value: Array of EMBED element objects Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ ✓✓✓ Whenever you want to load data that requires a plug-in application to play or dis- play, you use the <EMBED> tag. The document.embeds property is merely one way to determine the number of such tags defined in the document: var count = document.embeds.length For controlling those plug-ins in Navigator, you can use the LiveConnect technol- ogy, described in Chapter 44. Related Items: EMBED element object (Chapter 32). expando Value: Boolean Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ Microsoft calls any custom property that is not a native property of the docu- ment object an expando property. By default, most objects in recent generations of browsers allow scripts to add new properties of objects as a way to temporarily store data without explicitly defining global variables. For example, if you want to maintain an independent counter of how often a function is invoked, you can create a custom property of the document object and use it as the storage facility: document.counter = 0 IE4+ lets you control whether the document object is capable of accepting expando properties. The default value of the document.expando property is true, thus allowing custom properties. But the potential downside to this permissive- ness, especially during the page construction phase, is that a misspelled native property name is gladly accepted by the document object. You may not be aware of why the title bar of the browser window doesn’t change when you assign a new string to the document.Title property (which, in the case-sensitive world of JavaScript, is distinct from the native document.title property). document.expando 362 Part III ✦ Document Objects Reference Example on the CD Related Items: prototype property of custom objects (Chapter 41). fgColor See alinkColor. fileCreatedDate fileModifiedDate fileSize Value: String, Integer (fileSize) Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ These three IE-specific properties return information about the file that holds the current document. Two of the properties (not implemented in IE5/Mac) reveal the dates on which the current document’s file was created and modified. For an unmodified file, its creation and modified dates are the same. The fileSize property reveals the number of bytes of the file. Date values returned for the first two properties are formatted differently between IE4 and IE5. The former provides a full readout of the day and date; the lat- ter in a format similar to mm/dd/yyyy. Note, however, that the values contain only the date and not the time. In any case, you can use the values as the parameter to a new Date() constructor function. You can then use date calculations for such information as the number of days between the current day and the most recent modification. Not all servers may provide the proper date or size information about a file or in a format that IE can interpret. Test your implementation on the deployment server to ensure compatibility. Also, be aware that these properties can be read only for a file that is loaded in the browser. JavaScript by itself cannot get this information about files that are on the server but not loaded in the browser. IE5.5 exposes a property called fileUpdatedDate, but the property does not return any data. This property may be a phantom property left over from a prere- lease version. Example on the CD with Listing 18-4 Related Items: lastModified property. On the CD-ROM On the CD-ROM document.fileCreatedDate 363 Chapter 18 ✦ The Document and Body Objects forms Value: Array Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓✓ ✓ ✓ ✓✓✓ As I show in Chapter 23, which is dedicated to the form object, an HTML form (anything defined inside a <FORM> </FORM> tag pair) is a JavaScript object unto itself. You can create a valid reference to a form according to its name (assigned via a form’s NAME attribute). For example, if a document contains the following form definition <FORM NAME=”phoneData”> input item definitions </FORM> your scripts can refer to the form object by name: document.phoneData However, a document object also tracks its forms in another way: as an array of Form objects. The first item of a document.forms array is the form that loaded first (it was first from the top of the HTML code). If your document defines one form, the forms property is an array one entry in length; with three separate forms in the document, the array is three entries long. Use standard array notation to reference a particular form from the document.forms array. For example, the first form in a document (the “zeroth” entry of the document.forms array) is referenced as document.forms[0] Any of the form object’s properties or methods are available by appending the desired property or method name to the reference. For example, to retrieve the value of an input text field named homePhone from the second form of a document, the reference you use is document.forms[1].homePhone.value One advantage to using the document.forms property for addressing a form object or element instead of the actual form name is that you may be able to gener- ate a library of generalizable scripts that know how to cycle through all available forms in a document and hunt for a form that has some special element and prop- erty. The following script fragment (part of a repeat loop described more fully in Chapter 39) uses a loop-counting variable (i) to help the script check all forms in a document: for (var i = 0; i < document.forms.length; i++) { if (document.forms[i]. ) { statements } } document.forms 364 Part III ✦ Document Objects Reference One more variation on forms array references lets you substitute the name of a form (as a string) for the forms array index. For example, the form named phoneData can be referenced as document.forms[“phoneData”] If you use a lot of care in assigning names to objects, you will likely prefer the document.formName style of referencing forms. In this book, you see both indexed array and form name style references. The advantage of using name references is that even if you redesign the page and change the order of forms in the document, references to the named forms will still be valid, whereas the index numbers of the forms will have changed. See also the discussion in Chapter 23 of the form object and how to pass a form’s data to a function. Example on the CD with Listing 18-5 Related Items: form object (Chapter 23). frames Value: Array Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ The document.frames property is similar to the window.frames property, but its association with the document object may seem a bit illogical at times. The objects contained by the array returned from the property are window objects, which means they are the window objects of any FRAME elements (from a frameset- ting document) or IFRAME elements (from a plain HTML document) defined for the document. Distinguishing the window objects from the element objects is impor- tant. Window objects have different properties and methods than the FRAME and IFRAME element objects. The latter’s properties typically represent the attributes for those element’s tags. If a document contains no IFRAME elements, the frames array length is zero. While you can access an individual frame object via the typical array syntax (for example, document.frames[0]), you can also use alternate syntax that Microsoft provides for collections of objects. The index number can also be placed inside parentheses, as in document.frames(0) Moreover, if the frames have values assigned to their NAME attributes, you can use the name (in string form) as a parameter: document.frames(“contents”) On the CD-ROM document.frames 365 Chapter 18 ✦ The Document and Body Objects And if the collection of frames has more than one frame with the same name, you must take special care. Using the duplicated name as a parameter forces the refer- ence to return a collection of frame objects that share that name. Or, you can limit the returned value to a single instance of the duplicate-named frames by specifying an optional second parameter indicating the index. For example, if a document has two IFRAME elements with the name contents, a script could reference the second window object as document.frames(“contents”, 1) For the sake of cross-browser compatibility, my preference for referencing frame window objects is via the window.frames property. Example on the CD Related Items: window.frames property. height width Value: Integer Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ The height and width properties of the NN4+ document object provide the pixel dimensions of the content within the current window (or frame). If the docu- ment’s content is smaller than the size of the browser’s content region, the dimen- sions returned by these properties include the blank space to the right and/or bottom edges of the content area of the window. But if the content extends beyond the viewable edges of the content region, the dimensions include the unseen con- tent as well. The corresponding measures in IE4+ are the document.body. scrollHeight and document.body.scrollWidth properties. Example on the CD Related Items: document.body.scrollHeight, document.body.scrollWidth properties. On the CD-ROM On the CD-ROM document.height 366 Part III ✦ Document Objects Reference ids Value: Array Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ The NN4-specific ids property is used in the browser’s alternative, JavaScript- based style sheet syntax. Deployment of JavaScript style sheets is exceedingly rare. In some ways, the document.ids property behaves similarly to the IE4+ document. all property, but document.ids cannot be used in regular scripts to access ele- ment objects. Related Items: tags property. images Value: Array Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓(✓) ✓✓✓ With images treated as first-class objects beginning with NN3 and IE4 (and IE ver- sion 3.01 on the Mac), it’s only natural for a document to maintain an array of all the image tags defined on the page (just as it does for links and anchors). The prime importance of having images as objects is that you can modify their content (the source file associated with the rectangular space of the image) on the fly. You can find details about the image object in Chapter 22. Use image array references to pinpoint a specific image for retrieval of any image property or for assigning a new image file to its src property. Image arrays begin their index counts with 0: The first image in a document has the reference document.images[0]. And, as with any array object, you can find out how many images the array contains by checking the length property. For example: var imageCount = document.images.length Images can also have names, so if you prefer, you can refer to the image object by its name, as in var imageLoaded = document.imageName.complete or var imageLoaded = document.images[imageName].complete The document.images array is a useful guide to knowing whether a browser supports swappable images. Any browser that treats an IMG element as an object always forms a document.images array in the page. If no images are defined in the page, the array is still there, but its length is zero. The array’s existence, however, is document.images 367 Chapter 18 ✦ The Document and Body Objects the clue about image object compatibility. Because the document.images array evaluates to an array object when present, the expression can be used as a condi- tion expression for branching to statements that involve image swapping: if (document.images) { // image swapping or precaching here } Earlier browsers that don’t have this property evaluate document.images as undefined and thus the condition is treated as a false value. Example on the CD Related Items: Image object (Chapter 22). implementation Value: Object Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ The Core W3C DOM defines the document.implementation property as an avenue to let scripts find out what DOM features (that is, modules of the DOM stan- dard) are implemented for the current environment. While the object returned by the property (a DOMImplementation object) has no properties, it has a method, hasFeature(), which lets scripts find out, for example, whether the environment supports HTML or just XML. The first parameter of the hasFeature() method is the feature in the form of a string. The second parameter is a string form of the version number. The method returns a Boolean value. A section of the W3C DOM specification, called “Conformance,” governs the module names (the standard also allows browser-specific features to be tested via the hasFeature() method). Module names include strings such as HTML, XML, MouseEvents, and so on. Version numbering for W3C DOM modules corresponds to the W3C DOM level. Thus, the version for the XML DOM module in DOM Level 2 is known as 2.0. Note that versions refer to DOM modules and not, for instance, the separate HTML standard. NN6 reports that it conforms to many modules defined in the W3C DOM Level 2, as shown in Table 18-3. But the indicated support may be misleading. According to the W3C standard, conformance for a module and version should indicate support for “all the interfaces for that module and the associated semantics.” In some cases, however, NN6 has merely reserved placeholders for objects, properties, and meth- ods that are not yet implemented. As a result, it is risky to use the hasFeature() method as a substitute for object detection in scripts. For now, you can trust the reported conformance only as a coarse indication of feature support. On the CD-ROM document.implementation . document.Title property (which, in the case-sensitive world of JavaScript, is distinct from the native document.title property). document.expando 362 Part III ✦ Document Objects Reference Example on the. ✓ The NN4-specific ids property is used in the browser’s alternative, JavaScript- based style sheet syntax. Deployment of JavaScript style sheets is exceedingly rare. In some ways, the document.ids. 358 Part III ✦ Document Objects Reference Extra batches You may design a site that needs more than 20