Packagedom.html.objects
Classpublic class HTMLCollection
InheritanceHTMLCollection Inheritance Object

Introduced in: DOM 1 HTML 

An HTMLCollection is a list of nodes.

An individual node may be accessed by either ordinal index or the node's name or id attributes.

Note: Collections in the HTML DOM are assumed to be live meaning that they are automatically updated when the underlying document is changed.

See also

MDC: HTMLCollection
W3C DOM HTML Specification
MSDN: HTMLCollection

Public Properties
 PropertyDefined By
  DOM 1 HTML length : Number
[read-only] This attribute specifies the length or size of the list.
HTMLCollection
Public Methods
 MethodDefined By
  
DOM 1 HTML item(index:Number):Node
This method retrieves a node specified by ordinal index.
HTMLCollection
  
DOM 1 HTML namedItem(name:DOMString):Node
This method retrieves a Node using a name.
HTMLCollection
  
Non-Standard tags(tag:DOMString):HTMLCollection
Retrieves a collection of objects that have the specified HTML tag name.
HTMLCollection
  
Non-Standard urns(urn:DOMString):HTMLCollection
Retrieves a collection of all objects to which a specified behavior is attached.
HTMLCollection
Property Detail
DOM 1 HTML lengthproperty
length:Number  [read-only]

Introduced in: DOM 1 HTML 

This attribute specifies the length or size of the list.


Implementation
    public function get length():Number

See also

MDC: HTMLCollection
MSDN: length Property
W3C - DOM HTML: HTMLCollection.length
Method Detail
DOM 1 HTML item()method
public function item(index:Number):Node

Introduced in: DOM 1 HTML 

This method retrieves a node specified by ordinal index. Nodes are numbered in tree order (depth-first traversal order).

Note (IE): IE7 and earlier. item() has a second and optional param called 'iSubindex'. This param specifies the zero-based index of the object to retrieve when a collection is returned.

Note (IE): Internet Explorer 8 and later. In IE8 mode, the iSubindex parameter is not used.

Parameters

index:Number — The index of the node to be fetched. The index origin is 0

Returns
Node — The Node at the corresponding position upon success. A value of null is returned if the index is out of range.

See also

MDC: HTMLCollection
MSDN: item Method
W3C - DOM HTML: HTMLCollection.item()
DOM 1 HTML namedItem()method 
public function namedItem(name:DOMString):Node

Introduced in: DOM 1 HTML 

This method retrieves a Node using a name. With [HTML 4.01] documents, it first searches for a Node with a matching id attribute. If it doesn't find one, it then searches for a Node with a matching name attribute, but only on those elements that are allowed a name attribute. With [XHTML 1.0] documents, this method only searches for Nodes with a matching id attribute. This method is case insensitive in HTML documents and case sensitive in XHTML documents.

Note (IE): Internet Explorer 8 and later. In IE8 mode, the namedItem method does not return collections if more than one named item is found; instead, it returns the first case-insensitive matched element.

Note (IE): The namedItem method was introduced in Microsoft Internet Explorer 6.

Parameters

name:DOMString — The name of the Node to be fetched.

Returns
Node — The Node with a name or id attribute whose value corresponds to the specified string. Upon failure (e.g., no node with this name exists), returns null.

See also

MDC: HTMLCollection
MSDN: namedItem Method
W3C - DOM HTML: HTMLCollection.namedItem()

Example
The following example shows how to use the namedItem method to retrieve a div and change its innerText property. 
         <div id="oDIV1">This text will not change.</div>
         <div id="oDIV2">This text will change.</div>
         <button onclick="document.all.namedItem('oDIV2').innerHTML='Changed!';">
         Change Option
         </button>
tags()method 
public function tags(tag:DOMString):HTMLCollection

Non-standard (Microsoft)

Retrieves a collection of objects that have the specified HTML tag name.

Note: Successful execution includes the case where no elements having the given name are found. In this case, a collection containing zero elements is returned.

Note: NULL may be returned in cases where the collection cannot be constructed, such as inability to allocate memory for even a zero-length collection.

Parameters

tag:DOMString — Specifies an HTML tag. It can be any one of the objects exposed by the DHTML Object Model.

