Collections Reference

Collections Reference



all

Description

Retrieves a collection of element objects representing all the elements in an HTML document.

Syntax

object.all(index)

ParameterDescription
object The document object.
(index) Optional. An integer or a string specifying the index value of the element to retrieve. Integer indexes are zero-based, meaning the first element in the collection has index 0. A string index is valid only if the string is a name or identifier of at least one element in the document.

Remarks

The all collection includes one element object for each valid HTML tag. If a valid tag has a matching end tag, both tags are represented by the same element object.

The collection always includes one element object for each of the HTML, HEAD, TITLE and BODY tags regardless of whether the tags are present in the document.

If the document contains invalid or unknown tags, the collection includes one element object for each. Unlike valid end tags, unknown end tags are represented by their own element objects. The order of the element objects is the HTML source order. Although the collection indicates the order of tags, it does not indicate hierarchy.

Examples

The following JScript example displays the names of all tags in the document in the order the tags appear in the document.

for(i=0; i<document.all.length; i++) {
    alert(document.all(i).tagName);
}

The following JScript example uses the item method on the all collection to retrieve all element objects for which the name or ID attribute is set to "sample". Depending on how many times the name or ID is defined in the document, the item method may return null, a single element object, or a collection of element objects. The example uses the length property of the collection to determine whether item returned a collection or a single object.

var a = document.all.item("sample");
if (a!=null) {
    if (a.length!=null) {
        for (i=0; i<a.length; i++) {
            alert(a(i).tagName);
        }
    } else 
        alert(a.tagName);
} 

Property

length

Methods

item, tags

Applies To

A, ACRONYM, ADDRESS, APPLET, AREA, B, BASE, BASEFONT, BGSOUND, BIG, BLOCKQUOTE, BODY, BR, BUTTON, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, COMMENT, DD, DEL, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, FRAME, FRAMESET, H1, H2, H3, H4, H5, H6, HEAD, HR, HTML, I, IFRAME, IMG, INPUT, INS, KBD, LABEL, LEGEND, LI, LINK, LISTING, MAP, MARQUEE, MENU, OBJECT, OL, OPTION, P, PLAINTEXT, PRE, Q, S, SAMP, SCRIPT, SELECT, SMALL, SPAN, STRIKE, STRONG, STYLE, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TITLE, TR, TT, U, UL, VAR, XMP


anchors

Description

Retrieves a collection of all A elements that have a NAME= and/or ID= attribute. Elements in this collection are in HTML source order.

Syntax

object.anchors(index)

ParameterDescription
object The document object.
(index) Optional. An integer or a string specifying the index value of the element to retrieve. Integer indexes are zero-based, meaning the first element in the collection has index 0. A string index is valid only if the string is a name or identifier of at least one element in the document.

Remarks

This collection is indexed first by name, then by identifier. If duplicate names are found, a collection of those named items is returned. Collections of duplicate names must subsequently be referenced by ordinal position.

Example

The following example displays the NAME= attribute of the third anchor defined in the document.

alert(document.anchors(2).name);

Property

length

Methods

item, tags

Applies To

document


applets

Description

Retrieves a collection of all APPLET objects in the document.

Syntax

object.applets(index)

ParameterDescription
object The document object.
(index) Optional. An integer or a string specifying the index value of the object to retrieve. Integer indexes are zero-based, meaning the first object in the collection has index 0. A string index is valid only if the string is a name or identifier of one object in the document.

Remarks

This collection is indexed first by name, then by identifier. If duplicate names are found, a collection of those named items is returned. Collections of duplicate names must subsequently be referenced by ordinal position.

Property

length

Methods

item, tags

Applies To

document


areas

Description

Retrieves a collection of the AREA elements defined for the given MAP element.

Syntax

object.areas(index)

ParameterDescription
object A MAP element.
(index) Optional. An integer or a string specifying the index value of the element to retrieve. Integer indexes are zero-based, meaning the first element in the collection has index 0. A string index is valid only if the string is an identifier of at least one element in the document.

Remarks

Areas may be added to or removed from the collection. If duplicate identifiers are found, a collection of those items is returned. Collections of duplicates must subsequently be referenced by ordinal position.

Property

length

Methods

add, item, remove, tags

Applies To

MAP


cells

Description

Retrieves a collection of all cells in the row of a table. This is a collection of TH and TD elements.

Note When a cell spans multiple rows, that cell appears only in the cells collection for the first of the rows that the cell spans.

Syntax

object.cells(index)

ParameterDescription
object A TR element.
index Optional. An integer or a string specifying the index value of the element to retrieve. Integer indexes are zero-based, meaning the first element in the collection has index 0. A string index is valid only if the string is an identifier of at least one element in the document.

