JavaScript: The Definitive Guide, 5th Edition

Name

Node.insertBefore( ): insert a node into the document tree before the specified node — DOM Level 1 Core

Synopsis

Node insertBefore(NodenewChild,
                  Node refChild)
    throws DOMException;

Arguments

newChild

The node to be inserted into the tree. If it is a DocumentFragment, its children are inserted instead.

refChild

The child of this node before which newChild is to be inserted. If this argument is null, newChild is inserted as the last child of this node.

Returns

The node that was inserted.

Throws

This method may throw a DOMException with the following code values:

HIERARCHY_REQUEST_ERR

This node does not support children, it does not allow children of the specified type, or newChild is an ancestor of this node (or is this node itself).

WRONG_DOCUMENT_ERR

The ownerDocument property of newChild and this node are different.

NO_MODIFICATION_ALLOWED_ERR

This node is read-only and does not allow insertions, or the parent of newChild is read-only and does not allow deletions.

NOT_FOUND_ERR

refChild is not a child of this node.

Description

This method inserts the node newChild into the document tree as a child of this node. The new node is positioned within this node’s childNodes[] array so that it comes immediately before the refChild node. If refChild is null, newChild is inserted at the end of childNodes[], just as with the appendChild( ) method. Note that it is illegal to call this method with a refChild that is not a child of this node.

If newChild is already in the document tree, it is removed ...