APIs for dynamically inserting markup into the document interact with the parser, and thus their behavior varies depending on whether they are used with HTML documents (and the HTML parser) or XHTML in XML documents (and the XML parser).
The open()
method comes in several variants with different numbers of
arguments.
open( [ type [, replace ] ] )Causes the Document to be replaced in-place, as if
it was a new Document object, but reusing the
previous object, which is then returned.
If the type argument is omitted or has the
value "text/html", then the resulting
Document has an HTML parser associated with it, which
can be given data to parse using document.write(). Otherwise, all
content passed to document.write() will be parsed
as plain text.
If the replace argument is present and has
the value "replace", the existing entries in
the session history for the Document object are
removed.
The method has no effect if the Document is still
being parsed.
Throws an InvalidStateError exception if the
Document is an XML
document.
open( url, name, features [, replace ] )Works like the window.open()
method.
When called with two or fewer arguments, the method must act as follows:
Document object is not flagged as an HTML document, throw an
InvalidStateError exception and abort these
steps.Let type be the value of the first
argument, if there is one, or "text/html"
otherwise.
Let replace be true if there is a second argument and it is an ASCII case-insensitive match for the value "replace", and false otherwise.
If the document has an active parser that isn't a
script-created parser, and the insertion
point associated with that parser's input
stream is not undefined (that is, it does point to
somewhere in the input stream), then the method does
nothing. Abort these steps and return the Document
object on which the method was invoked.
This basically causes document.open() to be ignored
when it's called in an inline script found during the parsing of
data sent over the network, while still letting it have an effect
when called asynchronously or on a document that is itself being
spoon-fed using these APIs.
Release the storage mutex.
Set the Document's salvageable state to
false.
Prompt to
unload the Document object. If the user
refused to allow the document to be unloaded, then
these steps must be aborted.
Unload the
Document object, with the recycle
parameter set to true.
Unregister all event listeners registered on the
Document node and its descendants.
Remove any tasks
associated with the Document in any task
source.
Remove all child nodes of the document, without firing any mutation events.
Replace the Document's singleton objects with
new instances of those objects. (This includes in particular the
Window, Location, History,
ApplicationCache, and Navigator, objects,
the various BarProp objects, the two
Storage objects, the various
HTMLCollection objects, and objects defined by other
specifications, like Selection and the document's
UndoManager. It also includes all the Web IDL
prototypes in the JavaScript binding, including the
Document object's prototype.)
Change the document's character encoding to UTF-8.
Set the Document object's reload override
flag and set the Document's reload
override buffer to the empty string.
Set the Document's salvageable state back
to true.
Change the document's address to the entry script's document's address.
Create a new HTML parser and associate it with
the document. This is a script-created parser (meaning
that it can be closed by the document.open() and document.close() methods, and
that the tokenizer will wait for an explicit call to document.close() before emitting
an end-of-file token). The encoding confidence is
irrelevant.
Set the current document readiness of the
document to "loading".
If the type string contains a U+003B SEMICOLON character (;), remove the first such character and all characters from it up to the end of the string.
Strip leading and trailing whitespace from type.
If type is not now an ASCII
case-insensitive match for the string
"text/html", then act as if the tokenizer had emitted
a start tag token with the tag name "pre" followed by a single
U+000A LINE FEED (LF) character, then
switch the HTML parser's tokenizer to the
PLAINTEXT state.
Remove all the entries in the browsing context's session history after the current entry. If the current entry is the last entry in the session history, then no entries are removed.
This doesn't necessarily have to affect the user agent's user interface.
Remove any tasks queued by
the history traversal task source that are associated
with any Document objects in the top-level
browsing context's document family.
Document.If replace is false, then add a new
entry, just before the last entry, and associate with the new entry
the text that was parsed by the previous parser associated with the
Document object, as well as the state of the document
at the start of these steps. This allows the user to step backwards
in the session history to see the page before it was blown away by
the document.open() call.
This new entry does not have a Document object, so a
new one will be created if the session history is traversed to that
entry.
Finally, set the insertion point to point at just before the end of the input stream (which at this point will be empty).
Return the Document on which the method was
invoked.
The document.open() method does not
affect whether a Document is ready for post-load
tasks or completely loaded.
When called with three or more arguments, the open() method on the
Document object must call the open() method on the Window
object of the Document object, with the same
arguments as the original call to the open() method, and return whatever
that method returned. If the Document object has no
Window object, then the method must throw an
InvalidAccessError exception.
close()Closes the input stream that was opened by the document.open() method.
Throws an InvalidStateError exception if the
Document is an XML
document.
The close()
method must run the following steps:
If the Document object is not flagged as an
HTML document, throw an
InvalidStateError exception and abort these
steps.
If there is no script-created parser associated with the document, then abort these steps.
Insert an explicit "EOF" character at the end of the parser's input stream.
If there is a pending parsing-blocking script, then abort these steps.
Run the tokenizer, processing resulting tokens as they are emitted, and stopping when the tokenizer reaches the explicit "EOF" character or spins the event loop.
document.write()write(text...)In general, adds the given string(s) to the
Document's input stream.
This method has very idiosyncratic behavior. In
some cases, this method can affect the state of the HTML
parser while the parser is running, resulting in a DOM that
does not correspond to the source of the document (e.g. if the
string written is the string "<plaintext>" or "<!--"). In other cases, the call can clear the
current page first, as if document.open() had been called.
In yet more cases, the method is simply ignored, or throws an
exception. To make matters worse, the exact behavior of this
method can in some cases be dependent on network latency, which can lead to failures that are very hard to debug.
For all these reasons, use of this method is strongly
discouraged.
This method throws an InvalidStateError exception
when invoked on XML documents.
Document objects have an
ignore-destructive-writes counter, which is used in
conjunction with the processing of script elements to
prevent external scripts from being able to use document.write() to blow away the
document by implicitly calling document.open(). Initially, the
counter must be set to zero.
The document.write(...)
method must act as follows:
If the method was invoked on an XML
document, throw an InvalidStateError
exception and abort these steps.
If the insertion point is undefined and the
Document's ignore-destructive-writes
counter is greater than zero, then abort these steps.
If the insertion point is undefined, call the
open() method on the document object (with no arguments). If
the user refused to allow the document to be
unloaded, then abort these steps. Otherwise, the
insertion point will point at just before the end of
the (empty) input stream.
Insert the string consisting of the concatenation of all the arguments to the method into the input stream just before the insertion point.
If the Document object's reload override
flag is set, then append the string consisting of the
concatenation of all the arguments to the method to the
Document's reload override buffer.
If there is no pending parsing-blocking script,
have the HTML parser process the characters that were
inserted, one at a time, processing resulting tokens as they are
emitted, and stopping when the tokenizer reaches the insertion
point or when the processing of the tokenizer is aborted by the
tree construction stage (this can happen if a script
end tag token is emitted by the tokenizer).
If the document.write() method was
called from script executing inline (i.e. executing because the
parser parsed a set of script tags), then this is a
reentrant invocation of the
parser.
Finally, return from the method.
document.writeln()writeln(text...)Adds the given string(s) to the Document's input
stream, followed by a newline character. If necessary, calls the
open() method implicitly
first.
This method throws an InvalidStateError exception
when invoked on XML documents.
The document.writeln(...)
method, when invoked, must act as if the document.write() method had been
invoked with the same argument(s), plus an extra argument consisting
of a string containing a single line feed character (U+000A).