[This documentation is preliminary and is subject to change.]
Retrieves a collection of objects based on the specified element name.
 |
Syntax
object.getElementsByTagName(v)Standards information
- Document Object Model (DOM) Level 2 HTML Specification, Section 1.6.5
Parameters
- v [in]
-
Type: BSTR
String that specifies the name of an element.
Return value
Type: ObjectReturns a collection of objects with the specified element name.Remarks
The getElementsByTagName method is equivalent to using the tags method on the all collection. For example, the following code shows how to retrieve a collection of div elements from the body element, first using the Dynamic HTML (DHTML) Object Model and then the Document Object Model (DOM).
- Using the DHTML Object Model:
var aDivs = document.body.all.tags("DIV"); - Using the DOM:
var aDivs = document.body.getElementsByTagName("DIV");
When you use the getElementsByTagName method, all child and nested child elements with the specified tag name are returned. For example, all of the SPAN elements in the following example would be returned by the getElementsByTagName method.
<SCRIPT>
var aSpans = oDiv.getElementsByTagName("SPAN");
</SCRIPT>
<DIV id="oDiv">
<SPAN>Immediate Child
<DIV>
<SPAN>Child of Child DIV</SPAN>
</DIV>
</SPAN>
</DIV>
Examples
The following example uses the getElementsByTagName method to return the children of a ul element based on the selected li element.
Code example: http://samples.msdn.microsoft.com/workshop/samples/author/dhtml/refs/getElementsByTagName.htm
<SCRIPT>
function fnGetTags(){
var oWorkItem=event.srcElement;
var aReturn=oWorkItem.parentElement.getElementsByTagName("LI");
alert("Length: "
+ aReturn.length
+ "\nFirst Item: "
+ aReturn[0].childNodes[0].nodeValue);
}
</SCRIPT>
<UL onclick="fnGetTags()">
<LI>Item 1
<UL>
<LI>Sub Item 1.1
<OL>
<LI>Super Sub Item 1.1
<LI>Super Sub Item 1.2
</OL>
<LI>Sub Item 1.2
<LI>Sub Item 1.3
</UL>
<LI>Item 2
<UL>
<LI>Sub Item 2.1
<LI>Sub Item 2.3
</UL>
<LI>Item 3
</UL>
See also
- a
- abbr
- acronym
- address
- applet
- area
- b
- base
- baseFont
- bdo
- bgSound
- big
- blockQuote
- body
- br
- button
- caption
- center
- cite
- code
- col
- colGroup
- custom
- dd
- del
- dfn
- dir
- div
- dl
- document
- dt
- em
- embed
- fieldSet
- font
- form
- frame
- frameSet
- head
- hn
- hr
- html
- i
- iframe
- img
- ins
- kbd
- label
- legend
- li
- link
- listing
- map
- marquee
- menu
- ol
- p
- plainText
- pre
- q
- s
- samp
- script
- select
- small
- span
- strike
- strong
- sub
- sup
- table
- tBody
- td
- textArea
- tFoot
- th
- tHead
- title
- tr
- tt
- u
- ul
- var
- xmp
- About the W3C Document Object Model
Build date: 3/8/2012
Possibly bug in IE 8:
<span id="SpanID">
</param>
</param>
</param>
</span>
...
var len = SpanID.getElementsByTagName("param").length
In IE 8 len = 0
In IE 5-7 len = 3
But SpanID.all[0].tagName return "PARAM"
In IE7 when calling this method for INPUT tags and one of the child nodes has as a value 'length' in the name attribute. The method returned an empty collection with no error.
I tried it with a DIV element that contained nested INPUT in table cells. I solved this behaviour changing the name attribute value to another. I not tested with other values nor tried to replicate this error.
EricLaw[MSFT]: Interesting find, and this happens with IE8 too. The problem here is that the NodeList collection exposes the IDs of all tags as expandos off itself; if you have an INPUT named length with no id attribute, IE gives that control the ID length. Then, when you call .length on the NodeList collection, it returns that INPUT element rather than the nodelist's intrinsic length number.
var tables=document.getElementsByTagName('table');
alert(typeof(tables[0]);// returns "Number"
The IE7 bug does not allow to safely use this method: in returned result, one element is missing.
Test case: dynamically create 1000 same custom tags
<customtag><A name="same4all">aa</a></customtag>
the getElementsByName gave 1000 as expected, document.getElementsByTagName and document.all.tags returns 999 elements.
testcase:
http://simulationlabs.com/test/NavigationTest.html
----
[jsudds.msft] Thanks for the report. I'll make sure the product team knows about it. Fortunately, this behavior is limited to custom tags only; getElementsByTagName works as expected for built-in elements such as the A tag.