insertBefore Method

Article
10/27/2016

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

insertBefore Method

JScript Syntax

Parameters

Return Value

Example

C/C++ Syntax

Parameters

Return Values

Remarks

Versioning

See Also

Additional resources