TDOMNode_WithChildren.InsertBefore function

Member of TDOMNode_WithChildrenpublicIn unit Laz2_DOM

Inserts a new child node immediately before the reference child node.

Declaration

pascal

function InsertBefore(NewChild: TDOMNode; RefChild: TDOMNode): TDOMNode
 ; override

Arguments

`NewChild`	Child node inserted in the method.
`RefChild`	Reference child node where the new DOM node is inserted as a Sibling.

Function result

DOM Node inserted into the DOM sub-tree.

Description

InsertBefore is a TDOMNode function used to insert a new child node immediately before the reference child node. InsertBefore is an overridden function that re-implements the method defined in the ancestor class.

NewChild contains the Node inserted into the DOM sub-tree for the current DOM Node. RefChild contains the Node that establishes the position where the NewChild Node is inserted in the DOM sub-tree. When RefChild is not assigned (contains Nil), the new child node is appended as a sibling in the DOM sub-tree. No actions are performed in the method when NewChild and RefChild contains the same DOM node.

InsertBefore uses the value in the NodeType property for the NewChild node to determine the actions needed to add the node to the DOM sub-tree. NodeType determines if NewChild requires additional processing before it is added to the DOM sub-tree. Some DOM Node types cannot be added directly to the sub-tree. Only their child nodes are added. No actions are performed for these DOM Node specialization when they do not contain child nodes. InsertBefore raises an EDOMHierarchyRequest exception if ChildNode is not a valid child node type for the current DOM node.

InsertBefore updates the parent, sibling, and child relationships in DOM nodes as they are inserted (or appended) to the DOM sub-tree. The return value contains the NewChild argument with updated values in its ParentNode, PreviousSibling and NextSibling properties.

InsertBefore checks the ParentNode for the RefChild argument to ensure that it resides in the DOM sub-tree for the current DOM Node. An EDOMNotFound exception is raised when it has an assigned value other than the current DOM Node.

InsertBefore calls the Changing method to ensure that neither the current DOM Node nor its ancestor have their read-only Flags set. An exception is raised in Changing if Flags contains the value nfReadonly in either DOM Node.

When the NodeType is DOCUMENT_TYPE_NODE, the OwnerDocument property is examined. An EDOMWrongDocument exception is raised when the NewChild has an assigned value in the OwnerDocument property.

Errors

EDOMWrongDocument: Raised when the OwnerDocument for the current node is not the same as the value in NewChild
EDOMNotFound: Raised when the assigned ParentNode in RefChild is not the same as the current DOM node
EDOMHierarchyRequest: Raised when NewChild is not a valid child node type for the current DOM node