getElementsByTagName Method
Last Updated: 08-27-2005
Returns a NodeList collection of descendant element nodes with the specified name.

Syntax
var oNodeList = object.getElementsByTagName(sTagName);

Parameters
sTagName Required. The name of the element node to search for.

Return Value
The NodeList of element nodes with the specified name.

Remarks
The getElementsByTagName method searches recursively through all descendant nodes of the current node searching for node elements with the specified name. The method allows you to write code that is less dependent on the structure of the XML document, however, it is expensive. Consider one of the following alternatives:
  • If you control the schema of the data supplied to the data element, and the desired data is contained by unique nodes within the schema, add an id attribute to the nodes containing the data, and use the getElementById method to obtain references to those nodes.
  • If the document tree containing the data is shallow, use the childNodes property of a node to iterate through its children. Check the nodeName property of each traversed node until you encounter the desired node and associated data.
If the specified element name doesn't exist in the XML document, the getElementsByTagName method returns a NodeList of length zero.
Examples

The examples below utilize the following sample data describing a set of two airplane flights. The first flight consists of a single leg from San Francisco to Seattle. The second flight consists of two legs from San Francisco to Portland and from Portland to Seattle.

<?xml version="1.0"?>
<?access-control allow="*"?>
<flights>
<flight id="f129">
   <leg>
      <flight_num>100</flight_num>
      <origin>SFO</origin>
      <depart>27 Apr 2001 19:16:00 PST</depart>
      <dest>SEA</dest>
      <arrive>27 Apr 2001 21:14:00 PST</arrive>
   </leg>
</flight>
<flight id="f300">
   <leg>
      <flight_num>129</flight_num>
      <origin>SFO</origin>
      <depart>27 Apr 2001 17:30:00 PST</depart>
      <dest>PDX</dest>
      <arrive>27 Apr 2001 18:30:00 PST</arrive>
   </leg>
   <leg>
      <flight_num>592</flight_num>
      <origin>PDX</origin>
      <depart>27 Apr 2001 19:00:00 PST</depart>
      <dest>SEA</dest>
      <arrive>27 Apr 2001 19:45:00 PST</arrive>
   </leg>
</flight>
</flights>

The following example uses the getElementsByTagName method to determine the number of flights and the number of legs in each flight. This information is read back to the caller.

<vxml version="2.0">

<!-- if the data isn't well-formed or the fetch fails, it throws error.badfetch -->
<catch event="error.badfetch">
   <log>unable to fetch some resource</log>
</catch>

<data name="oFlightInfo" src="flights.exml"/>

<script><![CDATA[
var aNumbers = ["first", "second", "third", "fourth", "fifth", 
     "sixth", "seventh", "eighth", "ninth", "tenth"];

// how many flights in the data
function GetFlightCount(oDOM)
{
   return oDOM.getElementsByTagName("flight").length;
}

// return an array of the number of legs in each flight
function GetLegCounts(oDOM)
{
   var aLegs = []; // array to hold leg counts

   // get the collection of flight nodes
   var oFlights = oDOM.getElementsByTagName("flight");
   for (var i = 0; i < oFlights.length; i++)
   {
      var oFlight = oFlights.item(i);
      // get the collection of leg nodes
      var oLegs = oFlight.getElementsByTagName("leg");
      // add the length to the array
      aLegs.push(oLegs.length);
   }

   return aLegs;
}
]]></script>

<form id="finfo">
<var name="iFlight" expr="0"/>
<block>
<!-- if the data tag fails, the named variable will be null -->
<if cond="!oFlightInfo">
   <exit />
</if>
<audio>There are <value expr="GetFlightCount(oFlightInfo)"/> that meet your criteria.</audio>
<foreach item="iLegs" array="GetLegCounts(oFlightInfo)">
   <audio>The <value expr="aNumbers[iFlight]"/> 
      flight consists of <value expr="iLegs"/> 
      leg<value expr="(1 == iLegs ? '' : 's')"/>.</audio>
   <break size="medium"/> 
   <assign name="iFlight" expr="iFlight+1"/>
</foreach>
</block>
</form>

</vxml>

The following snippet shows alternative implementations of the GetFlightCount and GetLegCounts functions that do not rely on the getElementsByTagName method. Although the functions are implemented in JavaScript, they are more efficient than getElementsByTagName because they allocate less memory, visit fewer nodes, and perform no comparisons against the nodeName property of each node in the document tree.

// how many flights in the data
function GetFlightCount(oDOM)
{
   // flight nodes are direct descendants of root
   // so count of root's child nodes == flight count
   return oDOM.documentElement.childNodes.length;
}

// return an array of the number of legs in each flight
function GetLegCounts(oDOM)
{
   var aLegs = []; // array to hold leg counts

   // get the collection of flight nodes
   var oFlights = oDOM.documentElement.childNodes;
   for (var i = 0; i < oFlights.length; i++)
   {
      // leg nodes are direct descendants of flight
      // so count of flight's child nodes == leg count
      aLegs.push(oFlights.item(i).childNodes.length);
   }

   return aLegs;
}


Applies To
element, document
[24]7 Inc.| Terms of Service| Privacy Policy| General Disclaimers