Availability

Navigator 2.0, Internet Explorer 3.0

Description

document.write() appends each of its arguments, in order, to document. String values are appended as is. Numeric values are converted to a string representation, and Boolean values are appended as either the string "true" or the string "false". Object values are converted to strings by invoking their toString() method.

Document.write() is usually used in one of two ways. The first is when it is invoked on the current document within a <SCRIPT> tag or within a function that is executed while the document is still being parsed. In this case, the write() method writes its HTML output as if that output appeared literally in the file, at the location of the code that invoked the method.

The second way that Document.write() is commonly used is to dynamically generate the contents of documents other than that of the current window. In this case, the target document is never in the process of being parsed, and so the output cannot appear "in place" as it does in the case described above. In order for write() to output text into a document, that document must be "open." You can open a document by explicitly calling the Document.open() method, if you choose. In most cases this is unnecessary, however, because when write() is invoked on a document that is "closed," it implicitly opens the document. When a document is opened, any contents that previously appeared in that document are discarded and replaced with a blank document.

Once a document is open, Document.write() can append any amount of output to the end of the document. When a new document has been completely generated by this technique, the document should be closed by calling Document.close(). Note that although the call to open() is usually optional, the call to close() is never optional.

The results of calling Document.write() may not be immediately visible in the targeted web browser window or frame. This is because a web browser may buffer up data to output in larger chunks. Calling Document.close() is the only way to explicitly force all buffered output to be "flushed" and displayed in the browser window. In Navigator 2.0 and 3.0, however, output will be flushed whenever a line break occurs in the output. So for example, outputting the HTML tags <BR>, <HR>, or <P> would force Navigator to display all pending output. This technique does not work in Internet Explorer 3.0, however. In that browser, output is not "flushed" until the enclosing <SCRIPT> tag or event handler function terminates.

Document.write() can also be used in a third way, but only with extreme caution. When an event handler invokes write() on the current document (i.e., the document of which the event handler is a part), the document must first be opened, as we saw above. But opening a document discards any current contents, including any JavaScript code and function definitions. This means that the event handler calling document.write() on its own document cannot rely on any JavaScript functions defined in that document. In general, this technique is best avoided. If you want to dynamically generated documents without having multiple frames or windows visible, it is often easiest to use an invisible frame (one with zero height, for example) to hold the JavaScript code that does the document generation.

See Also

"Document", "Document.close()", "Document.open()", "Document.writeln()", Chapter 14, Documents and Their Contents