598 Part III ✦ Document Objects Reference Listing 26-2 (continued) var lang = (document.forms[0].geekLevel[0].checked) ? “plain” : “hard” // empty options from list while (listObj.options.length) { listObj.options.remove(0) } // create new option object for each entry for (var i = 0; i < choice.value; i++) { newOpt = document.createElement(“OPTION”) newOpt.text = (lang == “plain”) ? plainList[i] : hardList[i] listObj.options.add(newOpt) } listObj.options[0].selected = true } } Modifying SELECT options (W3C DOM) Yet another approach is possible in browsers that closely adhere to the W3C DOM Level 2 standard. In NN6, for example, you can use the add() and remove() methods of the SELECT element object. They work very much like the same-named methods for the options array in IE4+, but these are methods of the SELECT ele- ment object itself. The other main difference between the two syntaxes is that the NN6 add() method does not use the index value as the second parameter but rather a reference to the OPTION element object before which the new option is inserted. The second parameter is required, so to simply append the new item at the end of the current list, supply null as the parameter. Listing 26-3 shows the W3C-compatible version of the SELECT element modification scripts shown in Listings 26-1 and 26-2. I highlight source code lines in bold that exhibit differences between the IE4+ and W3C DOM versions. Listing 26-3: Modifying SELECT Options (NN6+) // change color language set function setLang(which) { var listObj = document.forms[0].colors var newOpt // filter out old IE browsers if (listObj.type) { // find out if it’s 3 or 6 entries var listLength = listObj.length // save selected index var currSelected = listObj.selectedIndex // replace individual existing entries for (var i = 0; i < listLength; i++) { newOpt = document.createElement(“OPTION”) newOpt.text = (which == “plain”) ? plainList[i] : hardList[i] SELECT 599 Chapter 26 ✦ Select, Option, and FileUpload Objects listObj.remove(i) listObj.add(newOpt, listObj.options[i]) } listObj.selectedIndex = currSelected } } // create entirely new options list function setCount(choice) { var listObj = document.forms[0].colors var newOpt // filter out old browsers if (listObj.type) { // get language setting var lang = (document.forms[0].geekLevel[0].checked) ? “plain” : “hard” // empty options from list while (listObj.options.length) { listObj.remove(0) } // create new option object for each entry for (var i = 0; i < choice.value; i++) { newOpt = document.createElement(“OPTION”) newOpt.text = (lang == “plain”) ? plainList[i] : hardList[i] listObj.add(newOpt, null) } listObj.options[0].selected = true } } As with the IE version, the W3C version offers no specific benefit over the origi- nal, backward-compatible approach. Choose the most modern one that fits the types of browsers you need to support with your page. Properties length Value: Integer Read/Write (see text) NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ ✓ ✓ ✓✓✓ Like all JavaScript arrays, the options array has a length property of its own. But rather than having to reference the options array to determine its length, the SELECT object has its own length property that you use to find out how many items are in the list. This value is the number of options in the object. A SELECT object with three choices in it has a length property value of 3. SELECT.length 600 Part III ✦ Document Objects Reference In NN3+ and IE4+, you can adjust this value downward after the document loads. This is one way to decrease the number of options in a list. Setting the value to 0 causes the SELECT object to empty but not disappear. Example on the CD-ROM Related Item: options property. multiple Value: Boolean Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ The multiple property represents the MULTIPLE attribute setting for a SELECT element object. If the value is true, the element accepts multiple selections by the user (for example, Ctrl+clicking in Windows). If you want to convert a pop-up list into a multiple SELECT pick list, you must also adjust the size property to direct the browser to render a set number of visible choices in the list. Example on the CD-ROM Related Item: size property. options[index] Value: Array of OPTION element objects Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ ✓ ✓ ✓✓✓ You typically don’t summon this property by itself. Rather, it is part of a refer- ence to a specific option’s properties (or methods in later browsers) within the entire SELECT object. In other words, the options property is a kind of gateway to more specific properties, such as the value assigned to a single option within the list. In early versions of NN, displaying an alert that referenced the options array showed the HTML for the options. But more recent browsers simply return an indi- cation that the value is an object. In newer browsers (IE4+ and NN6+), you can reference individual options as sep- arate HTML element objects. These references do not require the reference to the On the CD-ROM On the CD-ROM SELECT.options[index] 601 Chapter 26 ✦ Select, Option, and FileUpload Objects containing FORM or SELECT element objects. For backward compatibility, however, I recommend you stick with the long references through the SELECT objects. I list the next several properties here in the SELECT object discussion because they are backward-compatible with all browsers, including browsers that don’t treat the OPTION element as a distinct object. Be aware that all properties shown here that include options[index] as part of their references are also properties of the OPTION element object in IE4+ and NN6+. Example on the CD-ROM Related Items: All options[index].property items. options[index].defaultSelected Value: Boolean Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ ✓ ✓ ✓✓✓ If your SELECT object definition includes one option that features the SELECTED attribute, that option’s defaultSelected property is set to true. The defaultSelected property for all other options is false. If you define a SELECT object that allows multiple selections (and whose SIZE attribute is greater than 1), however, you can define the SELECTED attribute for more than one option definition. When the page loads, all items with that attribute are preselected for the user (even in noncontiguous groups). Example on the CD-ROM Related Item: options[index].selected property. options[index].index Value: Integer Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ ✓ ✓ ✓✓✓ The index value of any single option in a SELECT object likely is a redundant value in your scripting. Because you cannot access the option without knowing the On the CD-ROM On the CD-ROM SELECT.options[index].index 602 Part III ✦ Document Objects Reference index anyway (in brackets as part of the options[index] array reference), you have little need to extract the index value. The value is a property of the item just the same. Example on the CD-ROM Related Item: options property. options[index].selected Value: Boolean Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ ✓ ✓ ✓✓✓ As mentioned earlier in the discussion of this object, better ways exist for deter- mining which option a user selects from a list than looping through all options and examining the selected property. An exception to that “rule” occurs when you set up a list box to enable multiple selections. In this situation, the selectedIndex property returns an integer of only the topmost item selected. Therefore, your script needs to look at the true or false values of the selected property for each option in the list and determine what to do with the text or value data. Example (with Listing 26-4) on the CD-ROM Related Items: options[index].text, options[index].value, selectedIndex properties. options[index].text Value: String Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ ✓ ✓ ✓✓✓ The text property of an option is the text of the item as it appears in the list. If you can pass that wording along with your script to perform appropriate tasks, this property is the one you want to extract for further processing. But if your process- ing requires other strings associated with each option, assign a VALUE attribute in the definition and extract the options[index].value property (see Listing 26-6). On the CD-ROM On the CD-ROM SELECT.options[index].text 603 Chapter 26 ✦ Select, Option, and FileUpload Objects Example (with Listing 26-5) on the CD-ROM Related Item: options[index].value property. options[index].value Value: String Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ ✓ ✓ ✓✓✓ In many instances, the words in the options list appear in a form that is conve- nient for the document’s users but inconvenient for the scripts behind the page. Rather than set up an elaborate lookup routine to match the selectedIndex or options[index].text values with the values your script needs, you can easily store those values in the VALUE attribute of each <OPTION> definition of the SELECT object. You can then extract those values as needed. You can store any string expression in the VALUE attributes. That includes URLs, object properties, or even entire page descriptions that you want to send to a parent.frames[index].document.write() method. Starting with IE4 and NN6, the SELECT element object itself has a value property that returns the value property of the selected option. But for backward compati- bility, be sure to use the longer approach shown in the following example. Example (with Listing 26-6) on the CD-ROM Related Item: options[index].text property. selectedIndex Value: Integer Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ ✓ ✓ ✓✓✓ When a user clicks a choice in a selection list, the selectedIndex property changes to a zero-based number corresponding to that item in the list. The first item has a value of 0. This information is valuable to a script that needs to extract the value or text of a selected item for further processing. On the CD-ROM On the CD-ROM SELECT.selectedIndex 604 Part III ✦ Document Objects Reference You can use this information as a shortcut to getting at a selected option’s prop- erties. To examine a SELECT object’s selected property, rather than cycling through every option in a repeat loop, use the object’s selectedIndex property to fill in the index value for the reference to the selected item. The wording gets kind of long; but from an execution standpoint, this methodology is much more efficient. Note, however, that when the SELECT object is a multiple-style, the selectedIndex property value reflects the index of only the topmost item selected in the list. To script the selection of a particular item, assign an integer value to the SELECT element object’s selectedIndex property, as shown in Listings 26-1 through 26-3. Example (with Listing 26-7) on the CD-ROM Related Item: options property. size Value: Integer Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ The size property represents the SIZE attribute setting for a SELECT element object. You can modify the integer value of this property to change the number of options that are visible in a pick list without having to scroll. Example on the CD-ROM Related Item: multiple property. type Value: String Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ ✓✓✓ Use the type property to help you identify a SELECT object from an unknown group of form elements. The precise string returned for this property depends on whether the SELECT object is defined as a single ( select-one) or multiple ( select-multiple) type. Related Item: form.elements property. On the CD-ROM On the CD-ROM SELECT.type 605 Chapter 26 ✦ Select, Option, and FileUpload Objects value Value: String Read/Write (see text) NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ The more recent browsers (and the W3C DOM) provide a value property for the SELECT element object. This property returns the string assigned to the VALUE attribute (or value property) of the currently selected OPTION element. If you do not assign a string to the attribute or property, the value property returns an empty string. For these browser generations, you can use this shortcut reference to the SELECT element object’s value property instead of the longer version that requires a reference to the selectedIndex property and the options array of the element object. If you assign a new string to this property (and that string does not match an existing option value), IE accepts the new value property and displays an empty item in the list. While this property is technically read/write also in NN6, assigning a string to this property does not override the string returned based on the user selection. Example on the CD-ROM Related Item: options[index].value property. Methods options[index].add(elementRef[, index]) options[index].remove() Returns: Nothing. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓ These two IE-specific methods belong to the options array property of a SELECT element object. See the discussion at the opening of the SELECT element object earlier in this chapter to see how to use these methods and their counter- parts in other browser versions and object models. On the CD-ROM SELECT.options[index].add() 606 Part III ✦ Document Objects Reference item(index) namedItem(“optionID”) Returns: OPTION element reference. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ The item() and namedItem() methods are Netscape-specific convenience meth- ods that access OPTION element objects nested inside a SELECT object. In a sense, they provide shortcuts to referencing nested options without having to use the options array property and the indexing within that array. The parameter for the item() method is an index integer value. For example, the following two statements refer to the same OPTION element object: document.forms[0].mySelect.options[2] document.forms[0].mySelect.item(2) If your script knows the ID of an OPTION element, then it can use the namedItem() method, supplying the string version of the ID as the parameter, to return a reference to that option element. Example on the CD-ROM Related Item: options property. Event handlers onChange NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ ✓ ✓ ✓✓✓ As a user clicks a new choice in a SELECT object, the object receives a change event that the onChange event handler can capture. In examples earlier in this sec- tion (Listings 26-6 and 26-7, for example), the action is handed over to a separate button. This design may make sense in some circumstances, especially when you use multiple SELECT lists or any list box. (Typically, clicking a list box item does not trigger any action that the user sees.) But for most pop-up menus, triggering the action when the user makes a choice is desirable. To bring a pop-up menu to life, add an onChange event handler to the <SELECT> def- inition. If the user makes the same choice as previously selected, the onChange event handler is not triggered. In this case, you can still trigger an action via the onClick event handler; but this event works for the SELECT object only in IE4+ and NN6+. On the CD-ROM SELECT.onChange 607 Chapter 26 ✦ Select, Option, and FileUpload Objects A bug in the Windows versions of Navigator 2 (only) causes the onChange event handler in SELECT objects to fail unless the user clicks outside the SELECT object. If your audience includes users of these browsers, then consider adding a special routine that employs document.write() to include a “do nothing” button next to the SELECT object. This button should entice the user to click out of the SELECT object. The onChange event handler fires at a click of that button (or any other location on the page). Example (with Listing 26-8) on the CD-ROM OPTION Element Object For HTML element properties, methods, and event handlers, see Chapter 15. Properties MethodsEvent Handlers defaultSelected form† label selected text value †See text input object (Chapter 25). Syntax Accessing OPTION object properties: (All) [window.]document.formName.selectName.options[index].property | method([parameters]) (All) [window.]document.formName.elements[index].options[index].property | method([parameters]) (All) [window.]document.forms[index].selectName.options[index].property | method([parameters]) (All) [window.]document.forms[“formName”].selectName. options[index].property | method([parameters]) (All) [window.]document.forms[“formName”].elements[index]. options[index].property | method([parameters]) (IE4+) [window.]document.all.elemID.property | method([parameters]) (IE5+/NN6+) [window.]document.getElementById(“elemID”).property | method([parameters]) (NN6) [window.]document.forms[index].selectName.item(index).property | method([parameters]) (NN6) [window.]document.forms[“formName”].selectName.namedItem(elemID). property | method([parameters]) On the CD-ROM Note OPTION . the On the CD-ROM On the CD-ROM SELECT.options[index].index 602 Part III ✦ Document Objects Reference index anyway (in brackets as part of the options[index] array reference), you have little need. see how to use these methods and their counter- parts in other browser versions and object models. On the CD-ROM SELECT.options[index].add() 606 Part III ✦ Document Objects Reference item(index) namedItem(“optionID”) Returns:. object. A SELECT object with three choices in it has a length property value of 3. SELECT.length 600 Part III ✦ Document Objects Reference In NN3+ and IE4+, you can adjust this value downward after