Section F. The document object | ppk on JavaScript. Modern, Accessible, Unobtrusive JavaScript Explained by Means of Eight Real-World Example Scripts2006

F. The document object

By far the most important object in a window object is the document object, which represents the HTML page the window currently contains. It holds a lot of information, and it also allows you to change the document on the fly. In fact, 80% of the scripts you write are concerned only with the document object and its numerous child objects.

The document object contains a node object for every single HTML element in the page. We'll discuss these W3C DOM node objects in detail in Chapter 8. In addition, the document has many more methods and properties, some of which are W3C DOM-compatible, others remnants of older, proprietary DOMs.

There are a few document methods and properties that are not a part of any DOM, and that give information about the document as a whole. In this section we'll take a look at a few of these miscellaneous methods and properties. (We'll treat one of them, document.cookie, in the next section.)

lastModified

The document.lastModified property contains the last modification date of the document, provided that the server adds it to the document headers. If the server doesn't send this header, some browsers will decide the document was last modified today, while others maintain that it was last modified on 1 January 1970.

If the server does send a last-modified date, you initially receive it as a string. This string is browser-dependent. Here are a few:

01/22/2006 18:16:25 // Explorer Windows Sunday, January 22, 2006 18:16:25 // Mozilla Sun Jan 22 2006 18:16:25 // Safari

For this reason, among others, it's best to convert the last-modified time to a date object:

var lastMod = new Date(document.lastModified);

referrer

The document.referrer property contains the referrer to the current page, i.e., the URL of the page that brought the user to your page. If there is no such page, because the user typed in the URL or used a bookmark, then document.referrer is empty.

In general it's not a good idea to rely on document.referrer for security, since it can be spoofed by malicious surfers.

domain

The document.domain property allows you to circumvent the strictest part of JavaScript's same-source policy. We already discussed its use in 1B.

write()

The document.write() method allows you to write text to the page:

document.write('<h1>Hello world!</h1>');

Now the <h1> is inserted at the location of the document.write(). Although with the advent of the W3C DOM this way of creating dynamic HTML pages has become obsolete, document.write() was once the most important JavaScript method, and you'll often encounter it in scripts written before, say, 2002. Nowadays it's not important any more, except in one very specific situation that we'll discuss in 9C.

It is important to realize that a document.write() works properly only if it's executed while the page is being loaded. In addition, the written text appears exactly at the place the document.write() is called.

For instance, take this page:

<html> <body> <script type="text/javascript"> document.write('<h1>Hello world!</h1>'); </script> <p>I am a JavaScript hacker.</p> </body> </html>

Figure 6.6. document.write() writes new content into the page.

The <h1> appears in place of the <script> tag: above the paragraph. If you want the <h1> to appear below the paragraph, you would do this:

<html> <body> <script type="text/javascript"> function sayHello() {    document.write('<h1>Hello world!</h1>'); } </script> <p>I am a JavaScript hacker.</p> <script type="text/javascript"> sayHello(); </script> </body> </html>

One warning: if you execute document.write() after the page has been loaded, the browser interprets it as a command to destroy the old document and to create a new one. To understand this behavior, we have to discuss two more methods.

open() and close()

You are allowed to create a new HTML document in JavaScript. To do that, you first have to open the document, then write in it, and then close it. For example:

<script type="text/javascript"> document.open(); document.write('<h1>Hello world!</h1>'); document.close(); </script>

First the document is opened, and at that point the old document is destroyed. Then you write something in the new document, and afterwards you close it.

The document.open() method is not required. If, after a page has been completely loaded, you command JavaScript to write() something, it assumes that you want to open a new document, and it destroys the current page.

Therefore, this doesn't work:

   <a href="somepage.html" >  <script>  window.onload = function () {  document.getElementById('clickTest').onclick = function () {             document.write('You clicked me!');     }  }  </script>

The click event fires after the page has been loaded, and therefore the browser assumes that you want to open a new document, and destroys the old one. In its place, it shows a new document with the single line 'You clicked me!'

Figure 6.7. When document.write() is called after a page loads, it destroys the old page and creates a new one to write the message.

Writing into a popup

document.write() is occasionally used in combination with a popup:

var newWin = window.open('','newWin',[arguments]); newWin.document.write('<h1>Hello world!</h1>'); newWin.document.write('<p>I am a JavaScript hacker!</p>'); newWin.document.close();

This used to be especially handy if you needed your own debugging window:

var debug = window.open('','newWin',[arguments]); function addDebuggingMessage(msg) {    debug.document.write(msg + '<br>'); }

Note that in this case you do not use the document.close() method. You want the popup to remain open for writing, because later on you're going to call the function from anywhere you need it:

function doSomething() {    var x = [something complicated that's not what you expected];     addDebuggingMessage('x is ' + x.nodeName); }

Nowadays it's also possible to embed such a debugging window in your document and use the createTextNode() and appendChild() methods we'll discuss in 8D and 8E to write your debugging messages. See 3E for an example.