selectNN 2 IE 3 DOM 1  

  

The select object reflects the select element. This element is a form control that contains option elements. Note that the innerHTML and innerText properties are not available on the Macintosh version of Internet Explorer 4. The shared disabled property is available for Netscape 6.

 
HTML Equivalent
 
<select>
 
Object Model Reference
 
[window.]document.formName.selectName
[window.]document.forms[i].elements[i]
[window.]document.getElementById("elementID")
 
Object-Specific Properties
 
dataFlddataSrcformlengthmultiplename
options[ ]selectedIndexsizetypevalue
 
Object-Specific Methods
 
add( )item( )namedItem( )remove( )
 
Object-Specific Event Handler Properties
 
HandlerNNIEDOM
onblur24n/a
onchange24n/a
onfocus24n/a
accessKeyNN n/a IE 4 DOM 1  

Read/Write  

This is single character key that either gives focus to an element (in some browsers) or activates a form control or link action. The browser and operating system determine if the user must press a modifier key (e.g., Ctrl, Alt, or Command) with the access key to activate the link. In Windows versions of IE 5 and later and Netscape 6, the Alt key is required and the key is not case-sensitive. For Macintosh versions of IE 5 and later and Netscape 6, the Ctrl modifier key is required to effect the action.

 

Although listed here as a widely shared property, that isn't strictly the case across all implementations. Netscape 6 (per the W3C DOM) recognizes this property only for the following elements: a, area, button, input, label, legend, and textarea. To this list, IE 4 adds applet, body, div, embed, isindex, marquee, object, select, span, table, and td (but removes label and legend). IE 5 adds every other renderable element, but with a caution. Except for input and other form-related elements, you must also assign a tabindex attribute or tabIndex property value to the IE 5 and later element (even if it's simply a value of zero for all) to let the accelerator key combination bring focus to the element. As of Version 7, Netscape does not alter UI behavior if a script changes the property's value.

 
Example
 
document.links[3].accessKey = "n";
 
Value

Single alphanumeric (and punctuation) keyboard character.

 
Default

Empty string.

blur( )NN 2 IE 3 DOM 1  

Removes focus from the current object, at which time the object's onblur event fires. Note that the range of elements capable of focus and blur (both the event and method) is limited in all browsers except for more recent versions of IE (see the shared tabindex attribute in Chapter 8). Most reliably for backward compatibility, apply the blur( ) method to blatantly focusable elements, such as text input and textarea elements. Assigning the attribute onfocus="this.blur( );" to a text input element, for instance, is a crude but effective backward-compatible way to largely disable a field for browsers that do not provide genuine element disabling.

 

Use blur( ) and focus( ) methods in moderation on the same page. You can inadvertently trigger endless loops of blurring and focusing if alert dialog boxes are involved along the way. Moreover, be aware that when you invoke the blur( ) method on one object, some other object (perhaps the window object) receives an onfocus event.

 
Parameters

None.

 
Returned Value

None.

dataFldNN n/a IE 4 DOM n/a  

Read/Write  

Used with IE data binding to associate a remote data source column name with the selectedIndex property of the select object. A datasrc attribute must also be set for the element. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source. Works only with text file data sources in IE 5/Mac.

 
Example
 
document.forms[0].mySelect.dataFld = "choice";
 
Value

Case-sensitive identifier of the data source column.

 
Default

None.

dataSrcNN n/a IE 4 DOM n/a  

Read/Write  

Used with IE data binding to specify the ID of the page's object element that loads the data source object for remote data access. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source. Works only with text file data sources in IE 5/Mac.

 
Example
 
document.forms[0].mySelect.dataSrc = "DBSRC3";
 
Value

Case-sensitive identifier of the data source.

 
Default

None.

disabledNN 6 IE 4 DOM 1  

Read/Write  

Specifies whether the element is available for user interaction. When set to true, the element cannot receive focus or be modified by the user, and it typically appears grayed out on the page. This property is available for all HTML element objects in IE 5.5 for Windows and later. For IE 4 and IE 5, it applies only to form controls, while Netscape 6 and later recognize the property for form controls and the style element object. A disabled form control's name/value pair is not submitted with its form.

 
Example
 
document.getElementById("myButton").disabled = true;
 
Value

Boolean value: true | false.

 
Default

false

focus( )NN 2 IE 3 DOM 1  

Gives focus from the current object, at which time the object's onfocus event fires. Note that the range of elements capable of focus and blur (both the event and method) is limited in all browsers except for more recent versions of IE (see the shared tabindex attribute in Chapter 8). Most reliably for backward compatibility, apply the focus( ) method to blatantly focusable elements, such as text input and textarea elements.

 

To give a text box focus and pre-select all the text in the box, use the sequence of focus( ) and select( ) methods on the element. If this sequence is to occur after windows change (such as after an alert dialog box closes), place the methods in a separate function, and invoke this function through the setTimeout( ) method following the alert( ) method for the dialog. This allows IE/Windows to sequence statement execution correctly.

 
Parameters

