DOM Parsing and Serialization

Abstract

This specification aims to describe DOM APIs related to parsing markup into DOM trees and serializing DOM trees into markup, with a strong focus on compatibility with existing content.

Table of contents

Issues

Various issues are listed in the rest of the document.

This specification currently requires using the XML Parser for some APIs, when in an XML document. It is unclear whether consensus can be found for this approach.

Conformance

All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.

The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC2119. For readability, these words do not appear in all uppercase letters in this specification. RFC2119

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and terminate these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)

User agents may impose implementation-specific limits on otherwise unconstrained inputs, e.g. to prevent denial of service attacks, to guard against running out of memory, or to work around platform-specific limitations.

When a method or an attribute is said to call another method or attribute, the user agent must invoke its internal API for that attribute or method so that e.g. the author can't change the behavior by overriding attributes or methods with custom properties or functions in ECMAScript.

Unless otherwise stated, string comparisons are done in a case-sensitive manner.

If an algorithm calls into another algorithm, any exception that is thrown by the latter (unless it is explicitly caught), must cause the former to terminate, and the exception to be propagated up to its caller.

Dependencies

The IDL fragments in this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. WEBIDL

Some of the terms used in this specification are defined in DOM4 and HTML. DOM HTML

Extensibility

Vendor-specific proprietary extensions to this specification are strongly discouraged. Authors must not use such extensions, as doing so reduces interoperability and fragments the user base, allowing only users of specific user agents to access the content in question.

If vendor-specific extensions are needed, the members should be prefixed by vendor-specific strings to prevent clashes with future versions of this specification. Extensions must be defined so that the use of extensions neither contradicts nor causes the non-conformance of functionality defined in the specification.

When vendor-neutral extensions to this specification are needed, either this specification can be updated accordingly, or an extension specification can be written that overrides the requirements in this specification. When someone applying this specification to their activities decides that they will recognise the requirements of such an extension specification, it becomes an applicable specification for the purposes of conformance requirements in this specification.

Terminology

The term context object means the object on which the method or attribute being discussed was called.

Parsing and serializing Nodes

Parsing

The following steps form the fragment parsing algorithm, whose arguments are a markup string and a context element.

1. If the context element's node document is an HTML document: let algorithm be the HTML fragment parsing algorithm.

   If the context element's node document is an XML document: let algorithm be the XML fragment parsing algorithm.

2. Invoke algorithm with markup as the input, and context element as the context element.

3. Let new children be the nodes returned.

4. Let fragment be a new DocumentFragment whose node document is context element's node document.

5. Append each node in new children to fragment (in order).

   This ensures the node document for the new nodes is correct.

6. Return fragment.

Serializing

To serialize a Node node, the user agent must run the following steps:

1. Let document be node's node document.
2. If document is an HTML document, return an HTML serialization of node.
3. Otherwise, document is an XML document. Return an XML serialization of node.

The serialization of a DocumentType node is the string returned by the following steps:

1. Let name be node's name.
2. Let public ID be node's public ID.
3. Let system ID be node's system ID.
4. Let ids be as follows:

   if both public ID and system ID are the empty string

   the empty string

   if system ID is the empty string

   the concatenation of

   1. "PUBLIC";
   2. " "" (U+0020 SPACE, U+0022 QUOTATION MARK);
   3. public ID;
   4. """ (U+0022 QUOTATION MARK).

   if public ID is the empty string

   the concatenation of

   1. "SYSTEM";
   2. " "" (U+0020 SPACE, U+0022 QUOTATION MARK);
   3. system ID;
   4. """ (U+0022 QUOTATION MARK).

   otherwise

   the concatenation of

   1. "PUBLIC";
   2. " "" (U+0020 SPACE, U+0022 QUOTATION MARK);
   3. public ID;
   4. "" "" (U+0022 QUOTATION MARK, U+0020 SPACE, U+0022 QUOTATION MARK);
   5. system ID;
   6. """ (U+0022 QUOTATION MARK).

5. Return the concatenation of

   1. "<!DOCTYPE";
   2. " " (U+0020 SPACE);
   3. name;
   4. " " (U+0020 SPACE);
   5. ids;
   6. ">" (U+003E GREATER-THAN SIGN).

No attempt is made to ensure that the result of this algorithm is sensible if the public or system ID contains a """ character.

To produce an HTML serialization of a Node node, the user agent must run the appropriate steps, depending on node's interface:

Element

Document

DocumentFragment

Run the HTML fragment serialization algorithm on node. Return the returned string.

Comment

Text

You tell me.

DocumentType

Return the serialization of node.

ProcessingInstruction

You tell me.

To produce an XML serialization of a Node node, the user agent must run the appropriate steps, depending on node's interface:

Element

Return the concatenation of the following strings:

1. "<" (U+003C LESS-THAN SIGN);
2. the value of node's tagName attribute;

   escaping / throwing

3. the XML serialization of node's attributes;
4. ">" (U+003E GREATER-THAN SIGN);
5. the serialization of node's children, in order;
6. "</" (U+003C LESS-THAN SIGN, U+002F SOLIDUS);
7. the value of node's tagName attribute;
8. ">" (U+003E GREATER-THAN SIGN).

Document

Run the XML fragment serialization algorithm on node. Return the string this produced.

Comment

Return the concatenation of

1. "<!--" (U+003C LESS-THAN SIGN, U+0021 EXCLAMATION MARK, U+002D HYPHEN-MINUS, U+002D HYPHEN-MINUS);
2. node's data;
3. "-->" (U+002D HYPHEN-MINUS, U+002D HYPHEN-MINUS, U+003E GREATER-THAN SIGN).

Text

1. Let data be node's data.

