The Document Object Model (DOM), Part 4 (5)

The `replaceNode` Method

The replaceNode method is much more intuitive than the removeNode method. While the removeNode method just removes the specified element and makes its descendents children of their grandfather, the replaceNode method deletes the whole subtree that is rooted at the specified element, and substitutes it with a new element. Let's look at our complex example from the previous page. Instead of deleting the p3Node node (with the removeNode method), we'll replace it with a new node created by the createTextNode method:

<SCRIPT LANGUAGE="JavaScript">
<!--
var msg = "";
function printChildren()  {
   childCount = bodyNode.childNodes.length;
   msg += "bodyNode.childNodes.length = " + bodyNode.
     childNodes.length + "\n" ;
  // (The above two lines should be joined as one line.
  // They have been split for formatting purposes.)
   for(var i = 0; i < childCount; i++)  {
   msg += "bodyNode.childNodes[i].nodeName = " + bodyNode.
     childNodes[i].nodeName + "\n";
  // (The above two lines should be joined as one line.
  // They have been split for formatting purposes.)
   }
}
printChildren();
msg += "Replacing Paragraph 3\n";
var b = document.createTextNode("New Body Page");
var replacedNode = p3Node.replaceNode(b);
msg += "replacedNode.nodeName = " + replacedNode.nodeName + "\n";
msg += "replacedNode.childNodes.length = " + replacedNode.
  childNodes.length + "\n";
  // (The above two lines should be joined as one line.
  // They have been split for formatting purposes.)
msg += "p2Node.nodeName = " + p2Node.nodeName + "\n";
printChildren();
alert(msg);
// -->
</SCRIPT>

Notice how the new page looks different from the original page. The whole paragraph 3 disappeared, including its image and table. A new textual entry, "New Body Page", is now decorating the page in the exact same place where paragraph 3 used to be. The alert box echoes this change just as well. If before the replacement the page had six children, then after the replacement the number of children did not change. The only change at the top level is that a paragraph node is replaced with a text node. Also, you can learn from the alert box that the method returns the replaced node, which is still in contact with its children. There is no change to the subtree rooted at the replaced node. The table, image, and text entries still belong to their father.

Now you know how to remove a whole subtree -- just replace it with an illegal entry. Whenever you provide this method with an illegal substitute, it does remove the node and do not substitute it with the illegal node. Let's try, for example, to replace paragraph 3 with paragraph 2. This script is identical to the one listed above, except that the variable b is now set to p2Node:

<SCRIPT LANGUAGE="JavaScript">
<!--
var msg = "";
function printChildren()  {
   childCount = bodyNode.childNodes.length;
   msg += "bodyNode.childNodes.length = " + bodyNode.
     childNodes.length + "\n" ;
  // (The above two lines should be joined as one line.
  // They have been split for formatting purposes.)
   for(var i = 0; i < childCount; i++)  {
   msg += "bodyNode.childNodes[i].nodeName = " + bodyNode.
     childNodes[i].nodeName + "\n";
  // (The above two lines should be joined as one line.
  // They have been split for formatting purposes.)
   }
}
printChildren();
msg += "Replacing Paragraph 3\n";
var b = p2Node;
var replacedNode = p3Node.replaceNode(b);
msg += "replacedNode.nodeName = " + replacedNode.nodeName + "\n";
msg += "replacedNode.childNodes.length = " + replacedNode.
  childNodes.length + "\n";
  // (The above two lines should be joined as one line.
  // They have been split for formatting purposes.)
msg += "p2Node.nodeName = " + p2Node.nodeName + "\n";
printChildren();
alert(msg);
// -->
</SCRIPT>

Now try this script. Notice that paragraph 3 is removed and not substituted with any element. The alert box also demonstrates the change in the number of top level children from 6 to 5. The method replaceNode() returns the whole tree rooted at p3Node. If you try to replace p3Node with an empty element, p3Node.replaceNode(), the browser will not like it and will abort the script.