None.

 
Returned Value

None.

formNN 2 IE 3 DOM 1  

Read-only  

Returns a reference to the form element that contains the current element. When processing an event from this element, the event handler function automatically has access to the select element (as the event object's target or srcElement property). By reading the form property, the script can easily access other controls within the same form.

 
Example
 
var theForm = evt.srcElement.form;
 
Value

form element object reference.

 
Default

None.

lengthNN 2 IE 3 DOM 1  

Read/Write  

The number of option objects nested inside the select object. The value returned is the same as the select object options.length property, and can be safely used as a for loop maximum counter value to iterate through the nested option objects. The W3C DOM specifies that this property is read-only, but because the property has been read/write for some time in mainstream browsers, you can continue to adjust this value. By and large, the only modification made to this property, if at all, should be setting its value to zero to empty all options from the select object. Better still, if you are authoring for IE 5 and later or Netscape 6, use the select.remove( ) and select.add( ) methods to modify the contingent of option elements nested inside the select element.

 
Example
 
document.forms[0].mySelect.length = 0;
 
Value

Integer.

 
Default

None.

multipleNN 6 IE 4 DOM 1  

Read/Write  

Specifies whether the browser should render the select element as a list box and allow users to make multiple selections from the list of options. By default, the size property is set to the number of nested option elements, but the value may be overridden with the size property setting. To change a scrolling pick list to a popup menu, set the multiple property to false and the size property to 1. Users can select contiguous items by Shift-clicking on the first and last items of the group. To make discontiguous selections, Windows users must Ctrl-click on each item; Mac users must Command-click on each item. The multiple property has no effect when size is set to 1 to display a popup menu.

 
Example
 
if (document.entryForm.list3.multiple) {
    ...
}
 
Value

Boolean value: true | false.

 
Default

false

nameNN 2 IE 3 DOM 1  

Read/Write  

This is the identifier associated with the form control. The value of this property is submitted as one-half of the name/value pair when the form is submitted to the server. Names are hidden from user view, since control labels are assigned via other means, depending on the control type. Form control names may also be used by script references to the objects. Despite the modern standards' preference for the id attribute, many browsers still require that a control be assigned a name attribute to allow the control's value to be submitted.

 
Example
 
document.orderForm.payment.name = "credcard";
 
Value

Case-sensitive string identifier that follows the rules of identifier naming: it may contain no whitespace, cannot begin with a numeral, and should avoid punctuation except for the underscore character.

 
Default

None.

options[ ]NN 2 IE 3 DOM 1  

Read-only  

Returns an array of all option objects contained by the current element. Items in this array are indexed (zero-based) in source code order. For details on using this collection in a backward-compatible way for adding and removing option elements from a select element, see the options object. Loop through this collection in select elements set for multiple selections.

 
Example
 
var selVals = new Array( );
for (var i = 0; i < document.forms[0].mySelect.length; i++) {
    if (document.forms[0].mySelect.options[i].selected) {
        selVals[selVals.length] = document.forms[0].mySelect.options[i].value;
    }
}
 
Value

Array of option objects.

 
Default

None.

recordNumberNN n/a IE 4 DOM n/a  

Read-only  

Used with IE data binding, returns an integer representing the record within the data set that generated the element (i.e., an element whose content is filled via data binding). Values of this property can be used to extract a specific record from an Active Data Objects (ADO) record set (see recordset property). Although this property is defined for all IE element objects, the other properties related to data binding belong to a subset of elements.

 
Example
 
<script for="tableTemplate" event="onclick">
		    myDataCollection.recordset.absoluteposition = this.recordNumber;
		    ...
		</script>
 
Value

Integer.

 
Default

null

selectedIndexNN 2 IE 3 DOM 1  

Read/Write  

This is the zero-based integer of the option selected by the user. If the select element is set to allow multiple selections, the selectedIndex property returns the index of the first selected item (see the selected property). You can use this property to gain access to the value or text of the selected item, as shown in the example.

 

In recent browsers, if no option is selected, the selectedIndex property returns -1. Setting the value to -1 to deselect all items works as you'd expect in IE 5 and later for Windows. For Netscape 6, setting the property to -1 may not empty the displayed option, but it does effectively deselect all items for a submitted form.

 
Example
 
var list = document.forms[0].selectList;
var listText = list.options[list.selectedIndex].text;
 
Value

Integer.

 
Default

None.

sizeNN 6 IE 4 DOM 1  

Read/Write  

Controls the number of rows displayed in a scrolling pick list, reflecting the size attribute of the select element. When set to true, the multiple property overrides a size value set to fewer than the number of options. To change a scrolling pick list to a popup menu, set the multiple property to false and the size property to 1.

 
Example
 
document.forms[0].choices.size = 6;
 
Value

Integer.

 
Default

None.

tabIndexNN 6 IE 4 DOM 1  

Read/Write  

This is a number that indicates the sequence of this element within the tabbing order of all focusable elements in the document. Tabbing order follows a strict set of rules. Elements that have values other than zero assigned to their tabIndex properties are first in line when a user starts tabbing in a page. Focus starts with the element with the lowest tabIndex value and proceeds in order to the highest value, regardless of physical location on the page or in the document. If two elements have the same tabIndex values, the element that comes earlier in the document receives focus first. Next come all elements that either don't support the tabIndex property or have the value set to zero. These elements receive focus in the order in which they appear in the document.

 

The W3C DOM and Netscape 6 limit the tabIndex property to the following element objects: a, area, button, input, object, select, textarea. To this list, IE 4 adds applet, body, div, embed, isindex, marquee, span, table, and td. IE 5 adds every other renderable element. A negative value in IE (only) removes an element from tabbing order entirely.

 

Links and anchors cannot be tabbed to with the Mac version of IE 4, so the tabIndex property for a element objects is ignored in that version.

 
Example
 
document.getElementById("link3").tabIndex = 6;
 
Value

Integer.

 
Default

0

typeNN 3 IE 4 DOM 1  

Read-only  

Returns the type of form control element. A select object has two possible values, depending on whether the element is set to be a multiple-choice list. The value is returned in all lowercase letters. It may be necessary to cycle through all form elements in search of specific types to do some processing on (e.g., emptying all form controls of type "text" while leaving other controls untouched).

 

Note that Navigator 4 incorrectly reports a select object's type as select-multiple if the element's size attribute is set to any value larger than 1, even if the multiple attribute is not set. This is fixed in Netscape 6.

 
Example
 
if (document.forms[0].elements[3].type == "select-multiple") {
    ...
}
 
Value

Any of the following constants (as a string): button | checkbox | file | hidden | image | password | radio | reset | select-multiple | select-one | submit | text | textarea.

 
Default

Depends on value of multiple.

valueNN 6 IE 4 DOM 1  

Read/Write  

This is the current value associated with the form control that is submitted with the name/value pair for the element. All values are strings, but they may represent other kinds of data, including Boolean and numeric values. For browsers earlier than IE 4 and Netscape 6, scripts must retrieve the selected option's value by using the select object's selectedIndex property as an index into the options array, then inspect each option object's selected property to find the true one(s).

 
Example
 
if (document.forms[0].medium.value == "CD-ROM") {
    ...
}
 
Value

String.

 
Default

None.

add( )NN 6 IE 5 DOM 1  

add(newOptionElement[, positionIndex]) add(newOptionElement, optionElementReference)

  

Adds a new option element to the current select element. Unfortunately, IE and Netscape 6 don't agree on the parameter values for this method. While all browsers require a reference to a newly created option element (the value returned from a document.createElement("option") method is appropriate for that), the second parameter varies with browser. In IE, the second parameter is optional and supplies a numeric index to the existing option element; the new option is inserted in front of that element. With no second parameter, the new option is appended to the existing option elements. In Netscape 6 (which implements the W3C DOM recommendation from the unfinished HTML module), the second parameter is required. The parameter is either a reference to an existing option element (the new option is inserted before that referenced option) or null (the new option is appended to the existing options).

 
Parameters
 
  • Reference to an option element created by script, usually with the document.createElement( ) method.
  • Optional IE integer parameter signifying the existing nested option element in front of which the new option is to be inserted. Omitting this parameter causes the new option to be appended to the end of the options list.
  • Reference to an option element in front of which the new option is to be inserted. You may also use null to append the new option to the end of the option list.
 
Returned Value

None.

item( )NN n/a IE 5 DOM n/a  

item(index[, subindex])

  

Returns a single nested option object or collection of nested option objects corresponding to the element matching the index value (or, optionally, the index and subindex values).

 
Parameters
 
  • When the parameter is a zero-based integer, the returned value is a single element corresponding to the said numbered item in source code order (nested within the current element). When the parameter is a string, the returned value is a collection of elements with id properties that match that string.
  • If you specify a string value for the first parameter, you may use the second parameter to specify a zero-based integer to retrieve a specific element from the collection with id properties that match the first parameter's string value.
 
Returned Value

One object or collection (array) of objects. If there are no matches to the parameters, the returned value is null.

namedItem( )NN n/a IE 6 DOM n/a  

namedItem("ID")

  

Returns a single nested option object or collection of nested option objects corresponding to the element matching the parameter string value.

 
Parameters
 
  • The string that contains the same value as the desired element's id attribute.
 
Returned Value

One option object or collection (array) of option objects. If there are no matches to the parameters, the returned value is null.

remove( )NN 6 IE 5 DOM 1  

remove(positionIndex)

  

Deletes an option element from the current select element at the zero-based index position signified by the parameter value. In lieu of setting the select object's length property to zero, you can remove all existing options with a simple loop construction:

while (selectElemRef.length> 0) {
    selectElemRef.remove(0);
} 
 

At this point, you can populate the list with new options via the various approaches described in the add( ) method discussion and the options object discussion.

 
Parameters
 
positionIndex

Zero-based integer signifying the item from the nested options collection to be deleted.

 
Returned Value

None.