Share via


getElementsByTagName Method (DOMDocument)

 

Returns a collection of elements that have the specified name.

JScript Syntax

var objXMLDOMNodeList =  
    oXMLDOMDocument.getElementsByTagName(tagName);  

Parameters

tagName
A string specifying the element name to find. The tagName value "*" returns all elements in the document.

Return Value

An object. Points to a collection of elements that match the specified name.

Example

The following script example creates an IXMLDOMNodeList object using the DOMDocument object's getElementsByTagName method, and then displays all of the elements with the desired tag name.

var xmlDoc = new ActiveXObject("Msxml2.DOMDocument.3.0");
var objNodeList;
xmlDoc.async = false;
xmlDoc.load("books.xml");
if (xmlDoc.parseError.errorCode != 0) {
   var myErr = xmlDoc.parseError;
   WScript.Echo("You have error " + myErr.reason);
} else {
   objNodeList = xmlDoc.getElementsByTagName("author");
   for (var i=0; i<objNodeList.length; i++) {
      WScript.Echo(objNodeList.item(i).xml);
   }
}

When used with the sample XML file (books.xml), this example returns the following output, which includes the full XML string for each instance of the <author> element in books.xml:

<author>Gambardella, Matthew</author>

<author>Ralls, Kim</author>

<author>Corets, Eva</author>

<author>Corets, Eva</author>

<author>Corets, Eva</author>

<author>Randall, Cynthia</author>

<author>Thurman, Paula</author>

<author>Knorr, Stefan</author>

<author>Kress, Peter</author>

<author>O'Brien, Tim</author>

<author>O'Brien, Tim</author>

<author>Galos, Mike</author>

C/C++ Syntax

HRESULT getElementsByTagName(  
    BSTR tagName,  
    IXMLDOMNodeList **resultList);  

Parameters

tagName[in]
The element name to find. The tagName value"*" returns all elements in the document.

resultList[out, retval]
The address of a collection of elements that match the specified name.

Return Values

S_OK
The value returned if successful.

Example

IXMLDOMDocument *pIXMLDOMDocument = NULL;  
wstring strFindText (_T("author"));  
IXMLDOMNodeList *pIDOMNodeList = NULL;  
IXMLDOMNode *pIDOMNode = NULL;  
long value;  
BSTR bstrItemText;  
HRESULT hr;  
  
try  
{  
   // Initialize pIXMLDOMDocument (create a DOMDocument).  
   // Load document.  
   hr = pIXMLDOMDocument->getElementsByTagName(   
            (TCHAR*)strFindText.data(), &pIDOMNodeList);  
   SUCCEEDED(hr) ? 0 : throw hr;  
  
   hr = pIDOMNodeList->get_length(&value);  
   if(SUCCEEDED(hr))  
   {  
      pIDOMNodeList->reset();  
      for(int ii = 0; ii < value; ii++)  
      {  
         pIDOMNodeList->get_item(ii, &pIDOMNode);  
         if(pIDOMNode )  
         {  
            pIDOMNode->get_text(&bstrItemText);  
            ::MessageBox(NULL, bstrItemText,strFindText.data(), MB_OK);  
            pIDOMNode->Release();  
            pIDOMNode = NULL;  
         }  
      }  
   }  
   pIDOMNodeList->Release();  
   pIDOMNodeList = NULL;  
}  
catch(...)  
{  
   if(pIDOMNodeList)  
      pIDOMNodeList->Release();  
   if(pIDOMNode)  
      pIDOMNode->Release();  
   DisplayErrorToUser();  
}  
// Release pIXMLDOMDocument when finished with it.  

Remarks

The elements in the collection are returned in the order in which they would be encountered in a preorder traversal of the document tree. In a preorder traversal, the parent root node is visited first and each child node from left to right is then traversed.

The returned IXMLDOMNodeList object is live and immediately reflects changes to the nodes that appear in the list.

The getElementsByTagName method simulates the matching of the provided argument against the result of the tagName property of IXMLDOMElement. When executed, it does not recognize or support namespaces. Instead you should use the selectNodes method, which is faster in some cases and can support more complex searches.

Versioning

Implemented in: MSXML 3.0 and MSXML 6.0

Applies to

IXMLDOMDocument-DOMDocument

See Also

IXMLDOMNodeList
selectNodes Method