The Document data type specifies a method called createElement(). It accepts one argument, a string containing the tag name of the element you want to create. It creates an element outside of the currently loaded document and returns an element object. You use it like this:

var el = document.createElement("div");

Here you create a <div/> element by calling the createElement() method and passing it the tag name of div. You do not include any angle brackets — simply the tag name of the element. The resulting element object is saved in the el variable.

This new object is an instance of the HTMLElement data type (another data type included with the DOM), and, more specifically, of an HTMLDivElement. You can see this by calling alert(el) in any browser except Internet Explorer 8 and previous versions. Figure 14-1 shows the result of alert(el) in Internet Explorer 9.

Figure 14.1. Figure 14-1

The fact that this element is an HTMLDivElement isn't necessarily important for the sake of this discussion. But it is important to understand that every HTML element in the HTML specification has a corresponding data type in the DOM specification. This means there are many new data types included with the DOM. For the sake of simplicity, however, you will be introduced to them only when they're relevant.

In the DOM, all HTML element objects are instances of the HTMLElement and Element data types, and because of this all element objects have a certain set of properties and methods you can use to add attributes to the element. The following table lists some of these members:

Useful HTMLElement and Element Members

So, by using a few of these members, you can add more content to an element. The bold lines in the following code do just that:

var el = document.createElement("div");

el.id = "myDiv";
el.setAttribute("align", "center");

In this code, the new <div/> element is given an id of myDiv, and an align property is added to the element with the setAttribute() method. If you were to write the HTML that this code generates, it would look like this:

<div id="myDiv" align="center"></div>

Keep in mind, however, that this element is not yet loaded into the document. You have created the element by using the createElement() method of the document, but it currently exists outside the document. To load it into the document, you need to use the appendChild() method or other insertion methods.

The appendChild() method is a member of the Node data type, the same data type that you looked at in the previous lesson. You see, each HTML element object is an instance of a variety of data types. Not only is an element an instance of HTMLElement and Element, but it is an instance of the Node data type as well. So if you wanted to add this <div/> element to the web page's <body/> element, you could do so by finding the <body/> element's object and using its appendChild() method. Finding <body/> in the DOM is very easy: It's a property of the document object. The bold line in the following code adds the <div/> element created earlier to the page:

var el = document.createElement("div");

el.id = "myDiv";
el.setAttribute("align", "center");

document.body.appendChild(el);

The page's structure looks like Figure 14-2 after this code executes.

Figure 14.2. Figure 14-2

The appendChild() method appends the provided child node to the calling node. So this code places the new element as the last child in the page's body.

Sometimes you will want to append a new node, but not in every case. The insertBefore() method exists for this reason. It too adds a new node as a child of an existing node, but it gives you the ability to decide where, in the list of children, to place it.

The insertBefore() method accepts two arguments. The first is the new node to insert, and the second is a reference node to place the new node in front of. The bold lines in the following code create a new <div/> element and insert it before el from the previous example:

var el = document.createElement("div");

el.id = "myDiv";

el.setAttribute("align", "center");

document.body.appendChild(el);

var el2 = document.createElement("div");

el2.id = "myDiv2";
el2.setAttribute("align", "center");

document.body.insertBefore(el2, el);

Figure 14-3 shows what the DOM structure looks like after this code is executed.

Figure 14.3. Figure 14-3

The elements don't contain any data at the moment, so seeing the results of this code requires tools that can give us an idea of what the DOM currently looks like. I'll save the introduction to those tools until later in the book; now let's add some text to these elements so you can physically see them in the browser.

In the DOM, pieces of text are organized into individual nodes. So it's no surprise that the DOM method to create text actually creates a text node. The method to create a text node is aptly named createTextNode(). It accepts only one argument: the text that is contained within the node. Its usage looks like this:

var text = document.createTextNode("Hello, DOM methods!");

Here a text node containing the text Hello, DOM methods! is created and assigned to the text variable. Text nodes inherit from the Node data type as well, so they can be passed to the appendChild() method like this:

var el = document.createElement("div");
var text = document.createTextNode("Hello, DOM methods!");

el.id = "myDiv";
el.setAttribute("align", "center");

el.appendChild(text);
document.body.appendChild(el);

In this code, the bold lines create and append a text node to the el element from the previous examples.

One thing you might notice in this code is that the text node is appended to the <div/> element before the element is added to the body. Technically, it doesn't matter in what order you append nodes to elements and the document. But remember this: The DOM is a liability as far as performance is concerned. Every time you make a change to the document, the browser has to redraw the page. So, the goal is to limit the amount of times you change the document.

In the example provided here, the text node is added to the <div/> element while both nodes are outside the document itself. This is ideal, as adding the <div/> element to the document (complete with a child text node) requires only one write operation to the document.

Also, as the name of the method implies, createTextNode() creates text, not HTML. The createTextNode() method converts less-than and greater-than signs (< and >) to their HTML entity equivalents (< and >). To demonstrate this, let's return to our ongoing example and add a text node containing the < and > symbols with the following code:

var el = document.createElement("div");
var text = document.createTextNode("Hello, DOM methods!");

el.id = "myDiv";
el.setAttribute("align", "center");

el.appendChild(text);
document.body.appendChild(el);

var el2 = document.createElement("div");
var text2 = document.createTextNode("<b>Will this be bold?</b>");

el2.id = "myDiv2";
el2.setAttribute("align", "center");

el2.appendChild(text2);
document.body.insertBefore(el2, el);

The new lines of code are in bold. The first new line creates a text node containing HTML markup, which will be converted to HTML entities. The second new line adds that node to the <div/> element in el2. You can see the results of this code in Figure 14-4.

Figure 14.4. Figure 14-4

Using DOM methods to create elements is verbose and time-consuming. The payoff, however, is that you have references to the objects you create — you don't have to search the DOM for them. Making modifications to the <div/> element contained within the el variable is as easy as using that variable. So, DOM creation methods are ideal if you plan on modifying those same objects later on, but there is a faster and easier way to add HTML to a page if all you want to do is display it and forget it.

For this lesson, you need a text editor; any plain text editor will do. For Microsoft Windows users, Notepad is available by default on your system or you can download Microsoft's free Visual Web Developer Express (www.microsoft.com/express/web/) or Web Matrix (www.asp.net/webmatrix/). Mac OS X users can use TextMate, which comes as part of OS X, or they can download a trial for Coda (www.panic.com/coda/). Linux users can use the built-in VIM.

You also need a modern web browser. Choose any of the following:

Create a subfolder called Lesson14 in the JS24Hour folder you created in Lesson 1. Store the files you create in this lesson in the Lesson14 folder.

You will write a web page and its content, a shopping list, using the DOM creation methods and innerHTML.

To get the sample code files, you can download Lesson 14 from the book's website at www.wrox.com.