W3C

DOM Parsing and Serialization

W3C Working Draft 20 September 2012

This version:
http://www.w3.org/TR/2012/WD-DOM-Parsing-20120920/
Latest published version:
http://www.w3.org/TR/DOM-Parsing/
Latest editor's draft:
http://dvcs.w3.org/hg/innerhtml/raw-file/tip/index.html
Editors:
Travis Leithead, Microsoft Corp.
Ms2ger

Copyright © 2012 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.

Abstract

This specification defines various APIs for programmatic access to HTML and generic XML parsers by web applications for use in parsing and serializing DOM nodes

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

Comments submitted in regard to this document should have their subject line prefixed with the string [DOM-Parsing] to help facilitate tracking on the www-dom mailing list.

This document was published by the Web Applications Working Group as a First Public Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to www-dom@w3.org (subscribe, archives). All feedback is welcome.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

Issues

Various issues are listed in the rest of the document.

Issue 1

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.

1. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [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.

1.1 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], [HTML5], and [XML10].

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

2. Terminology

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

3. Parsing and serializing Nodes

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

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

  6. Return fragment.

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

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
DocumentType
ProcessingInstruction
Issue 2
Define how these are serialized...

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;
    Issue 3

    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

Let markup the concatenation of "<!--", node's data, and "-->".

If markup matches the Comment production, return markup. Otherwise, throw a DOMException with name InvalidStateError.

Text

Let data be node's data.

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

  1. If data doesn't match the CData production, throw a DOMException with name InvalidStateError and terminate the entire algorithm.
  2. Let markup be the concatenation of "<![CDATA[", data, and "]]>".
  3. Return markup.

Otherwise, return data.

DocumentFragment

Let markup the empty string.

For each child of node, in order, produce an XML serialization of the child and concatenate the result to markup.

Return markup.

DocumentType
ProcessingInstruction
Issue 4
TODO

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;
      Issue 5

      escaping / throwing

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

      escaping / throwing

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

4. The DOMParser interface

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

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

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

4.1 Methods

parseFromString

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

Note

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

Note

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

  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.

Issue 7

It is currently unclear what the URL of the returned document should be.

Results for a test case:

GeckoOperaChrome
document.location null
document.URL unsupported unsupported ""
document.documentURI Page URL null null

Anne van Kesteren suggests using the default, about:blank.

Note

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

ParameterTypeNullableOptionalDescription
strDOMString✘✘
typeSupportedType✘✘
Return type: Document

5. The XMLSerializer interface

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

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

5.1 Methods

serializeToString
The serializeToString(root) method must produce an XML serialization of root and return the result.
ParameterTypeNullableOptionalDescription
rootNode✘✘
Return type: DOMString

6. Extensions to the Element interface

enum insertAdjacentHTMLPosition {
    "beforebegin",
    "afterbegin",
    "beforeend",
    "afterend"
};
partial interface Element {
             attribute DOMString innerHTML;
             attribute DOMString outerHTML;
    void insertAdjacentHTML (insertAdjacentHTMLPosition position, DOMString text);
};

6.1 Attributes

innerHTML of type DOMString

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 a DOMException with name InvalidStateError if the Element cannot be serialized to XML, and a DOMException with name SyntaxError if the given string is not well-formed.

On getting, if the context object's node document is an HTML document, then the attribute must return the result of running the HTML fragment serialization algorithm on the context object; otherwise, the context object's node document is an XML document, and the attribute must return the result of running the XML fragment serialization algorithm on the context object instead (this might throw an exception instead of returning a string).

On setting, these steps must be run:

  1. Let fragment be the result of invoking the fragment parsing algorithm with the new value as markup, and the context object as the context element.
  2. Replace all with fragment within the context object.
outerHTML of type DOMString

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 a DOMException with name InvalidStateError if the element cannot be serialized to XML, and a DOMException with name SyntaxError if the given string is not well-formed.

Throws a DOMException with name NoModificationAllowedError if the parent of the element is the Document node.

On getting, if the context object's node document is an HTML document, then the attribute must return the result of running the HTML fragment serialization algorithm on a fictional node whose only child is context object; otherwise, the context object's node document is an XML document, and the attribute must return the result of running the XML fragment serialization algorithm on that fictional node instead (this might throw an exception instead of returning a string).

