3.4 Dynamic markup insertion

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).

3.4.1 Opening the input stream

The open() method comes in several variants with different numbers of arguments.

document = document . 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.

window = 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:

  1. If the Document object is not flagged as an HTML document, throw an InvalidStateError exception and abort these steps.

  2. Let type be the value of the first argument, if there is one, or "text/html" otherwise.

  3. 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.

  4. 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.

  5. Release the storage mutex.

  6. Set the Document's salvageable state to false.

  7. Prompt to unload the Document object. If the user refused to allow the document to be unloaded, then these steps must be aborted.

  8. Unload the Document object, with the recycle parameter set to true.

  9. Abort the Document.

  10. Unregister all event listeners registered on the Document node and its descendants.

  11. Remove any tasks associated with the Document in any task source.

  12. Remove all child nodes of the document, without firing any mutation events.

  13. 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.)

  14. Change the document's character encoding to UTF-8.

  15. Set the Document object's reload override flag and set the Document's reload override buffer to the empty string.

  16. Set the Document's salvageable state back to true.

  17. Change the document's address to the entry script's document's address.

  18. 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.

  19. Set the current document readiness of the document to "loading".

  20. If the type string contains a ";" (U+003B) character, remove the first such character and all characters from it up to the end of the string.

  21. 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 "LF" (U+000A) character, then switch the HTML parser's tokenizer to the PLAINTEXT state.

  22. 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.

  23. Remove any tasks queued by the history traversal task source.

  24. Remove any earlier entries that share the same Document.

  25. 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.

  26. Finally, set the insertion point to point at just before the end of the input stream (which at this point will be empty).

  27. 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.

3.4.2 Closing the input stream

document . 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:

  1. If the Document object is not flagged as an HTML document, throw an InvalidStateError exception and abort these steps.

  2. If there is no script-created parser associated with the document, then abort these steps.

  3. Insert an explicit "EOF" character at the end of the parser's input stream.

  4. If there is a pending parsing-blocking script, then abort these steps.

  5. 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.

3.4.3 document.write()

document . 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:

  1. If the method was invoked on an XML document, throw an InvalidStateError exception and abort these steps.

  2. If the insertion point is undefined and the Document's ignore-destructive-writes counter is greater than zero, then abort these steps.

  3. 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.

  4. Insert the string consisting of the concatenation of all the arguments to the method into the input stream just before the insertion point.

  5. 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.

  6. 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.

  7. Finally, return from the method.

3.4.4 document.writeln()

document . 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).