2. If node has its serialize as CDATA flag set, run the following steps:

   1. If data doesn't match the CData production, throw an InvalidStateError exception and terminate the entire algorithm.
   2. Let markup be the concatenation of "<![CDATA[", data, and "]]>".

3. Otherwise, run the following steps:

   1. Let markup be data.
   2. Replace any occurrences of "&" in markup by "&".
   3. Replace any occurrences of "<" in markup by "<".
   4. Replace any occurrences of ">" in markup by ">".
4. Return markup.

DocumentFragment

1. Let markup be the empty string.
2. For each child of node, in order, produce an XML serialization of the child and concatenate the result to markup.
3. Return markup.

DocumentType

Return the serialization of node.

ProcessingInstruction

Return the concatenation of

1. "<?" (U+003C LESS-THAN SIGN, U+003F QUESTION MARK);
2. node's target;
3. " " (U+0020 SPACE);
4. node's data;
5. "?>" (U+003F QUESTION MARK, U+003E GREATER-THAN SIGN).

The XML serialization of the attributes of an element element is the result of the following algorithm:

1. Let result be the empty string.

2. For each attribute attr in element attributes, in order, append the following strings to result:

   1. " " (U+0020 SPACE);
   2. attr's name;

      escaping / throwing

   3. "="" (U+003D EQUALS SIGN, U+0022 QUOTATION MARK);
   4. attr's value;

      escaping / throwing

   5. """ (U+0022 QUOTATION MARK).
3. Return result.

The DOMParser interface

enum SupportedType {
  "text/html",
  "text/xml",
  "application/xml",
  "application/xhtml+xml",
  "image/svg+xml"
};

[Constructor]
interface DOMParser {
  Document parseFromString(DOMString str, SupportedType type);
};

The DOMParser() constructor must return a new DOMParser object.

The parseFromString(str, type) method must run these steps, depending on type:

"text/html"

Parse str with an HTML parser, and return the newly created document.

The scripting flag must be set to "disabled".

meta elements are not taken into account for the encoding used, as a Unicode stream is passed into the parser.

script elements get marked unexecutable and the contents of noscript get parsed as markup.

"text/xml"

"application/xml"

"application/xhtml+xml"

"image/svg+xml"

1. Parse str with a namespace-enabled XML parser.

2. If the previous step didn't return an error, return the newly created document and terminate these steps.

3. Let document be a newly-created Document.

   The intention is that this document does not support document.load(). It is not clear if it needs to be a XMLDocument for other reasons (such as stringification).

4. Let root be a new Element, with its local name set to "parsererror" and its namespace set to "http://www.mozilla.org/newlayout/xml/parsererror.xml".

   At this point user agents may append nodes to root, for example to describe the nature of the error.

5. Append root to document.

6. Return document.

In any case, the returned document's content type must be the type argument.

The returned document's encoding is the default, UTF-8.

The XMLSerializer interface

[Constructor]
interface XMLSerializer {
  DOMString serializeToString(Node root);
};

The XMLSerializer() constructor must return a new XMLSerializer object.

The serializeToString(root) method must produce an XML serialization of root and return the result.

Extensions to the Element interface

partial interface Element {
  [TreatNullAs=EmptyString] attribute DOMString innerHTML;
  [TreatNullAs=EmptyString] attribute DOMString outerHTML;
  void insertAdjacentHTML(DOMString position, DOMString text);
};

innerHTML

The innerHTML IDL attribute represents the markup of the Element's contents.

element . innerHTML [ = value ]

Returns a fragment of HTML or XML that represents the element's contents.

Can be set, to replace the contents of the element with nodes parsed from the given string.

In the case of an XML document, will throw an InvalidStateError if the Element cannot be serialized to XML, and a SyntaxError if the given string is not well-formed.

outerHTML

The outerHTML IDL attribute represents the markup of the Element and its contents.

element . outerHTML [ = value ]

Returns a fragment of HTML or XML that represents the element and its contents.

Can be set, to replace the element with nodes parsed from the given string.

In the case of an XML document, will throw an InvalidStateError if the element cannot be serialized to XML, and a SyntaxError if the given string is not well-formed.

Throws a NoModificationAllowedError exception if the parent of the element is the Document node.

insertAdjacentHTML()

element . insertAdjacentHTML(position, text)

Parses the given string text as HTML or XML and inserts the resulting nodes into the tree in the position given by the position argument, as follows:

"beforebegin"

Before the element itself.

"afterbegin"

Just inside the element, before its first child.

"beforeend"

Just inside the element, after its last child.

"afterend"

After the element itself.

Throws a SyntaxError exception if the arguments have invalid values (e.g., in the case of an XML document, if the given string is not well-formed).

Throws a NoModificationAllowedError exception if the given position isn't possible (e.g. inserting elements after the root element of a Document).

Extensions to the Text interface

partial interface Text {
  attribute boolean serializeAsCDATA;
};

text . serializeAsCDATA [ = value ]

Controls whether, in XML, this node is serialized as a CDATA section.

Extensions to the Range interface

partial interface Range {
  DocumentFragment createContextualFragment(DOMString fragment);
};

fragment = range . createContextualFragment(fragment)

Returns a DocumentFragment, created from the markup string given.

References

All references are normative unless marked "Non-normative".

Acknowledgements

Thanks to Anne van Kesteren, Aryeh Gregor, Boris Zbarsky, David Håsäther, Henri Sivonen, Ryosuke Niwa, Simon Pieters, timeless and Travis Leithead for their useful comments.

Special thanks to Ian Hickson for defining the innerHTML and outerHTML attributes, and the insertAdjacentHTML() method in HTML and his useful comments. HTML