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

This specification is based on the original work of the DOM Parsing and Serialization Living Specification, though it has diverged in terms of supported features, normative requirements, and algorithm specificity. As appropriate, relevant fixes from the living specification are incorporated into this document.

This document was published by the Web Platform Working Group as a Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to [email protected] (subscribe, archives) with DOM-Parsing at the start of your email's subject. All comments are 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.

This document is governed by the 1 September 2015 W3C Process Document.

Candidate Recommendation Exit Criteria

This specification will not advance to Proposed Recommendation before the spec's test suite is completed and two or more independent implementations pass each test, although no single implementation must pass each test. We expect to meet this criteria no sooner than 24 October 2014. The group will also create an Implementation Report.

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.

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

The HTML namespace is http://www.w3.org/1999/xhtml.

The XML namespace is http://www.w3.org/XML/1998/namespace.

The XMLNS namespace is http://www.w3.org/2000/xmlns/.

4. Parsing and serializing Nodes

4.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. Let new children be the result of invoking algorithm with markup as the input, and context element as the context element.
  3. Let fragment be a new DocumentFragment whose node document is context element's node document.
  4. Append each node in new children to fragment (in tree order).
    Note

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

  5. Return the value of fragment.

4.2 Serializing

The following steps form the fragment serializing algorithm, whose arguments are a Node node and a flag require well-formed:

  1. Let context document be the value of node's node document.
  2. If context document is an HTML document, return an HTML serialization of node.
  3. Otherwise, context document is an XML document; return an XML serialization of node passing the flag require well-formed.
    Note

    The XML serialization defined in this document conforms to the requirements of the XML fragment serialization algorithm defined in [HTML5].

To produce an HTML serialization of a Node node, the user agent must run the HTML fragment serialization algorithm [HTML5] on node and return the string produced.

To produce an XML serialization of a Node node given a flag require well-formed, run the following steps:

  1. Let context namespace be null. The context namespace is changed when a node serializes a different default namespace definition from its parent. The algorithm assumes no namespace to start.
  2. Let namespace prefix map be a new map for associating namespaceURI and namespace prefix pairs, where namespaceURI values are the map's keys, and prefix values are the map's key values. The namespace prefix map will be populated by previously seen namespaceURIs and their most recent prefix associations for a subtree. Note: the namespace prefix map only associates a single prefix value with a given namespaceURI. During serialization, if different namespace prefixes are found that map to the same namespaceURI, the last one encountered "wins" by replacing the existing key value in the map with the new prefix value.
  3. Initialize the namespace prefix map with the XML namespace key and string "xml" as the key value.
  4. Let generated namespace prefix index be an integer with a value of 1. The generated namespace prefix index is used to generate a new unique prefix value when no suitable existing namespace prefix is available to serialize a node's namespaceURI (or the namespaceURI of one of node's attributes). See the generate a prefix algorithm.
  5. Return the result of running the XML serialization algorithm on node passing the context namespace, namespace prefix map, generated namespace prefix index reference, and the flag require well-formed. If an exception occurs during the execution of the algorithm, then catch that exception and throw a DOMException with name "InvalidStateError".

An XML serialization differs from an HTML serialization in the following ways:

Otherwise, the algorithm for producing an XML serialization is designed to produce a serialization that is compatible with the HTML parser. For example, elements in the HTML namespace that contain no child nodes are serialized with an explicit begin and end tag rather than using the self-closing tag syntax [XML10].

Note

Per [DOM4], Attr objects do not inherit from Node, and thus cannot be serialized by the XML serialization algorithm. An attempt to serialize an Attr object will result in a TypeError exception [WEBIDL].

To run the XML serialization algorithm on a node given a context namespace namespace, a namespace prefix map prefix map, a generated namespace prefix index prefix index, and a flag require well-formed, the user agent must run the appropriate steps, depending on node's interface:

Element

