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 XML documents (and the XML parser).
Document
objects have a throw-on-dynamic-markup-insertion counter,
which is used in conjunction with the create an element for the token algorithm to
prevent custom element constructors from being
able to use document.open(type,
replace)
, document.close()
, and document.write()
when they are invoked by the parser.
Initially, the counter must be set to zero.
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.
The resulting Document
has an HTML parser associated with it, which can be given
data to parse using document.write()
. (The
type argument is ignored.)
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
" DOMException
if the
Document
is an XML document.
Throws an "InvalidStateError
" DOMException
if the
parser is currently executing a custom element constructor.
open
( url, name, features )Works like the window.open()
method.
Document
objects have an ignore-opens-during-unload counter, which is
used to prevent scripts from invoking the document.open(type, replace)
method
(directly or indirectly) while the document is being
unloaded. Initially, the counter must be set to zero.
The document open steps, given a document and replaceInput, are as follows:
If document is an XML document, then throw
an "InvalidStateError
" DOMException
exception.
If document's throw-on-dynamic-markup-insertion counter is greater
than 0, then throw an "InvalidStateError
"
DOMException
.
If document is not an active document, then return document.
Let window be document's relevant global object.
If document's origin is not same origin to the
origin of the responsible document specified by the entry
settings object, then throw a "SecurityError
"
DOMException
.
If document has an active parser whose script nesting level is greater than 0, then return document.
This basically causes document.open(type, replace)
to be
ignored when it's called in an inline script found during parsing, while still letting it have
an effect when called from a non-parser task such as a timer callback or event handler.
Similarly, if document's ignore-opens-during-unload counter is greater than 0, then return document.
This basically causes document.open(type, replace)
to be
ignored when it's called from a beforeunload
, pagehide
, or unload
event
handler while the Document
is being unloaded.
Let replace be false.
If replaceInput is an ASCII case-insensitive match for "replace
", then set replace to true.
Otherwise, if document's browsing context's session
history contains only one Document
object, and that was the
about:blank
Document
created when document's browsing
context was created, and that
Document
object has never had the unload a document algorithm invoked
on it, then set replace to true.
Abort document.
For each shadow-including inclusive descendant node of document, erase all event listeners and handlers given node.
Erase all event listeners and handlers given window.
Replace all with null within document, without firing any mutation events.
If document is ready for post-load tasks, then set document's reload override flag and set document's reload override buffer to the empty string.
Change document's URL to the URL of the responsible document specified by the entry settings object.
If document's iframe load in progress flag is set, then set document's mute iframe load flag.
Create a new HTML parser and associate it with document. This is a
script-created parser (meaning that it can be closed by the document.open(type, replace)
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 document to "loading
".
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.
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 earlier entries whose Document
object is
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
document, as well as the state of 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(type,
replace)
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 document.
The open(type,
replace)
method must return the result of running the document open
steps with this Document
object and replace.
The type argument is ignored. Also, the document.open(type, replace)
method does
not affect whether a Document
is ready for post-load tasks or
completely loaded.
The open(url, name,
features)
method must run these steps:
If this Document
object is not an active document, then throw an
"InvalidStateError
" DOMException
exception.
Return the result of running the window open steps with url, name, and features.
close
()Closes the input stream that was opened by the document.open(type, replace)
method.
Throws an "InvalidStateError
" DOMException
if the
Document
is an XML document.
Throws an "InvalidStateError
" DOMException
if the
parser is currently executing a custom element constructor.
The close()
method must run the following
steps:
If the Document
object is an XML
document, then throw an "InvalidStateError
"
DOMException
.
If the Document
object's throw-on-dynamic-markup-insertion
counter is greater than zero, then throw an "InvalidStateError
"
DOMException
.
If there is no script-created parser associated with the document, then return.
Insert an explicit "EOF" character at the end of the parser's input stream.
If there is a pending parsing-blocking script, then return.
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(type, replace)
had been
called. In yet more cases, the method is simply ignored, or throws an exception. Users agents
are explicitly allowed to avoid executing
script
elements inserted via this method. And to make matters even 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.
Throws an "InvalidStateError
" DOMException
when
invoked on XML documents.
Throws an "InvalidStateError
" DOMException
if the
parser is currently executing a custom element constructor.
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(type, replace)
. Initially,
the counter must be set to zero.
The document write steps, given a Document
object document
and a string input, are as follows:
If document is an XML document, then throw
an "InvalidStateError
" DOMException
.
If document's throw-on-dynamic-markup-insertion counter is greater
than 0, then throw an "InvalidStateError
"
DOMException
.
If document is not an active document, then return.
If the insertion point is undefined, then:
If document's ignore-opens-during-unload counter is greater than 0 or document's ignore-destructive-writes counter is greater than 0, then return.
Run the document open steps with document and the empty string. If the user refused to allow the document to be unloaded, then return. Otherwise, the insertion point will point at just before the end of the (empty) input stream.
Insert input into the input stream just before the insertion point.
If document's reload override flag is set, then append input to document's reload override buffer.
If there is no pending parsing-blocking script, have the HTML
parser process input, one code point 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. If the parser pause flag is set, the tokenizer will abort immediately
and no HTML will be parsed, per the tokenizer's parser pause
flag check.
The document.write(...)
method, when
invoked, must run the document write steps with this Document
object and
a string that is the concatanation of all arguments passed.
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(type,
replace)
method implicitly first.
Throws an "InvalidStateError
" DOMException
when
invoked on XML documents.
Throws an "InvalidStateError
" DOMException
if the
parser is currently executing a custom element constructor.
The document.writeln(...)
method, when
invoked, must run the document write steps with this Document
object and
a string that is the concatanation of all arguments passed and U+000A LINE FEED.