insertBefore Method
Inserts a child node to the left of the specified node, or at the end of the list.
JScript Syntax
var objXMLDOMNode = oXMLDOMNode.insertBefore(newChild, refChild);
Parameters
newChild
An object. The address of the new node to be inserted.
refChild
A variant. The address of the reference node; the newChild parameter is inserted to the left of the refChild parameter. If Null, the newChild parameter is inserted at the end of the child list.
Return Value
Object. On success, returns the child node that was inserted.
Example
The following script example creates a new IXMLDOMNode object and inserts it as the second child of the top-level node.
var xmlDoc = new ActiveXObject("Msxml2.DOMDocument.6.0");
var root;
var newNode;
var currNode;
xmlDoc.async = false;
xmlDoc.loadXML("<root><child1/></root>");
if (xmlDoc.parseError.errorCode != 0) {
var myErr = xmlDoc.parseError;
WScript.Echo("You have error " + myErr.reason);
} else {
root = xmlDoc.documentElement;
WScript.Echo(root.xml);
newNode = xmlDoc.createNode(1, "CHILD2", "");
currNode = root.insertBefore(newNode, root.childNodes.item(1));
WScript.Echo(root.xml);
}
C/C++ Syntax
HRESULT insertBefore(
IXMLDOMNode *newChild,
VARIANT refChild,
IXMLDOMNode **outNewChild);
Parameters
newChild[in]
The address of the new node to be inserted. The node passed here must be a valid child of the current XML DOM document node. For example, if the current node is an attribute, you cannot pass another attribute in the newChild parameter, because an attribute cannot have an attribute as a child.
If newChild is of DOCUMENT_FRAGMENT node type, all its children are inserted in order before refChild. If newChild is already in the tree, it is first removed before it is reinserted before the refChild node. Read-only nodes, such as NODE_DOCUMENT_TYPE and NODE_ENTITY nodes, cannot be passed in the newChild parameter.
refChild[in]
The address of the reference node. The node specified is where the newChild node is to be inserted to the left as the preceding sibling in the child list. The node passed here must be a either a child node of the current node or Null. If the value is Null, the newChild node is inserted at the end of the child list. If the refChild node is not a child of the current node, an error is returned.
outNewChild[out, retval]
On success, the child node that was inserted. If Null, no object is created.
Return Values
S_OK
The value returned if successful.
E_INVALIDARG
The value returned if the newChild parameter is Null.
E_FAIL
The value returned if an error occurs.
Remarks
The following are general remarks about the insertBefore method when DTD/schema rules or namespace prefixes are involved.
How DTD/Schema definitions are resolved
The newChild and refChild parameters can represent nodes in the same document or in different documents. When in the same document, the nodes retain their default attributes and data types. When in different documents, the nodes either lose or alter their default attributes, depending on whether the document that contains them has a document type definition (DTD) or other schema. MSXML attempts to correctly merge the different DTDs.
If the newChild node's DTD or schema differs from that of the original document, the nodes will be treated with the definitions in the new DTD, including default attributes and data types. If there is no DTD, the nodes keep their data types by picking up an instance definition in which elements are defined based upon how they are used in the current DOM document instance but any attributes within the newChild node fragment lose their data types and defaults. Cutting and pasting between documents with two different DTDs can result in an invalid document that might fail to parse after being saved.
How conflicts between prefixes and namespaces are resolved
If there is a conflict between prefixes on the containing element and the prefixes being added, the insertBefore operation fails and returns an error. For example, a conflict occurs when a new attribute referring to a different namespace is added to an element with the namespace, as in the following.
xmlns:myns="URN1"
The error can result from the new attribute, where myns refers to a different namespace, "URN2," such as would result from a call to createNode("attribute","myns:myname","URN2"):
myns:myname="myattributevalue"
Namespace conflict errors occur only when setting attributes. Inserted child elements do not cause a namespace conflict.
When adding a document fragment, the containing element adds all namespaces and prefixes from the document fragment. If this causes a conflict with the containing element, insertBefore returns an error.
Further remarks
The use and operation of the insertBefore method depends on the value of the nodeType property for the IXMLDOMNode type object passed in the newChild parameter. The following topics provide further information about the results of calling insertBefore on different types of nodes.
Versioning
Implemented in: MSXML 3.0 and MSXML 6.0
See Also
createNode Method
nodeType Property1
IXMLDOMAttribute
IXMLDOMCDATASection
IXMLDOMCharacterData
IXMLDOMComment
IXMLDOMDocument-DOMDocument
IXMLDOMDocumentFragment
IXMLDOMDocumentType
IXMLDOMElement
IXMLDOMEntity
IXMLDOMEntityReference
IXMLDOMNode
IXMLDOMNotation
IXMLDOMProcessingInstruction
IXMLDOMText