Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

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

Script Syntax

Copy Code 
var 
objXMLDOMNode = oXMLDOMNode.insertBefore(
newChild, 
refChild);

Remarks

Script Parameters

newChild

Object. Address of the new node to be inserted.

refChild

Variant. Address of the reference node; newChildis inserted to the left of refChild. If Null, newChildis inserted at the end of the child list.

Script Return Value

Object. On success, returns the child node that was inserted.

C/C++ Syntax

Copy Code 
HRESULT insertBefore(
  IXMLDOMNode* 
newChild,
  VARIANT 
refChild,
  IXMLDOMNode** 
outNewChild
);

Remarks

C/C++ Parameters

newChild

[in] Address of the new node to be inserted.

refChild

[in] Address of the reference node; newChildis inserted to the left of refChild. If Null, newChildis inserted at the end of the child list.

outNewChild

[out, retval] On success, the child node that was inserted. If Null, no object is created.

C/C++ Return Values

S_OK

Value returned if successful.

E_INVALIDARG

Value returned if newChildis Null.

E_FAIL

Value returned if an error occurs.

Requirements

Header msxml2.h, msxml2.idl
Library uuid.lib
Windows Embedded CE Windows CE .NET 4.0 and later

General Remarks

This operation depends on the value of the nodeTypeproperty.

NODE_ATTRIBUTE

This operation depends on the value of the newChildparameter.

Value Description

NODE_ATTRIBUTE, NODE_CDATA_SECTION, NODE_COMMENT, NODE_DOCUMENT, NODE_DOCUMENT_TYPE, NODE_ELEMENT, NODE_ENTITY, NODE_NOTATION, NODE_PROCESSING_INSTRUCTION

Returns an error. These node types cannot be children of an attribute.

NODE_DOCUMENT_FRAGMENT

Inserts the children of the document fragment ( newChild) and returns newChild.

NODE_ENTITY_REFERENCE, NODE_TEXT

Inserts newChildand returns newChild.

NODE_CDATA_SECTION, NODE_COMMENT, NODE_ENTITY, NODE_NOTATION, NODE_PROCESSING_INSTRUCTION, NODE_TEXT

Returns an error. These node types either cannot have children or their children are read-only.

NODE_DOCUMENT

This operation depends on the value of the newChildparameter.

Value Description

NODE_ATTRIBUTE, NODE_CDATA_SECTION, NODE_DOCUMENT, NODE_ENTITY, NODE_ENTITY_REFERENCE, NODE_NOTATION, NODE_TEXT

Returns an error. These nodes are not valid as children of a document node.

NODE_COMMENT, NODE_PROCESSING_INSTRUCTION

Inserts newChildand returns newChild.

NODE_ELEMENT

Inserts newChildand returns newChild. By definition, an XML document (the Document node) can have only a single child. Therefore, an error is returned if the Document node already has a child.

NODE_DOCUMENT_FRAGMENT

Inserts the children of the document fragment (in newChild) and returns newChild. The insert operations are subject to the rules for child nodes and can fail if the document fragment children represent node types that cannot be inserted.

NODE_DOCUMENT_TYPE

Returns an error. The document type is read-only.

NODE_DOCUMENT_FRAGMENT

This operation depends on the value of the newChildparameter.

Value Description

NODE_ATTRIBUTE, NODE_DOCUMENT, NODE_DOCUMENT_TYPE

Returns an error. These nodes types are not valid as children of a document fragment.

NODE_CDATA_SECTION, NODE_COMMENT, NODE_ELEMENT, NODE_ENTITY_REFERENCE, NODE_PROCESSING_INSTRUCTION, NODE_TEXT

Inserts newChildand returns newChild.

NODE_DOCUMENT_FRAGMENT

Inserts the children of the document fragment ( newChild) and returns newChild.

NODE_ENTITY, NODE_NOTATION

Returns an error. Entities and notations are read-only and cannot be inserted into a document.

NODE_ELEMENT

This operation depends on the value of the newChildparameter.

Value Description

NODE_CDATA_SECTION, NODE_COMMENT, NODE_ELEMENT, NODE_ENTITY_REFERENCE, NODE_TEXT, NODE_PROCESSING_INSTRUCTION

Inserts newChildand returns newChild.

NODE_ATTRIBUTE, NODE_DOCUMENT, NODE_DOCUMENT_TYPE, NODE_ENTITY, NODE_NOTATION

Returns an error. These node types cannot be children of an element node.

NODE_DOCUMENT_FRAGMENT

Inserts the children of the document fragment ( newChild) and returns newChild.

NODE_ENTITY_REFERENCE

Returns an error. Although the child nodes of an entity reference are the expanded entity, the children cannot be modified.

The node supplied in refChildmust be a child node of this node or Null. The newChildis inserted before refChild(as the left sibling) in the child list. If refChildis Null, newChildis inserted at the end of the child list. If refChildis not a child of this node, an error is returned.

If newChildis a node of type DOCUMENT_FRAGMENT, all its children are inserted, in the same order, before refChild. If newChildis already in the tree, it is first removed.

These parameters can represent nodes in the same or different documents. When in the same document, the nodes retain their default attributes and data types. When these parameters represent nodes in different documents, the nodes either lose or alter their default attributes, depending on whether this node's document has a document type definition (DTD) or other schema. The Microsoft implementation attempts to correctly merge the different DTDs.

If the newChildnode's DTD or schema differs from 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 (attributes lose their data types), and default attributes are lost. Note also that cutting and pasting between documents with two different DTDs can result in an invalid document that can fail to parse after being saved.

When elements are added as children to other elements, they introduce their own namespace scoping. That is, if the element is from a default namespace, the default has scope beginning with the element being added.

If an entity reference is being added as a child to an element or document fragment, the namespace declaration of the entity reference is added to the containing element. In a similar way, if the entity reference is being added to an attribute, the namespace and the prefix of the entity reference are added to the element containing the attribute.

If there is a conflict between prefixes on the containing element and the prefixes being added, the insertBeforemethod 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.

Copy Code 
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 Method("attribute","myns:myname","URN2").

Copy Code 
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, insertBeforereturns an error.

This method applies to the following objects and interfaces:

IXMLDOMAttribute, IXMLDOMCDATASection, IXMLDOMCharacterData, IXMLDOMComment, DOMDocument, IXMLDOMDocumentFragment, IXMLDOMDocumentType, IXMLDOMElement, IXMLDOMEntity, IXMLDOMEntityReference, IXMLDOMNode, IXMLDOMNotation, IXMLDOMProcessingInstruction, IXMLDOMText, and IXTLRuntime.

See Also

Concepts

nodeType Property

Other Resources