Like we’ve said before, the methods of the Document object are all concerned with modifying the HTML of the document. As usual, a quick example is often the easiest way to explain what we mean. Fire up NotePad once again, and enter the following code:
<HTML>
<HEAD>
<TITLE> Document Methods </TITLE>
</HEAD>
<BODY>
<H1> Document Object Methods </H1>
<SCRIPT LANGUAGE="VBScript">
Document.Write "The current time is " & Now & "."
</SCRIPT>
</BODY>
</HTML>Load up the page and look at the results. It's displaying the current date and time—even though we didn’t enter it in our HTML or have the file processed on the server before it was sent to the client. The language interpreter on the client machine is still interpreting our code—it’s just generating HTML instead of responding to an event and doing things like popping up message boxes or navigating to a new page. If we view the source for this page we’ll still see our script code and not the results, unlike if the script was executing on the server where it would just send us HTML.
All of the Document object’s methods work this way – they modify the HTML as they’re interpreted. If you’re curious you could try a little experiment to show that ASP code is indeed executed earlier than client-side code. Add a few lines of ASP code to the example above to read the current time on the server and output it to the page. When the browser finally finishes rendering the page, you’ll see two time values that differ by a second or two—even if the browser and server are running on the same machine.
Lets take a look at the Write method in a little more detail. This method simply takes a string, and outputs it as part of the HTML stream. Because the text is actually interpreted by a script engine, it can include variable references and function calls, in addition to plain text. The interpreter executes all of the calls and resolves all variables, before sending a final string to the browser.
Since the string is going to the browser, it can (and should) include whatever HTML markup tags are needed. For example, the following Document.Write line displays the current date and time in the Header 1 font of the current browser:
Document.Write "<H1>" & Now & "</H1>"
Calls to the Document.Write method can be interspersed with standard HTML, just as calls to the Response.Write method can be intertwined with HTML on the server.
WriteLn is nearly identical to Write, with one difference that may be important to us depending exactly upon the point at which we need to use the Write methods. WriteLn writes a string to the document just like Write, however it appends a new-line character to the end of each string. Since the HTML specification ignores white space and new-line characters when interpreting standard text, the browser output may look the same, independent of which Write method is used. The only place we’ll see a difference is when the output we’re writing is inside a formatting tag that pays attention to line-feeds. For example, when WriteLn is used inside of a <PRE>...</PRE> block, separate WriteLn statements will result in text that is displayed on separate lines.
One last question you might have regards what happens if Write or WriteLn are used after a page is already loaded—as part of an event handler, for example. We're going to postpone the answer to this question until we’ve covered the Document’s Open, Close, and Clear methods in the next section. You’ll see why afterwards.
As we’ve seen in the example above, it’s possible to use the Write or WriteLn methods by themselves. Sandwiching our calls to Write and WriteLn between a call to the Document object's Open and Close methods gives us more control over when the strings are outputted to the page. In effect, using these methods is like using the buffering ability ASP provides with the Response object.
Although the documentation claims that calling Open after the output stream already has data will clear the output stream, we haven’t been able to see this behavior with Internet Explorer 3.01. Our recommendation is to experiment with these methods on the latest version of your browser, and determine how close your browser, and the browsers your customers may have, come to the original specifications. This omission on the part of the browser isn’t catastrophic—in many cases this functionality isn’t necessary. Perfect software is great, but certainly not a reality in an imperfect world.