Returns
HTMLCollection — Returns a collection of element objects if successful, or null otherwise.

See also

MSDN: tags Method

Example
This example uses the tags method to retrieve a collection of all p elements in the document, and all body elements in the document. It displays some of the properties of the collections that are returned. It then displays selected elements of the collection.

There are no p elements in the document, and there is one body element in the document. So, this example illustrates both the cases where the collection is empty and where the collection is populated.

         <html>
<head>
<title>document.all.tags example </title>
</head>

<body>
<script type="text/jscript" language="jscript">

document.write("Here is how document.all.tags behaves when no tags are found.<br>");
var coll = document.all.tags("p");
document.write("list 'p' tags" + "<br>");
document.write("coll= " + coll + "<br>");
document.write("coll.length= " + coll.length + "<br>");
if (coll==null){
    document.write( "coll= is null <br>" );
} else {
    document.write( "coll= is not null <br>" );
}


if ( coll[0] != null ){
    document.write( "coll[0].attributes length " + coll[0].attributes.length  + "<br>");

    for ( i = 0; i<coll[0].attributes.length ; i++ ){
        if (( coll[0].attributes[i].value       != "null"  )
           &( coll[0].attributes[i].value.length > 0       ))
        {
            document.write( "coll[0].attributes "        + i + ":"   );
            document.write(  coll[0].attributes[i].name      + ":            "   );
            document.write(  coll[0].attributes[i].value     + "<br>");
        }
    }
}

document.write( "<br><br>" );
document.write( "Here is how document.all.tags behaves when at least 1 tag is found.<br>" );
var coll = document.all.tags( "body" );
document.write( "list 'body' tags"            + "<br>" );
document.write( "coll= "        + coll        + "<br>" );
document.write( "coll.length= " + coll.length + "<br>" );
if ( coll == null ){
    document.write( "coll= is null <br>" );
} else {
    document.write( "coll= is not null <br>" );
}

if ( coll[0] != null ){
    document.write( "coll[0].attributes length " + coll[0].attributes.length  + "<br>");

    for ( i = 0; i<coll[0].attributes.length ; i++ ){
        if (( coll[0].attributes[i].value       != "null"  )
           &( coll[0].attributes[i].value.length > 0       ))
        {
            document.write( "coll[0].attributes "        + i + ":"   );
            document.write(  coll[0].attributes[i].name      + ":            "   );
            document.write(  coll[0].attributes[i].value     + "<br>");
        }
    }
}

</script>

<pre>
=================================
== Here is what the above example should display in your browser
=================================
Here is how document.all.tags behaves when no tags are found.
list 'p' tags
coll= [object]
coll.length= 0
coll= is not null


Here is how document.all.tags behaves when at least 1 tag is found.
list 'body' tags
coll= [object]
coll.length= 1
coll= is not null
coll[0].attributes length 98
coll[0].attributes 21:hideFocus: false
coll[0].attributes 45:contentEditable: inherit
coll[0].attributes 59:disabled: false
coll[0].attributes 69:tabIndex: 0
coll[0].attributes 80:bottomMargin: 15
coll[0].attributes 81:noWrap: false
coll[0].attributes 90:leftMargin: 10
coll[0].attributes 92:topMargin: 15
coll[0].attributes 95:rightMargin: 10

</pre>
</body>
</html>
urns()method 
public function urns(urn:DOMString):HTMLCollection

Non-standard (Microsoft)

Retrieves a collection of all objects to which a specified behavior is attached.

Parameters

urn:DOMString — Specifies the behavior's Uniform Resource Name (URN).

Returns
HTMLCollection — Returns a collection of objects if successful, or null otherwise.

See also

MSDN: urns Method

Example
The following example shows how to use the urns method to retrieve a collection of all elements currently attached to the specified behavior and then display a comma-delimited list of these element IDs in a message box. 
         <script language="JScript">
             var coll  = document.all.urns("URN1");
             var sText = '';
         
             if (coll != null) {
                 for (i=0; i<coll.length; i++) {
                     sText += coll.item(i).id + ', ';
                 }
         
                 window.alert(sText);
             }
         </script>




Mon Aug 17 2009, 10:08 AM -04:00