Section 15.1. Dynamic Document Content

15.1. Dynamic Document Content

Let's begin exploring the Document object with its write() method, which allows you to write content into the document. This method is part of the legacy DOM and has been around since the very earliest releases of JavaScript. document.write() can be used in two ways. The first and simplest way to use it is within a script, to output HTML into the document that is currently being parsed. Consider the following code, which uses write() to add the current date to an otherwise static HTML document:

 <script>   var today = new Date();   document.write("<p>Document accessed on: " + today.toString()); </script> 

Be aware, however, that you can use the write() method to output HTML to the current document only while that document is being parsed. That is, you can call document.write() from within top-level code in <script> tags only because these scripts are executed as part of the document parsing process. If you place a document.write() call within a function definition and then call that function from an event handler, it will not work as you expectin fact, it will erase the current document and the scripts it contains! (You'll see why shortly.)

document.write() inserts text into an HTML document at the location of the <script> tag that contains the invocation of the method. If a <script> tag has a defer attribute, it may not contain any calls to document.write(). The defer attribute tells the web browser that it is safe to defer execution of the script until the document is fully loaded. And once that has happened, it is too late for document.write() to insert content into the document while it is being parsed.

Using the write() method to generate document content while the document is being parsed used to be an extremely common JavaScript programming technique. The W3C DOM now allows you to insert content (using techniques you'll learn about later) into any part of a document after the document has been parsed. Nevertheless, this use of document.write() is still fairly common.

You can also use the write() method (in conjunction with the open() and close() methods of the Document object) to create entirely new documents in other windows or frames. Although you cannot usefully write to the current document from an event handler, there is no reason why you can't write to a document in another window or frame; doing so can be a useful technique with multiwindow or multiframe web sites. For example, you might create a pop-up window and write some HTML to it with code like this:

 // This function opens a pop-up window. Invoke it from an event handler // or the pop up will probably be blocked. function hello() {     var w = window.open();             //    Create a new window with no content     var d = w.document;                // Get its Document object     d.open();                             // Start a new document (optional)     d.write("<h1>Hello world!</h1>");  // Output document content     d.close();                           // End the document } 

To create a new document, you first call the open() method of the Document object, then call write() any number of times to output the contents of the document, and finally call the close() method of the Document object to indicate that you're finished. This last step is important; if you forget to close the document, the browser does not stop the document-loading animation it displays. Also, the browser may buffer the HTML you have written; it is not required to display the buffered output until you explicitly end the document by calling close().

In contrast to the close() call, which is required, the open() call is optional. If you call the write() method on a document that has already been closed, JavaScript implicitly opens a new HTML document, as if you had called the open() method. This explains what happens when you call document.write() from an event handler within the same document: JavaScript opens a new document. In the process, however, the current document (and its contents, including scripts and event handlers) is discarded. As a general rule of thumb, a document should never call write() on itself from within an event handler.

A couple of final notes about the write() method. First, many people do not realize that the write() method can take more than one argument. When you pass multiple arguments, they are output one after another, just as if they had been concatenated. So instead of writing:

 document.write("Hello, "  + username + " Welcome to my blog!"); 

you might equivalently write:

 var greeting = "Hello, "; var welcome = " Welcome to my blog!"; document.write(greeting, username, welcome); 

The second point to note about the write() method is that the Document object also supports a writeln() method, which is identical to the write() method in every way except that it appends a newline after outputting its arguments. This can be useful if you are outputting preformatted text within a <pre> tag, for example.

See HTMLDocument in Part IV for complete details on the write(), writeln(), open(), and close() methods.