WebReference.com - Part 1 of chapter 5 from Creating Applications with Mozilla. From O'Reilly (5/6).

To dynamically add an element to a document, you need to use the method appendChild( ). This method adds a newly created element to an existing parent node by appending to it. If a visible widget is added, this change is visible in the interface immediately.

<groupbox id="my-id" />
<script>
var existingEl  = document.getElementById('my-id');
var captionEl   = document.createElement('caption');
existingEl.appendChild(captionEl);
captionEl.setAttribute('label', 'This is a new caption');
captionEl.setAttribute('style', 'color: blue;');
</script>

This example creates a new element, gets an existing parent element from the document, and then uses appendChild( ) to insert that new element into the document. It also uses setAttribute to add an attribute value and some CSS style rules, which can highlight the new element in the existing interface.

For elements that already exist, a copy method allows you to duplicate elements to avoid having to recreate them from scratch. cloneNode, which is a method on the element object rather than the document, returns a copy of the given node.

<script>
// this is untested --pete
var element = document.getElementById('my-id');
var clone = element.cloneNode(false);
dump('element='+element+'\n');
dump('clone='+clone+'\n');
</script>

The method takes a Boolean-optional parameter that specifies whether the copy is "deep." Deep copies duplicate all descendants of a node as well as the node itself.

Another very useful method is getElementsByTagName. This method returns an array of elements of the specified type. The argument used is the string element type. "box," for example, could be used to obtain an array of all boxes in a document. The array is zero-based, so the elements start at 0 and end with the last occurrence of the element in the document. If you have three boxes in a document and want to reference each box, you can do it as follows:

<box id="box-one" />
<box id="box-two" />
<box id="box-three" />
<script>
document.getElementsByTagName('box')[0];
document.getElementsByTagName('box')[1];
document.getElementsByTagName('box')[2];
</script.

Or you can get the array and index into it like this:

var box = document.getElementsByTagName('box');

box[0], the first object in the returned array, is a XUL box.

To see the number of boxes on a page, you can use the length property of an array:

var len = document.getElementsByTagName('box').length;
dump(l+'\n');
console output: 3

To output the id of the box:

<box id="box-one" />
<box id="box-two" />
<box id="box-three" />
<script>
var el      = document.getElementsByTagName('box');
var tagId   = el[0].id;
dump(tagId+"\n");
</script>
console output: box-one

To get to an attribute of the second box:

<box id="box-one" />
<box id="box-two" foo="some attribute for the second box" />
<box id="box-three" />
<script>
var el        = document.getElementsByTagName('box');
var att       = el[1].getAttribute('foo');
dump(att      +"\n");
</script>
console output: some attribute for the second box