insertBefore Method

MSXML 5.0 SDK

Microsoft XML Core Services (MSXML) 5.0 for Microsoft Office - DOM Reference

insertBefore Method

Inserts a child node to the left of the specified node, or at the end of the list.

[Script]

Script 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 before the second child of the top-level node.

var xmlDoc = new ActiveXObject("Msxml2.DOMDocument.5.0");
var root;
var newNode;
var currNode;
xmlDoc.async = false;
xmlDoc.load("books.xml");
if (xmlDoc.parseError.errorCode <> 0) {
   var myErr = xmlDoc.parseError;
   alert("You have error " + myErr.reason);
} else {
   root = xmlDoc.documentElement;
   alert(root.xml);
   newNode = xmlDoc.createNode(1, "VIDEOS", "");
   currNode = root.insertBefore(newNode, root.childNodes.item(1));
   alert(root.xml);
}
[Visual Basic]

Visual Basic Syntax

Set 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

An object. On success, returns the child node that was inserted.

Example

The following Visual Basic example creates a new IXMLDOMNode object and inserts it before the second child of the top-level node.

Dim xmlDoc As New Msxml2.DOMDocument50
Dim root As IXMLDOMElement
Dim newNode As IXMLDOMNode
Dim currNode As IXMLDOMNode
xmlDoc.async = False
xmlDoc.Load ("books.xml")
If (xmlDoc.parseError.errorCode <> 0) Then
   Dim myErr
   Set myErr = xmlDoc.parseError
   MsgBox("You have error " & myErr.reason)
Else
   Set root = xmlDoc.documentElement
   MsgBox root.xml
   Set newNode = xmlDoc.createNode(NODE_ELEMENT, "VIDEOS", "")
   Set currNode = root.insertBefore(newNode, root.childNodes.Item(1))
   MsgBox root.xml
End If
[C/C++]

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.

C/C++ 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.

To view reference information for Visual Basic, C/C++, or Script only, click the Language Filter button Language Filter in the upper-left corner of the page.

See Also

createNode Method | nodeType Property

Applies to: IXMLDOMAttribute | IXMLDOMCDATASection | IXMLDOMCharacterData | IXMLDOMComment | DOMDocument | IXMLDOMDocumentFragment | IXMLDOMDocumentType | IXMLDOMElement | IXMLDOMEntity | IXMLDOMEntityReference | IXMLDOMNode | IXMLDOMNotation | IXMLDOMProcessingInstruction | IXMLDOMText