Run the following algorithm:

  1. If the require well-formed flag is set (its value is true), and this node's localName attribute contains the character ":" (U+003A COLON) or does not match the XML Name production [XML10], then throw an exception; the serialization of this node would not be a well-formed element.
  2. Let markup be the string "<" (U+003C LESS-THAN SIGN).
  3. Let qualified name be an empty string.
  4. Let a skip end tag flag have the value false.
  5. Let an ignore namespace definition attribute flag have the value false.
  6. Let map be a copy of the prefix map.
  7. Let element prefixes list be an empty list. This list is local to each element. Its purpose is to ensure that there are no conflicting prefixes should a new namespace prefix attribute need to be generated.
  8. Let duplicate prefix definition be null.
  9. Let local default namespace be the result of recording the namespace information for node given map, element prefixes list, and duplicate prefix definition.
    Note

    This above step will update the map with any found namespace prefix definitions, add the found prefix definitions to the element prefixes list, optionally set the duplicate prefix definition value, and return a local default namespace value defined by a default namespace attribute if one exists. Otherwise it returns null.

  10. Let inherited ns be a copy of namespace.
  11. Let ns be the value of node's namespaceURI attribute.
  12. If inherited ns is equal to ns, then:
    1. If local default namespace is not null, then set ignore namespace definition attribute to true.
    2. If ns is the XML namespace, then let qualified name be the concatenation of the string "xml:" and the value of node's localName.
    3. Otherwise, let qualified name be the value of node's localName. The node's prefix is always dropped.
    4. Append the value of qualified name to markup.
  13. Otherwise, inherited ns is not equal to ns (the node's own namespace is different from the context namespace of its parent). Run these sub-steps:
    1. Let prefix be the value of node's prefix attribute.
    2. Let candidate prefix be a value from map where there exists a key in map that matches the value of ns or if there is no such key, then let candidate prefix be null.
    3. If candidate prefix is not null (a suitable namespace prefix is defined which maps to ns), then:
      1. Let qualified name be the concatenation of candidate prefix, ":" (U+003A COLON), and node's localName. There exists on this node or the node's ancestry a namespace prefix definition that defines the node's namespace.
      2. If local default namespace is not null (there exists a locally-defined default namespace declaration attribute), then let inherited ns get the value of ns.
      3. Append the value of qualified name to markup.
    4. Otherwise, if prefix is not null and local default namespace is null, then:
      1. If the element prefixes list contains the value of prefix, then let prefix be the result of generating a prefix providing as input the namespace prefix map map, node's ns string, and the prefix index integer.
      2. Otherwise, append to map a new key ns whose key value is prefix.
      3. Let qualified name be the concatenation of prefix, ":" (U+003A COLON), and node's localName.
      4. Append the value of qualified name to markup.
      5. Append the following to markup, in the order listed: The following serializes the new namespace/prefix association just added to the map.
        1. " " (U+0020 SPACE);
        2. The string "xmlns:";
        3. The value of prefix;
        4. "="" (U+003D EQUALS SIGN, U+0022 QUOTATION MARK);
        5. The result of serializing an attribute value given ns and the require well-formed flag as input;
        6. """ (U+0022 QUOTATION MARK).
    5. Otherwise, if local default namespace is null, or local default namespace is not null and its value is not equal to ns, then:
      1. Set the ignore namespace definition attribute flag to true.
      2. Let qualified name be the value of node's localName.
      3. Let the value of inherited ns be ns. The new default namespace will be used in the serialization to define this node's namespace and act as the context namespace for its children.
      4. Append the value of qualified name to markup.
      5. Append the following to markup, in the order listed: The following serializes the new (or replacement) default namespace definition.
        1. " " (U+0020 SPACE);
        2. The string "xmlns";
        3. "="" (U+003D EQUALS SIGN, U+0022 QUOTATION MARK);
        4. The result of serializing an attribute value given ns and the require well-formed flag as input;
        5. """ (U+0022 QUOTATION MARK).
    6. Otherwise, the node has a local default namespace that matches ns. Let qualified name be the value of node's localName, let the value of inherited ns be ns, and append the value of qualified name to markup.
  14. Append to markup the result of the XML serialization of node's attributes given the namespace prefix map map, the generated prefix index prefix index, the flag ignore namespace definition attribute and the value of duplicate prefix definition.
  15. If ns is the HTML namespace, and the node's list of children is empty, and the node's localName matches any one of the following void elements: "area", "base", "basefont", "bgsound", "br", "col", "embed", "frame", "hr", "img", "input", "keygen", "link", "menuitem", "meta", "param", "source", "track", "wbr"; then append the following to markup, in the order listed:
    1. " " (U+0020 SPACE);
    2. "/" (U+002F SOLIDUS).
    and set the skip end tag flag to true.
  16. If ns is not the HTML namespace, and the node's list of children is empty, then append "/" (U+002F SOLIDUS) to markup and set the skip end tag flag to true.
  17. Append ">" (U+003E GREATER-THAN SIGN) to markup.
  18. If the value of skip end tag is true, then return the value of markup and skip the remaining steps. The node is a leaf-node.
  19. If ns is the HTML namespace, and the node's localName matches the string "template", then this is a template element. Append to markup the result of running the XML serialization algorithm on the template element's template contents (a DocumentFragment), providing the value of inherited ns for the context namespace, map for the namespace prefix map, prefix index for the generated namespace prefix index, and the value of the require well-formed flag. This allows template content to round-trip , given the rules for parsing XHTML documents [HTML5].
  20. Otherwise, append to markup the result of running the XML serialization algorithm on each of node's children, in tree order, providing the value of inherited ns for the context namespace, map for the namespace prefix map, prefix index for the generated namespace prefix index, and the value of the require well-formed flag.
  21. Append the following to markup, in the order listed:
    1. "</" (U+003C LESS-THAN SIGN, U+002F SOLIDUS);
    2. The value of qualified name;
    3. ">" (U+003E GREATER-THAN SIGN).
  22. Return the value of markup.
Document

If the require well-formed flag is set (its value is true), and this node has no documentElement (the documentElement attribute's value is null), then throw an exception; the serialization of this node would not be a well-formed document.

Otherwise, run the following steps:

  1. Let serialized document be an empty string.
  2. Append to serialized document the string produced by running the steps to produce a DocumentType serialization of node's doctype attribute provided the require well-formed flag if node's doctype attribute is not null.
  3. For each child child of node, in tree order, run the XML serialization algorithm on the child given a context namespace namespace, a namespace prefix map prefix map, a reference to a generated namespace prefix index prefix index, flag require well-formed, and append the result to serialized document.
  4. Return the value of serialized document.
Comment

If the require well-formed flag is set (its value is true), and node's data contains characters that are not matched by the XML Char production [XML10] or contains "--" (two adjacent U+002D HYPHEN-MINUS characters) or that ends with a "-" (U+002D HYPHEN-MINUS) character, then throw an exception; the serialization of this node's data would not be well-formed.

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

Text
  1. If the require well-formed flag is set (its value is true), and node's data contains characters that are not matched by the XML Char production [XML10], then throw an exception; the serialization of this node's data would not be well-formed.
  2. Let markup be the value of node's data.
  3. Replace any occurrences of "&" in markup by "&amp;".
  4. Replace any occurrences of "<" in markup by "&lt;".
  5. Replace any occurrences of ">" in markup by "&gt;".
  6. Return the value of markup.
DocumentFragment
  1. Let markup the empty string.
  2. For each child child of node, in tree order, run the XML serialization algorithm on the child given a context namespace namespace, a namespace prefix map prefix map, a reference to a generated namespace prefix index prefix index, and flag require well-formed. Concatenate the result to markup.
  3. Return the value of markup.
DocumentType
Run the steps to produce a DocumentType serialization of node given the require well-formed flag, and return the string this produced.
ProcessingInstruction
  1. If the require well-formed flag is set (its value is true), and node's target contains a ":" (U+003A COLON) character or is an ASCII case-insensitive match for the string "xml", then throw an exception; the serialization of this node's target would not be well-formed.
  2. If the require well-formed flag is set (its value is true), and node's data contains characters that are not matched by the XML Char production [XML10] or contains the string "?>" (U+003F QUESTION MARK, U+003E GREATER-THAN SIGN), then throw an exception; the serialization of this node's data would not be well-formed.
  3. Let markup be the concatenation of the following, in the order listed:
    1. "<?" (U+003C LESS-THAN SIGN, U+003F QUESTION MARK);
    2. The value of node's target;
    3. " " (U+0020 SPACE);
    4. The value of node's data;
    5. "?>" (U+003F QUESTION MARK, U+003E GREATER-THAN SIGN).
  4. Return the value of markup.

To produce a DocumentType serialization of a Node node, given a require well-formed flag, the user agent must return the result of the following algorithm:

  1. If the require well-formed flag is true and the node's publicId attribute contains characters that are not matched by the XML PubidChar production [XML10], then throw an exception; the serialization of this node would not be a well-formed document type declaration.
  2. If the require well-formed flag is true and the node's systemId attribute contains characters that are not matched by the XML Char production [XML10] or that contains both a """ (U+0022 QUOTATION MARK) and a "'" (U+0027 APOSTROPHE), then throw an exception; the serialization of this node would not be a well-formed document type declaration.
  3. Let markup be an empty string.
  4. Append the string "<!DOCTYPE" to markup.
  5. Append " " (U+0020 SPACE) to markup.
  6. Append the value of the node's name attribute to markup. For a node belonging to an HTML document, the value will be all lowercase.
  7. If the node's publicId is not the empty string then append the following, in the order listed, to markup:
    1. " " (U+0020 SPACE);
    2. The string "PUBLIC";
    3. " " (U+0020 SPACE);
    4. """ (U+0022 QUOTATION MARK);
    5. The value of the node's publicId attribute;
    6. """ (U+0022 QUOTATION MARK).
  8. If the node's systemId is not the empty string and the node's publicId is set to the empty string, then append the following, in the order listed, to markup:
    1. " " (U+0020 SPACE);
    2. The string "SYSTEM".
  9. If the node's systemId is not the empty string then append the following, in the order listed, to markup:
    1. " " (U+0020 SPACE);
    2. """ (U+0022 QUOTATION MARK);
    3. The value of the node's systemId attribute;
    4. """ (U+0022 QUOTATION MARK).
  10. Append ">" (U+003E GREATER-THAN SIGN) to markup.
  11. Return the value of markup.

To record the namespace information for an Element element, given a namespace prefix map map, an element prefixes list (initially empty), and a duplicate prefix definition reference, the user agent must run the following steps:

  1. Let default namespace attr value be null.
  2. Main: For each attribute attr in element's attributes, in the order they are specified in the element's attribute list:
    Note

    The following conditional steps add namespace prefixes into the element prefixes list and add or replace them in the map. Only attributes in the XMLNS namespace are considered (e.g., attributes made to look like namespace declarations via setAttribute("xmlns:pretend-prefix", "pretend-namespace") are not included).

    1. Let attribute namespace be the value of attr's namespaceURI value.
    2. Let attribute prefix be the value of attr's prefix.
    3. If the attribute namespace is the XMLNS namespace, then:
      1. If attribute prefix is null, then attr is a default namespace declaration. Set the default namespace attr value to attr's value and stop running these steps, returning to Main to visit the next attribute.
      2. Otherwise, the attribute prefix is not null and attr is a namespace prefix definition. Run the following steps:
        1. Let prefix definition be the value of attr's localName.
        2. Let namespace definition be the value of attr's value.
        3. If a key matching the value of namespace definition already exists in map, and the key's value matches prefix definition, then this is a duplicate namespace prefix definition. Set the value of duplicate prefix definition to prefix definition.
        4. Otherwise, if the key matching the value of namespace definition already exists in map, but the key's value does not match prefix definition, then update the key's value to be prefix definition.
        5. Otherwise, no key matching the value of namespace definition exists; append to map a new key namespace definition whose key value is the prefix definition.
        6. Append the value of prefix definition to element prefixes list.
  3. Return the value of default namespace attr value.

To generate a prefix given a namespace prefix map map, a string new namespace, and a reference to a generated namespace prefix index prefix index, the user agent must run the following steps:

  1. Let generated prefix be the concatenation of the string "ns" and the current numerical value of prefix index.
  2. Let the value of prefix index be incremented by one.
  3. Append to map a new key new namespace whose key value is the generated prefix.
  4. Return the value of generated prefix.

The XML serialization of the attributes of an Element element together with a namespace prefix map map, a generated prefix index prefix index reference, a flag ignore namespace definition attribute, a duplicate prefix definition value, and a flag require well-formed, is the result of the following algorithm:

  1. Let result be the empty string.
  2. Let localname set be a new empty namespace localname set. This localname set will contain tuples of unique attribute namespaceURI and localName pairs, and is populated as each attr is processed. This set is used to [optionally] enforce the well-formed constraint that an element cannot have two attributes with the same namespaceURI and localName. This can occur when two otherwise identical attributes on the same element differ only by their prefix values.
  3. Main: For each attribute attr in element's attributes, in the order they are specified in the element's attribute list:
    1. If the require well-formed flag is set (its value is true), and the localname set contains a tuple whose values match those of a new tuple consisting of attr's namespaceURI attribute and localName attribute, then throw an exception; the serialization of this attr would fail to produce a well-formed element serialization.
    2. Create a new tuple consisting of attr's namespaceURI attribute and localName attribute, and add it to the localname set.
    3. Let attribute namespace be the value of attr's namespaceURI value.
    4. Let candidate prefix be null.
    5. If attribute namespace is not null, then run these sub-steps:
      1. If the value of attribute namespace is the XMLNS namespace and either the attr's prefix is null and the ignore namespace definition attribute flag is true or the attr's prefix is not null and the attr's localName matches the value of duplicate prefix definition, then stop running these steps and goto Main to visit the next attribute.
      2. Otherwise, if there exists a key in map that matches the value of attribute namespace, then let candidate prefix be that key's value from the map.
      3. Otherwise, there is no key matching attribute namespace in map and the attribute namespace is not the XMLNS namespace. Run these steps:
        1. Let candidate prefix be the result of generating a prefix providing map, attribute namespace, and prefix index as input.
        2. Append the following to result, in the order listed:
          1. " " (U+0020 SPACE);
          2. The string "xmlns:";
          3. The value of candidate prefix;
          4. "="" (U+003D EQUALS SIGN, U+0022 QUOTATION MARK);
          5. The result of serializing an attribute value given attribute namespace and the require well-formed flag as input;
          6. """ (U+0022 QUOTATION MARK).
    6. Append a " " (U+0020 SPACE) to result.
    7. If candidate prefix is not null, then append to result the concatenation of candidate prefix with ":" (U+003A COLON).
    8. If the require well-formed flag is set (its value is true), and this attr's localName attribute contains the character ":" (U+003A COLON) or does not match the XML Name production [XML10] or equals "xmlns" and attribute namespace is null, then throw an exception; the serialization of this attr would not be a well-formed attribute.
    9. Append the following strings to result, in the order listed:
      1. The value of attr's localName;
      2. "="" (U+003D EQUALS SIGN, U+0022 QUOTATION MARK);
      3. The result of serializing an attribute value given attr's value attribute and the require well-formed flag as input;
      4. """ (U+0022 QUOTATION MARK).
  4. Return the value of result.

To serialize an attribute value given an attribute value and require well-formed flag, the user agent must run the following steps:

  1. If the require well-formed flag is set (its value is true), and attribute value contains characters that are not matched by the XML Char production [XML10], then throw an exception; the serialization of this attribute value would fail to produce a well-formed element serialization.
  2. If attribute value is null, then return the empty string.
  3. Otherwise, attribute value is a string. Return the value of attribute value, first replacing any occurrences of the following:
    1. """ with "&quot;"
    2. "&" with "&amp;"
    3. "<" with "&lt;"
    4. ">" with "&gt;"
    Note

    This matches behavior present in browsers, and goes above and beyond the grammar requirement in the XML specification's AttValue production [XML10] by also replacing ">" characters.

5. 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 {
    [NewObject]
    Document parseFromString (DOMString str, SupportedType type);
};

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

    For all XHTML script elements parsed using the XML parser, the equivalent of the scripting flag must be set to "disabled".

  2. If the previous step didn't return an error, return the newly created document.
  3. Let document be a newly-created XML Document. The document will use the Document interface rather than the XMLDocument interface.

  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 the value of document.

In any case, the returned document's content type must be the type argument. Additionally, the document must have a URL value equal to the URL of the active document, a location value of null.

Note

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

ParameterTypeNullableOptionalDescription
strDOMString✘✘
typeSupportedType✘✘
Return type: Document

6. The XMLSerializer interface

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

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

6.1 Methods

serializeToString
The serializeToString(root) method must produce an XML serialization of root passing a value of false for the require well-formed parameter, and return the result.
ParameterTypeNullableOptionalDescription
rootNode✘✘
Return type: DOMString

7. Extensions to the Element interface

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

7.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, return the result of invoking the fragment serializing algorithm on the context object providing true for the require well-formed flag (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, return the result of invoking the fragment serializing algorithm on a fictional node whose only child is the context object providing true for the require well-formed flag (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.
  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.

7.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 DOMException with name "SyntaxError" 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 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".

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

    Throw a DOMException with name "SyntaxError".

  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 context 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
positionDOMString✘✘
textDOMString✘✘
Return type: void

8. Extensions to the Range interface

partial interface Range {
    [CEReactions, NewObject]
    DocumentFragment createContextualFragment (DOMString fragment);
};

8.1 Methods

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

The createContextualFragment(fragment) method must run these steps:

  1. Let node be 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.
  2. If either element is null or the following are all true:

    let element be a new element with

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

A. Revision History

The following is an informative summary of the changes since the last publication of this specification. A complete revision history of the Editor's Drafts of this specification can be found here.

B. Acknowledgements

Thanks to Ms2ger [Mozilla] for maintaining the initial drafts of this specification and for its continued improvement in the Living Specification.

Thanks to Victor Costan, Aryeh Gregor, Anne van Kesteren, Arkadiusz Michalski, Simon Pieters, Henri Sivonen, Josh Soref and Boris Zbarsky, 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.

C. References

C.1 Normative references

[HTML5]
Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Edward O'Connor; Silvia Pfeiffer. W3C. HTML5. 28 October 2014. W3C Recommendation. URL: http://www.w3.org/TR/html5/
[RFC2119]
S. Bradner. IETF. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[WEBIDL]
Cameron McCormack; Boris Zbarsky. W3C. WebIDL Level 1. 8 March 2016. W3C Candidate Recommendation. URL: http://www.w3.org/TR/WebIDL-1/

C.2 Informative references

[DOM4]
Anne van Kesteren; Aryeh Gregor; Ms2ger; Alex Russell; Robin Berjon. W3C. W3C DOM4. 19 November 2015. W3C Recommendation. URL: http://www.w3.org/TR/dom/
[XML10]
Tim Bray; Jean Paoli; Michael Sperberg-McQueen; Eve Maler; François Yergeau et al. W3C. Extensible Markup Language (XML) 1.0 (Fifth Edition). 26 November 2008. W3C Recommendation. URL: http://www.w3.org/TR/xml