On setting, the following steps must be run:

  1. Let parent be the context object's parent.
  2. If parent is null, terminate these steps. There would be no way to obtain a reference to the nodes created even if the remaining steps were run.
  3. If parent is a Document, throw a DOMException with name NoModificationAllowedError exception and terminate these steps.
  4. If parent is a DocumentFragment, let parent be a new Element with
  5. Let fragment be the result of invoking the fragment parsing algorithm with the new value as markup, and parent as the context element.
  6. Replace the context object with fragment within the context object's parent.

6.2 Methods

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 TypeError exception if the position argument has an invalid value.

In XML documents, throws a DOMException with name SyntaxError if the given string is not well-formed.

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

The insertAdjacentHTML(position, text) method must run these steps:

  1. Use the first matching item from this list:
    If position is an ASCII case-insensitive match for the string "beforebegin"
    If position is an ASCII case-insensitive match for the string "afterend"

    Let context be the context object's parent.

    If context is null or a document, throw a DOMException with name NoModificationAllowedError and terminate these steps.

    If position is an ASCII case-insensitive match for the string "afterbegin"
    If position is an ASCII case-insensitive match for the string "beforeend"
    Let context be the context object.
  2. If context is not an Element or the following are all true:

    let context be a new Element with

  3. Let fragment be the result of invoking the fragment parsing algorithm with text as markup, and parent as the context element.
  4. Use the first matching item from this list:
    If position is an ASCII case-insensitive match for the string "beforebegin"
    Insert fragment into the context object's parent before the context object.
    If position is an ASCII case-insensitive match for the string "afterbegin"
    Insert fragment into the context object before its first child.
    If position is an ASCII case-insensitive match for the string "beforeend"
    Append fragment to the context object.
    If position is an ASCII case-insensitive match for the string "afterend"
    Insert fragment into the context object's parent before the context object's next sibling.
ParameterTypeNullableOptionalDescription
positioninsertAdjacentHTMLPosition✘✘
textDOMString✘✘
Return type: void

7. Extensions to the Text interface

partial interface Text {
             attribute boolean serializeAsCDATA;
};

7.1 Attributes

serializeAsCDATA of type boolean
text . serializeAsCDATA [ = value ]
Controls whether, in XML, this node is serialized as a CDATA section.

Text nodes have an additional associated flag, the serialize as CDATA flag.

The serializeAsCDATA attribute must return true if the context object has its serialize as CDATA flag set, or false otherwise.

Setting the serializeAsCDATA attribute must, if the new value is true, set the context object's serialize as CDATA flag, or unset it otherwise.

8. Extensions to the Range interface

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

8.1 Methods

createContextualFragment
fragment = range . createContextualFragment(fragment)
Returns a DocumentFragment, created from the markup string given.

The createContextualFragment(fragment) method must run these steps:

  1. If the context object's detached flag is set, throw a DOMException with name InvalidStateError and terminate these steps.
  2. Let node the context object's start node.

    Let element be as follows, depending on node's interface:

    Document
    DocumentFragment
    null
    Element
    node
    Text
    Comment
    node's parent element
    DocumentType
    ProcessingInstruction
    [DOM4] prevents this case.
  3. If either element is null or the following are all true:

    let element be a new element with

  4. Let fragment node be the result of invoking the fragment parsing algorithm with fragment as markup, and element as the context element.
  5. Unmark all scripts in fragment node as "already started".
  6. Return fragment node.
ParameterTypeNullableOptionalDescription
fragmentDOMString✘✘
Return type: DocumentFragment

A. Acknowledgements

Thanks to Ms2ger for maintaining the initial drafts of this specification.

Thanks to Anne van Kesteren, Aryeh Gregor, Henri Sivonen, Simon Pieters and timeless for their useful comments.

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

B. References

B.1 Normative references

[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
[WEBIDL]
Cameron McCormack. Web IDL. 27 September 2011. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2011/WD-WebIDL-20110927/

B.2 Informative references

[DOM4]
Anne van Kesteren; Aryeh Gregor; Ms2ger. DOM4. URL: http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html/
[HTML5]
Ian Hickson; David Hyatt. HTML5. 29 March 2012. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/html5
[XML10]
C. M. Sperberg-McQueen; et al. Extensible Markup Language (XML) 1.0 (Fifth Edition). 26 November 2008. W3C Recommendation. URL: http://www.w3.org/TR/2008/REC-xml-20081126/