IXMLDOMDocumentFragment

Article
10/27/2016

A lightweight object that is useful for tree insert operations.

Jscript Example

var xmlDoc = new ActiveXObject("Msxml2.DOMDocument.3.0");  
var docFragment;  
xmlDoc.async = false;  
xmlDoc.loadXML("<root/>");  
if (xmlDoc.parseError.errorCode != 0) {  
   var myErr = xmlDoc.parseError;  
   WScript.Echo("You have error " + myErr.reason);  
} else {  
   docFragment = xmlDoc.createDocumentFragment();  
   docFragment.appendChild(xmlDoc.createElement("node1"));  
   docFragment.appendChild(xmlDoc.createElement("node2"));  
   docFragment.appendChild(xmlDoc.createElement("node3"));  
   WScript.Echo(docFragment.xml);  
   xmlDoc.documentElement.appendChild(docFragment);  
   WScript.Echo(xmlDoc.xml);  
}

Output

<node1/><node2/><node3/>  
<root></root>

C++ Example

The C++ sample below creates and appends a new IXMLDOMDocumentFragment to the root document element. It uses the following XML document:

<?xml version='1.0'?>  
<COLLECTION  
   xmlns:dt="urn:schemas-microsoft-com:datatypes">  
  <DATE dt:dt="datetime">1998-10-13T15:56:00</DATE>  
  <BOOK>  
    <TITLE>Lover Birds</TITLE>  
    <AUTHOR>Cynthia Randall</AUTHOR>  
    <PUBLISHER>Lucerne Publishing</PUBLISHER>  
  </BOOK>  
  <BOOK>  
    <TITLE>The Sundered Grail</TITLE>  
    <AUTHOR>Eva Corets</AUTHOR>  
    <PUBLISHER>Lucerne Publishing</PUBLISHER>  
  </BOOK>  
  <BOOK>  
    <TITLE>Splish Splash</TITLE>  
    <AUTHOR>Paula Thurman</AUTHOR>  
    <PUBLISHER>Scootney</PUBLISHER>  
  </BOOK>  
</COLLECTION>

#include “msxml6.h”  
  
inline void TESTHR( HRESULT _hr )   
   { if FAILED(_hr) throw(_hr); }  
  
void XMLDOMDocumentFragmentSample()  
{  
      //HRESULT hr;  
      try  
      {  
            MSXML2::IXMLDOMDocumentPtr docPtr;  
  
            //init  
            TESTHR(CoInitialize(NULL));   
            TESTHR(docPtr.CreateInstance("Msxml2.DOMDocument.6.0"));  
  
            // load a document  
            _variant_t varXml(_T("c:\\book.xml"));  
            _variant_t varOut((bool)TRUE);  
            varOut = docPtr->load(varXml);  
            if ((bool)varOut == FALSE)  
            {// show error description - IXMLDOMParseError sample  
                  MSXML2::IXMLDOMParseErrorPtr errPtr = docPtr->GetparseError();  
                  _bstr_t bstrErr(errPtr->reason);  
  
                  _tprintf(_T("Error:\n"));  
                  _tprintf(_T("Code = 0x%x\n"), errPtr->errorCode);  
                  _tprintf(_T("Source = Line : %ld; Char : %ld\n"), errPtr->line, errPtr->linepos);  
                  _tprintf(_T("Error Description = %s\n"), (char*)bstrErr);  
            }  
            else  
            {// dom fragment sample  
  
                  // create a new node and add to the doc  
                     _variant_t varTyp((short) MSXML2::NODE_ELEMENT);  
                     _bstr_t varName(_T("BOOK"));  
                     MSXML2::IXMLDOMNodePtr nodePtr= docPtr->createNode(varTyp, varName, "");  
                     // create a doc fragment and associate the new node with it  
                     MSXML2::IXMLDOMDocumentFragmentPtr fragPtr = docPtr->createDocumentFragment();  
                     fragPtr->appendChild(nodePtr);  
                     // add some elements to the new node  
                     varName = _T("TITLE");  
                     MSXML2::IXMLDOMNodePtr nodePtr1= docPtr->createNode(varTyp, varName, "");  
                     nodePtr1->text = _T("Creepy Crawlies");  
                     varName = "AUTHOR";  
                     MSXML2::IXMLDOMNodePtr nodePtr2= docPtr->createNode(varTyp, varName, "");  
                     nodePtr2->text = _T("Stefan Knorr");  
                     nodePtr->appendChild(nodePtr1);  
                     nodePtr->appendChild(nodePtr2);  
                     // display the fragment contents  
                     MessageBox(NULL, fragPtr->xml, "", MB_OK);  
                     // add the fragment to the original doc  
                     docPtr->documentElement->appendChild(fragPtr);  
                     // display the modified doc contents  
                     MessageBox(NULL, docPtr->xml, "", MB_OK);  
              }  
  
       }  
       catch (_com_error &e)  
       {  
              _tprintf(_T("Error:\n"));  
              _tprintf(_T("Code = %08lx\n"), e.Error());  
              _tprintf(_T("Code meaning = %s\n"), (char*) e.ErrorMessage());  
              _tprintf(_T("Source = %s\n"), (char*) e.Source());  
              _tprintf(_T("Error Description = %s\n"), (char*) e.Description());  
       }  
          catch(...)  
       {  
              _tprintf(_T("Unknown error!"));  
       }  
       CoUninitialize();  
}

Remarks

The DocumentFragment object can represent a fragment of a document or portion of a document's tree. This makes it useful when implementing end user commands that allow users to rearrange a document, such as cutting and pasting.

The DocumentFragment node has special, defined behavior for IXMLDOMNode insert operations that makes it especially convenient for developers. When an IXMLDOMDocumentFragment is inserted into a DOMDocument node (or other node that can take children), the children of the DocumentFragment are inserted into the node rather than the DocumentFragment itself. This makes the DocumentFragment useful when the user wants to create nodes that are siblings; the DocumentFragment acts as the parent of these nodes so that the user can employ the standard methods from the IXMLDOMNode interface, such as insertBefore and appendChild.

The children of a DocumentFragment node make up zero or more nodes representing the tops of any subtrees defining the structure of the document. DocumentFragment nodes do not need to be well-formed XML documents (although they do need to follow the rules imposed upon well-formed XML parsed entities, which can have multiple top nodes). For example, a DocumentFragment might have only one child, and that child node could be a Text node. Such a structure model represents neither an HTML document nor a well-formed XML document.

IXMLDOMDocumentFragment has no unique members of its own, but exposes the same members as IXMLDOMNode.

Requirements

Implementation:

msxml3.dll, msxml2.lib (MSXML 3.0)

msxml6.dll, msxml6.lib (MSXML 6.0)

Header and IDL files (C/C++): msxml2.h, msxml2.idl, msxml6.h, msxml6.idl

Versioning

Implemented in: MSXML 3.0, MSXML 6.0