Remarks

If duplicate identifiers are found, a collection of those items is returned. Collections of duplicates must subsequently be referenced by ordinal position.

Example

The following example uses the rows collection on the TABLE and the cells collection to insert a number into each cell of the table.

<HTML>
<SCRIPT LANGUAGE="JScript">
function numberCells() {
    var count=0;
    for (i=0; i < document.all.mytable.rows.length; i++) {
        for (j=0; j < document.all.mytable.rows(i).cells.length; j++) {
            document.all.mytable.rows(i).cells(j).innerText = count;
            count++;
        }
    }
}
</SCRIPT>
<BODY onload="numberCells()">
<TABLE id=mytable border=1>
<TR><TH>&nbsp;</TH><TH>&nbsp;</TH><TH>&nbsp;</TH><TH>&nbsp;</TH></TR>
<TR><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD></TR>
<TR><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD></TR>
</TABLE>
</BODY>
</HTML> 

Applies To

TR

Property

length

Methods

item, tags


children

Description

Retrieves only the direct descendants of an element. The elements contained in this collection are undefined if the child elements are overlapping tags. Similar to the all collection.

Syntax

object.children(index)

ParameterDescription
object The document object.
(index) Optional. An integer or a string specifying the index value of the element to retrieve. Integer indexes are zero-based, meaning the first element in the collection has index 0. A string index is valid only if the string is a name or identifier of at least one element in the document.

Remarks

The following example illustrates what this collection would return.

<DIV id=divONE>
<IMG src=mygif.gif>
<DIV id=divTWO>
<p>Some text in a paragraph
</DIV>
<BUTTON> The label for the button </BUTTON>
</DIV>

The children collection for divONE would include IMG, DIV, and BUTTON. The children collection for divTWO would include P.

Applies To

A, ACRONYM, ADDRESS, APPLET, AREA, B, BASE, BASEFONT, BGSOUND, BIG, BLOCKQUOTE, BODY, BR, BUTTON, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, COMMENT, DD, DEL, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, FRAME, FRAMESET, H1, H2, H3, H4, H5, H6, HEAD, HR, HTML, I, IFRAME, IMG, INPUT, INS, KBD, LABEL, LEGEND, LI, LINK, LISTING, MAP, MARQUEE, MENU, OBJECT, OL, OPTION, P, PLAINTEXT, PRE, Q, S, SAMP, SCRIPT, SELECT, SMALL, SPAN, STRIKE, STRONG, STYLE, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TITLE, TR, TT, U, UL, VAR, XMP


elements

Description

Retrieves a collection, in source order, of all elements in a given form. This collection can contain any combination of INPUT, SELECT, and TEXTAREA elements.

Syntax

object.elements(index)

ParameterDescription
object A FORM element.
(index) Optional. An integer or a string specifying the index value of the element to retrieve. Integer indexes are zero-based, meaning the first element in the collection has index 0. A string index is valid only if the string is a name or identifier of at least one element in the document.

Remarks

This collection is indexed first by name, then by identifier. If duplicate names are found, a collection of those named items is returned. Collections of duplicate names must subsequently be referenced by ordinal position.

Property

length

Methods

item, tags

Applies To

FORM


embeds

Description

Retrieves a collection of all EMBED elements on the document.

Syntax

object.embeds(index)

ParameterDescription
object The document object.
(index) Optional. An integer or a string specifying the index value of the element to retrieve. Integer indexes are zero-based, meaning the first element in the collection has index 0. A string index is valid only if the string is an identifier of at least one element in the document.

Remarks

If duplicate identifiers are found, a collection of those items is returned. Collections of duplicates must subsequently be referenced by ordinal position.

Property

length

Methods

item, tags

Applies To

document


filters

Description

Retrieves a collection of filter objects for an element.

Syntax

object.filters(index)

ParameterDescription
object An element object.
(index) Optional. An integer specifying the index value of the filter to retrieve. Integer indexes are zero-based, meaning the first filter in the collection has index 0.

Remarks

An asterisk in the following applies to list indicates that a defined height, width, or absolute position is required.

Property

length

Methods

item

Applies To

BODY, BUTTON, DIV*, IMG, INPUT, MARQUEE, SPAN*, TABLE, TD, TEXTAREA, TFOOT, TH, THEAD, TR


forms

Description

Retrieves a collection, in source order, of all FORM elements in the document.

Syntax

object.forms(index)

ParameterDescription
object The document object.
(index) Optional. An integer or a string specifying the index value of the element to retrieve. Integer indexes are zero-based, meaning the first element in the collection has index 0. A string index is valid only if the string is a name or identifier of at least one element in the document.

Remarks

