item method

Retrieves a form object or an object from an elements collection.

Syntax

object.item(name, index)

Parameters

name [in]

Type: Variant

Variant of type Integer or String that specifies the object or collection to retrieve. If this parameter is an integer, it is the zero-based index of the object. If this parameter is a string, all objects with matching name or id properties are retrieved, and a collection is returned if more than one match is made.

index [in, optional]

Type: Variant

Variant of type Integer that specifies the zero-based index of the object to retrieve when a collection is returned.

Return value

Type: Object

Returns an object or a collection of objects if successful, or null otherwise.

Standards information

There are no standards that apply here.

Remarks

Note This method indexes collections by the name or id property of the object; this is a known standards-compliance issue. For interoperability with other browsers, do not reference an object by name using this method.

Windows Internet Explorer 8 and later. In IE8 Standards mode, the index parameter is not used. For more information, see Defining Document Compatibility.

Call QueryInterface on the IDispatch interface pointer retrieved to pdisp to obtain the correct interface for the object or collection.

This function returns S_OK even if the element is not found. You should check the value of the pdisp (IDispatch) pointer returned by this call. If the value of the pointer is NULL, the element was not found and the call was not successful.

The item method cannot retrieve input type=image elements from a form. To access all elements contained in a form, call QueryInterface on IHTMLFormElement and request an IHTMLElement interface. Use the children property of the IHTMLElement interface to retrieve a collection of all elements in the form.

The item method cannot retrieve input type=image elements from a form. To access all elements contained in a form, use the children collection.

Examples

The following example uses the item method to retrieve each object in the elements collection of a form object.

JavaScript


<body>
<form action="example.asp" method="get">
  First name: <input type="text" name="fname" value="John" /> <br />
  Last name: <input type="text" name="lname" value="Doe" /> <br />
  <input type="submit" value="Submit" />
</form>
<script type="text/jscript">
  window.onload = function() {
    var oForm = document.getElementsByTagName("FORM")[0];
    var oColl = oForm.elements;
    var sTypeAttr = new Array();
    var sNameAttr = new Array();
    var sValAttr = new Array();
	  
    for (i=0; i<oColl.length; i++) {     
      sTypeAttr[i] = oColl.item(i).getAttribute("type");
      sNameAttr[i] = oColl.item(i).getAttribute("name");
      sValAttr[i] = oColl.item(i).getAttribute("value");                
    }
    alert("This form has " + oColl.length + " input elements:" + "\n" +
      "type=" + "\"" + sTypeAttr[0] + "\" name=" + "\"" + sNameAttr[0] + "\" value=" + "\"" + sValAttr[0] + "\"\n" + 
      "type=" + "\"" + sTypeAttr[1] + "\" name=" + "\"" + sNameAttr[1] + "\" value=" + "\"" + sValAttr[1] + "\"\n" +
      "type=" + "\"" + sTypeAttr[2] + "\" name=" + "\"" + sNameAttr[2] + "\" value=" + "\"" + sValAttr[2] + "\"");  
    	 
  }
</script>
</body>

The following general example shows how to use the length property and item method to iterate through the option objects within a select object.

C++


HRESULT GetOptions(IHTMLSelectElement *ppvSelect, BSTR *pszOptText, long *plItems)
{
    IDispatch *ppvdispOption;
    IHTMLOptionElement *ppvOption;
    HRESULT hResult;
    // Obtain the number of option objects in the select object.
    ppvSelect->get_length(plItems);
 
    for (long i=0;i<*plItems;i++){
        // Get an IDispatch interface for the next option.
        _variant_t index = i;
        hResult = ppvSelect->item( index, index, &ppvdispOption );
        if FAILED(hResult) return(hResult);
        // Query for the IHTMLOptionElement interface.
        hResult = ppvdispOption->QueryInterface( IID_IHTMLOptionElement, 
                                                 (void **) &ppvOption);
        ppvdispOption->Release();
        if FAILED(hResult) return(hResult);
        // Add the option text to a list box.
        hResult = ppvOption->get_text(&(pszOptText[i]));
        ppvOption->Release();
        if FAILED(hResult) return(hResult);
    }
    return S_OK;
}