IXMLDOMDocumentFragment
A lightweight object that is useful for tree insert operations.
Example
var xmlDoc = new ActiveXObject("Msxml2.DOMDocument.5.0"); var docFragment; xmlDoc.async = false; xmlDoc.loadXML("<root/>"); if (xmlDoc.parseError.errorCode <> 0) { var myErr = xmlDoc.parseError; alert("You have error " + myErr.reason); } else { docFragment = xmlDoc.createDocumentFragment(); docFragment.appendChild(xmlDoc.createElement("node1")); docFragment.appendChild(xmlDoc.createElement("node2")); docFragment.appendChild(xmlDoc.createElement("node3")); alert(docFragment.xml); xmlDoc.documentElement.appendChild(docFragment); alert(xmlDoc.xml); }
Example
Dim xmlDoc As New Msxml2.DOMDocument50 Dim docFragment As IXMLDOMDocumentFragment xmlDoc.async = False xmlDoc.loadXML "<root/>" If (xmlDoc.parseError.errorCode <> 0) Then Dim myErr Set myErr = xmlDoc.parseError MsgBox("You have error " & myErr.reason) Else Set docFragment = xmlDoc.createDocumentFragment() docFragment.appendChild xmlDoc.createElement("node1") docFragment.appendChild xmlDoc.createElement("node2") docFragment.appendChild xmlDoc.createElement("node3") MsgBox docFragment.xml xmlDoc.documentElement.appendChild docFragment MsgBox xmlDoc.xml End If
Example
The following sample 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> #import "msxml5.dll" using namespace MSXML2; inline void TESTHR( HRESULT _hr ) { if FAILED(_hr) throw(_hr); } void XMLDOMDocumentFragmentSample() { //HRESULT hr; try { IXMLDOMDocumentPtr docPtr; //init TESTHR(CoInitialize(NULL)); TESTHR(docPtr.CreateInstance("Msxml2.DOMDocument.5.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 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)NODE_ELEMENT); _bstr_t varName(_T("BOOK")); IXMLDOMNodePtr nodePtr= docPtr->createNode(varTyp, varName, ""); // create a doc fragment and associate the new node with it IXMLDOMDocumentFragmentPtr fragPtr = docPtr->createDocumentFragment(); fragPtr->appendChild(nodePtr); // add some elements to the new node varName = _T("TITLE"); IXMLDOMNodePtr nodePtr1= docPtr->createNode(varTyp, varName, ""); nodePtr1->text = _T("Creepy Crawlies"); varName = "AUTHOR"; 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
.
Versioning
MSXML 2.0 and later
Requirements
Implementation: msxml5.dll, msxml2.lib
Header and IDL files: msxml2.h, msxml2.idl
To view reference information for Visual Basic, C/C++, or Script only, click the Language Filter button in the upper-left corner of the page.
See Also
appendChild Method | insertBefore Method | IXMLDOMDocumentFragment Members | IXMLDOMNode | DOMDocument