This collection is indexed first by name, then by identifier. If duplicate names are found, a collection of those named items is returned. Collections of duplicate names must subsequently be referenced by ordinal position.

Property

length

Methods

item, tags

Applies To

document


frames

Description

Retrieves a collection of all window objects defined by the given document or defined by the document associated with the given window.

Syntax

object.frames(index)

ParameterDescription
object Either the document or window object.
(index) Optional. An integer or a string specifying the index value of the window to retrieve. Integer indexes are zero-based, meaning the first window in the collection has index 0. A string index is valid only if the string is the name of one window in the document.

Remarks

If the HTML source document contains a BODY tag, the collection contains one window for each IFRAME element in the document. If the source document contains FRAMESET tags, the collection contains one window for each FRAME tag in the document. In both cases, the order is determined by the HTML source.

This collection contains window objects only and does not provide access to the corresponding FRAME and IFRAME elements. To access these elements, use the all collection for the document containing the elements.

Although you can use names with the item method on this collection, the method never returns a collection. Instead, it always returns the first window having the given name. To ensure that all windows are accessible, you should always make sure that no two windows in a document have the same name.

Examples

The following JScript example displays the URLs of the HTML documents contained in windows created by the IFRAME elements in the document.

var frm = document.frames;
for (i=0; i<frm.length; i++)
    alert(frm(i).location);

The following JScript example displays the names of each window defined by FRAME tags in the parent window of the current document.

var frm = window.parent.frames;
for (i=0; i < frm.length; i++) 
    alert(frm(i).name);
}

Property

length

Methods

item

Applies To

document, window


images

Description

Retrieves a collection, in source order, of IMG elements in the document.

Syntax

object.images(index)

ParameterDescription
object The document object.
(index) Optional. An integer or a string specifying the index value of the element to retrieve. Integer indexes are zero-based, meaning the first element in the collection has index 0. A string index is valid only if the string is a name or identifier of at least one element in the document.

Remarks

This collection is indexed first by name, then by identifier. If duplicate names are found, a collection of those named items is returned. Collections of duplicate names must subsequently be referenced by ordinal position.

Property

length

Methods

item, tags

Applies To

document


imports

Description

Retrieves a collection of all the imported style sheets defined for the respective styleSheet object. An imported style sheet is one that is brought into the document using the @import attribute in CSS.

Syntax

object.imports(index)

ParameterDescription
object A styleSheet object.
(index) Optional. An integer or a string specifying the index value of the style sheet to retrieve. Integer indexes are zero-based, meaning the first style sheet in the collection has index 0.

Example

The following example displays the URLs of the imported style sheets in the document.

for (i=0; i<document.styleSheets.length; i++) {
    if (document.styleSheets(i).owningElement.tagName == "STYLE") {
        for (j=0; j<document.styleSheets(i).imports.length; j++)
            alert("Imported style sheet " + j + " is at " + document.styleSheets(i).imports(j).href);
    }
}

Property

length

Methods

item

Applies To

styleSheet


links

Description

Retrieves a collection of all A elements that specify the HREF= attribute and all AREA elements in the document.

Syntax

object.links(index)

ParameterDescription
object The document object.
(index) Optional. An integer or a string specifying the index value of the element to retrieve. Integer indexes are zero-based, meaning the first element in the collection has index 0. A string index is valid only if the string is a name or identifier of at least one element in the document.

Remarks

This collection is indexed first by name, then by identifier. If duplicate names are found, a collection of those named items is returned. Collections of duplicate names must subsequently be referenced by ordinal position.

This collection includes A elements that have a NAME= or ID= attribute as long as they also have an HREF= attribute.

Example

The following example displays the HREF= attribute of the third link defined in the document.

alert(document.anchors(2).href);

Property

length

Methods

item, tags

Applies To

document


options

Description

Retrieves a collection of the OPTION elements in a SELECT object.

Syntax

object.options(index)

ParameterDescription
object A SELECT element.
(index) Optional. An integer or a string specifying the index value of the element to retrieve. Integer indexes are zero-based, meaning the first element in the collection has index 0. A string index is valid only if the string is an identifier of at least one element in the document.

Remarks

To delete an option from a SELECT object, you assign the option a null value. This compresses the array.

If duplicate identifiers are found, a collection of those items is returned. Collections of duplicates must subsequently be referenced by ordinal position.

Example

The following example displays the text and values of all OPTION elements in the first SELECT element in the document.

var coll = document.all.tags("SELECT");
if (coll.length>0) {
    for (i=0; i< coll(0).options.length; i++)
        alert("Element " + i + " is " + coll(0).options(i).text + " and has the value " + coll(0).options(i).value);
}

Property

length

Methods

add, item, remove, tags

Applies To

SELECT

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.