DOMParser

  • Revision slug: DOM/DOMParser
  • Revision title: DOMParser
  • Revision id: 37414
  • Created:
  • Creator: Sephr
  • Is current revision? No
  • Comment 5 words added, 1 words removed

Revision Content

DOMParser can parse XML or HTML source stored in a string into a DOM Document. DOMParser is specified in DOM Parsing and Serialization (which defines XML parsing but doesn't cover HTML yet).

Note that XMLHttpRequest supports parsing XML and HTML from URL-addressable resources.

For the time being, Firefox extensions can use DOMParser to parse XML (not HTML) from a buffer or from a stream, but this functionality is not available to Web pages.

Creating a DOMParser

To create a DOMParser object from a web page or a chrome script running in a window, simply use new DOMParser(). When you create a DOMParser from a privileged script, you can pass parameters to the constructor, more on that below.

To create a DOMParser when the constructor is not available (e.g., from a JS XPCOM component, a JS module, or an xpcshell test), use:

var parser = Components.classes["@mozilla.org/xmlextras/domparser;1"]
             .createInstance(Components.interfaces.nsIDOMParser);
// optionally, call parser.init(principal, documentURI, baseURI);

Parsing XML

Once you have created a parser object, parsing is easy:

var parser = new DOMParser();
var doc = parser.parseFromString(stringContainingXMLSource, "application/xml");

Error handling

Note that if the parsing process failed, DOMParser currently does not throw an exception, but instead returns an error document (see {{ Bug("45566") }}):

<parsererror xmlns="http://www.mozilla.org/newlayout/xml/parsererror.xml">
(error description)
<sourcetext>(a snippet of the source XML)</sourcetext>
</parsererror>

The parsing errors are also reported to the Error Console, with the document URI (see below) as the source of the error.

Parsing an SVG or HTML document

The DOMParser can also be used to parse a SVG document {{ geckoRelease("10.0") }} or a HTML document {{ geckoRelease("12.0") }}. There are three different results possible, selected by the MIME type given. If the MIME type is text/xml, the resulting object will be an XMLDocument, if the MIME type is text/svg+xml, it will be an SVGDocument and if the MIME type is text/html, it will be an HTMLDocument.

var parser = new DOMParser();
var doc = parser.parseFromString(stringContainingXMLSource, "application/xml");
// returns a Document, but not a SVGDocument nor a HTMLDocument

parser = new DOMParser();
doc = parser.parseFromString(stringContainingXMLSource, "image/svg+xml");
// returns a SVGDocument, which also is a Document.

parser = new DOMParser();
doc = parser.parseFromString(stringContainingHTMLSource, "text/html");
// returns a HTMLDocument, which also is a Document.

DOMParser HTML extension for other browsers and previous Firefox releases

/*
 * DOMParser HTML extension
 * 2012-02-02
 * 
 * By Eli Grey, http://eligrey.com
 * Public domain.
 * NO WARRANTY EXPRESSED OR IMPLIED. USE AT YOUR OWN RISK.
 */

/*global document, DOMParser*/

(function(DOMParser) {
	"use strict";
	
	var
	  DOMParser_proto = DOMParser.prototype
	, real_parseFromString = DOMParser_proto.parseFromString
	;

	try {
		if ((new DOMParser).parseFromString("", "text/html")) {
			// text/html parsing is natively supported
			return;
		}
	} catch (ex /*if ex.result === Components.results.NS_ERROR_NOT_IMPLEMENTED*/) {}

	DOMParser_proto.parseFromString = function(markup, type) {
		if (/^\s*text\/html\s*(?:;|$)/i.test(type)) {
			var
			  doc = document.implementation.createHTMLDocument("")
			, doc_elt = doc.documentElement
			, first_elt
			;
			
			doc_elt.innerHTML = markup;
			first_elt = doc_elt.firstElementChild;
			
			if ( // are we dealing with an entire document or a fragment?
				   doc_elt.childElementCount === 1
				&& first_elt.localName.toLowerCase() === "html"
			) {
				doc.replaceChild(first_elt, doc_elt);
			}
			
			return doc;
		} else {
			return real_parseFromString.apply(this, arguments);
		}
	};
}(DOMParser));

Principals, document and base URI

{{ Note("This section covers changes introduced to DOMParser in Gecko 1.9.") }}

(This section is only relevant to Firefox extensions--not to Web content.)

To create a document, the parser needs to specify a principal (see Security check basics), a base URI (see document.baseURIObject), and a documentURI.

These values are automatically determined as defined below, but if you work with DOMParser from privileged code, you can override the defaults by providing arguments to the DOMParser constructor or calling parser.init(). Usually you don't need to do that. If you come across a situation when these matter, feel free to ask questions in mozilla.dev.tech.dom and update this documentation to mention these cases.

  • When a DOMParser is instantiated by calling new DOMParser(), it inherits the calling code's principal (except that for chrome callers the principal is set to the null principal) and the documentURI and baseURI of the window the constructor came from.
  • If the caller has UniversalXPConnect privileges, it can pass parameters to new DOMParser(). If fewer than three parameters are passed, the remaining parameters will default to null.
    • The first parameter is the principal to use; this overrides the default principal normally inherited.
    • The second parameter is the documentURI to use.
    • The third parameter is the baseURI to use.
  • If you instantiate a DOMParser by calling createInstance(), and you don't call the DOMParser's init() method, attempting to initiate a parsing operation will automatically call init() on the DOMParser with a null principal and null pointers for documentURI and baseURI.

Cases where these values matter:

  • If you don't specify the document URI by calling init() after creating the parser via createInstance() the created documents will use a moz-nullprincipal:{<guid>} URI, which will show in the Error Console in parsing errors, in particular.
  • Supposedly, if you want to create objects that some particular set of unprivileged code will be able to access (see discussion in {{ Bug("565480") }}).

Examples

Within the context of a window:

var parser = new DOMParser();
var doc = parser.parseFromString(aStr, "application/xml");

Outside of a window (e.g., a JS XPCOM component, a JS module, or an xpcshell test):

var parser = Components.classes["@mozilla.org/xmlextras/domparser;1"]
             .createInstance(Components.interfaces.nsIDOMParser);
var doc = parser.parseFromString(aStr, "application/xml");

Using Components.Constructor():

const DOMParser = new Components.Constructor("@mozilla.org/xmlextras/domparser;1", "nsIDOMParser");
var parser = new DOMParser();
parser.init(principal, documentURI, baseURI);
var doc = parser.parseFromString(aStr, "application/xml");

Browser compatibility

{{ CompatibilityTable() }}

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
XML support {{ CompatVersionUnknown() }} {{ CompatVersionUnknown() }} {{ CompatVersionUnknown() }} {{ CompatVersionUnknown() }} {{ CompatVersionUnknown() }}
SVG support {{ CompatUnknown() }} {{ CompatGeckoDesktop("10") }} {{ CompatUnknown() }} {{ CompatUnknown() }} {{ CompatUnknown() }}
HTML support {{ CompatUnknown() }} {{ CompatGeckoDesktop("12") }} {{ CompatUnknown() }} {{ CompatUnknown() }} {{ CompatUnknown() }}
Feature Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
XML support {{ CompatVersionUnknown() }} {{ CompatVersionUnknown() }} {{ CompatUnknown() }} {{ CompatVersionUnknown() }} {{ CompatUnknown() }}
SVG support {{ CompatUnknown() }} {{ CompatGeckoMobile("10") }} {{ CompatUnknown() }} {{ CompatUnknown() }} {{ CompatUnknown() }}
HTML support {{ CompatUnknown() }} {{ CompatGeckoMobile("12") }} {{ CompatUnknown() }} {{ CompatUnknown() }} {{ CompatUnknown() }}

 

See also

{{ languages( { "fr": "fr/DOMParser", "ja": "ja/DOMParser" } ) }}

Revision Source

<p><code>DOMParser</code> can parse XML or HTML source stored in a string into a DOM <a href="/en/DOM/document" title="document">Document</a>. <code>DOMParser</code> is specified in <a class="external" href="http://html5.org/specs/dom-parsing.html" title="http://html5.org/specs/dom-parsing.html">DOM Parsing and Serialization</a> (which defines XML parsing but doesn't cover HTML yet).</p>
<p>Note that <a href="/en/DOM/XMLHttpRequest" title="en/DOM/XMLHttpRequest">XMLHttpRequest</a> supports parsing XML and HTML from URL-addressable resources.</p>
<p>For the time being, Firefox extensions can use <code>DOMParser</code> to parse XML (not HTML) from a buffer or from a stream, but this functionality is not available to Web pages.</p>
<h2>Creating a DOMParser</h2>
<p>To create a <code>DOMParser</code> object from a web page or a chrome script running in a window, simply use <code>new DOMParser()</code>. When you create a <code>DOMParser</code> from a privileged script, you can pass parameters to the constructor, more on that below.</p>
<p>To create a <code>DOMParser</code> when the constructor is not available (e.g., from a JS XPCOM component, a JS module, or an xpcshell test), use:</p>
<pre class="brush: js">var parser = Components.classes["@mozilla.org/xmlextras/domparser;1"]
             .createInstance(Components.interfaces.nsIDOMParser);
// optionally, call parser.init(principal, documentURI, baseURI);
</pre>
<h2>Parsing XML</h2>
<p>Once you have created a parser object, parsing is easy:</p>
<pre class="brush: js">var parser = new DOMParser();
var doc = parser.parseFromString(stringContainingXMLSource, "application/xml");
</pre>
<h3 name="Error_handling">Error handling</h3>
<p>Note that if the parsing process failed, <code>DOMParser</code> currently does not throw an exception, but instead returns an error document (see {{ Bug("45566") }}):</p>
<pre class="brush: xml">&lt;parsererror xmlns="<span class="nowiki">http://www.mozilla.org/newlayout/xml/parsererror.xml</span>"&gt;
<em>(error description)</em>
&lt;sourcetext&gt;<em>(a snippet of the source XML)</em>&lt;/sourcetext&gt;
&lt;/parsererror&gt;
</pre>
<p>The parsing errors are also reported to the <a href="/en/Error_Console" title="en/Error Console">Error Console</a>, with the document URI (see below) as the source of the error.</p>
<h2>Parsing an SVG or HTML document</h2>
<p>The <code>DOMParser</code> can also be used to parse a SVG document {{ geckoRelease("10.0") }} or a HTML document {{ geckoRelease("12.0") }}. There are three different results possible, selected by the MIME type given. If the MIME type is <code>text/xml</code>, the resulting object will be an <code>XMLDocument</code>, if the MIME type is <code>text/svg+xml</code>, it will be an <code>SVGDocument</code> and if the MIME type is <code>text/html</code>, it will be an <code>HTMLDocument</code>.</p>
<pre class="brush: js">var parser = new DOMParser();
var doc = parser.parseFromString(stringContainingXMLSource, "application/xml");
// returns a Document, but not a SVGDocument nor a HTMLDocument

parser = new DOMParser();
doc = parser.parseFromString(stringContainingXMLSource, "image/svg+xml");
// returns a SVGDocument, which also is a Document.

parser = new DOMParser();
doc = parser.parseFromString(stringContainingHTMLSource, "text/html");
// returns a HTMLDocument, which also is a Document.
</pre>
<h3>DOMParser HTML extension for other browsers and previous Firefox releases</h3>
<pre class="brush: js">/*
 * DOMParser HTML extension
 * 2012-02-02
 * 
 * By Eli Grey, http://eligrey.com
 * Public domain.
 * NO WARRANTY EXPRESSED OR IMPLIED. USE AT YOUR OWN RISK.
 */

/*global document, DOMParser*/

(function(DOMParser) {
	"use strict";
	
	var
	  DOMParser_proto = DOMParser.prototype
	, real_parseFromString = DOMParser_proto.parseFromString
	;

	try {
		if ((new DOMParser).parseFromString("", "text/html")) {
			// text/html parsing is natively supported
			return;
		}
	} catch (ex /*if ex.result === Components.results.NS_ERROR_NOT_IMPLEMENTED*/) {}

	DOMParser_proto.parseFromString = function(markup, type) {
		if (/^\s*text\/html\s*(?:;|$)/i.test(type)) {
			var
			  doc = document.implementation.createHTMLDocument("")
			, doc_elt = doc.documentElement
			, first_elt
			;
			
			doc_elt.innerHTML = markup;
			first_elt = doc_elt.firstElementChild;
			
			if ( // are we dealing with an entire document or a fragment?
				   doc_elt.childElementCount === 1
				&amp;&amp; first_elt.localName.toLowerCase() === "html"
			) {
				doc.replaceChild(first_elt, doc_elt);
			}
			
			return doc;
		} else {
			return real_parseFromString.apply(this, arguments);
		}
	};
}(DOMParser));</pre>
<h2>Principals, document and base URI</h2>
<p>{{ Note("This section covers changes introduced to <code>DOMParser</code> in Gecko 1.9.") }}</p>
<p>(This section is only relevant to Firefox extensions--not to Web content.)</p>
<p>To create a document, the parser needs to specify a principal (see <a href="/en/Security_check_basics" title="en/Security check basics">Security check basics</a>), a base URI (see <a href="/en/DOM/document.baseURIObject" title="en/DOM/document.baseURIObject">document.baseURIObject</a>), and a <a href="/en/DOM/document.documentURI" title="en/DOM/document.documentURI">documentURI</a>.</p>
<p>These values are automatically determined as defined below, but if you work with <code>DOMParser</code> from privileged code, you can override the defaults by providing arguments to the DOMParser constructor or calling <code>parser.init()</code>. Usually you don't need to do that. If you come across a situation when these matter, feel free to ask questions in <a class="external" href="http://groups.google.com/group/mozilla.dev.tech.dom/topics">mozilla.dev.tech.dom</a> and update this documentation to mention these cases.</p>
<ul> <li>When a <code>DOMParser</code> is instantiated by calling <code>new DOMParser()</code>, it inherits the calling code's principal (except that for chrome callers the principal is set to the null principal) and the <code>documentURI</code> and <code>baseURI</code> of the window the constructor came from.</li> <li>If the caller has UniversalXPConnect privileges, it can pass parameters to <code>new DOMParser()</code>. If fewer than three parameters are passed, the remaining parameters will default to <code>null</code>. <ul> <li>The first parameter is the principal to use; this overrides the default principal normally inherited.</li> <li>The second parameter is the <code>documentURI</code> to use.</li> <li>The third parameter is the <code>baseURI</code> to use.</li> </ul> </li> <li>If you instantiate a <code>DOMParser</code> by calling <code>createInstance()</code>, and you don't call the <code>DOMParser</code>'s <code>init()</code> method, attempting to initiate a parsing operation will automatically call <code>init()</code> on the <code>DOMParser</code> with a null principal and <code>null</code> pointers for <code>documentURI</code> and <code>baseURI</code>.</li>
</ul>
<p>Cases where these values matter:</p>
<ul> <li>If you don't specify the document URI by calling init() after creating the parser via <code>createInstance()</code> the created documents will use a moz-nullprincipal:{&lt;guid&gt;} URI, which will show in the Error Console in parsing errors, in particular.</li> <li>Supposedly, if you want to create objects that some particular set of unprivileged code will be able to access (see discussion in {{ Bug("565480") }}).</li>
</ul>
<h2 name="Example">Examples</h2>
<p>Within the context of a window:</p>
<pre class="brush: js">var parser = new DOMParser();
var doc = parser.parseFromString(aStr, "application/xml");
</pre>
<p>Outside of a window (e.g., a JS XPCOM component, a JS module, or an xpcshell test):</p>
<pre class="brush: js">var parser = Components.classes["@mozilla.org/xmlextras/domparser;1"]
             .createInstance(Components.interfaces.nsIDOMParser);
var doc = parser.parseFromString(aStr, "application/xml");
</pre>
<p>Using <code>Components.Constructor()</code>:</p>
<pre class="brush: js">const DOMParser = new Components.Constructor("@mozilla.org/xmlextras/domparser;1", "nsIDOMParser");
var parser = new DOMParser();
parser.init(principal, documentURI, baseURI);
var doc = parser.parseFromString(aStr, "application/xml");
</pre>
<h2 name="Browser_compatibility">Browser compatibility</h2>
<p>{{ CompatibilityTable() }}</p>
<div id="compat-desktop"> <table class="compat-table"> <tbody> <tr> <th>Feature</th> <th>Chrome</th> <th>Firefox (Gecko)</th> <th>Internet Explorer</th> <th>Opera</th> <th>Safari (WebKit)</th> </tr> <tr> <td>XML support</td> <td>{{ CompatVersionUnknown() }}</td> <td>{{ CompatVersionUnknown() }}</td> <td>{{ CompatVersionUnknown() }}</td> <td>{{ CompatVersionUnknown() }}</td> <td>{{ CompatVersionUnknown() }}</td> </tr> <tr> <td>SVG support</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatGeckoDesktop("10") }}</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatUnknown() }}</td> </tr> <tr> <td>HTML support</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatGeckoDesktop("12") }}</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatUnknown() }}</td> </tr> </tbody> </table>
</div>
<div id="compat-mobile"> <table class="compat-table"> <tbody> <tr> <th>Feature</th> <th>Android</th> <th>Firefox Mobile (Gecko)</th> <th>IE Mobile</th> <th>Opera Mobile</th> <th>Safari Mobile</th> </tr> <tr> <td>XML support</td> <td>{{ CompatVersionUnknown() }}</td> <td>{{ CompatVersionUnknown() }}</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatVersionUnknown() }}</td> <td>{{ CompatUnknown() }}</td> </tr> <tr> <td>SVG support</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatGeckoMobile("10") }}</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatUnknown() }}</td> </tr> <tr> <td>HTML support</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatGeckoMobile("12") }}</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatUnknown() }}</td> </tr> </tbody> </table>
</div>
<p> </p>
<h2 name="See_also">See also</h2>
<ul> <li><a href="/en/Parsing_and_serializing_XML" title="en/Parsing_and_serializing_XML">Parsing and serializing XML</a></li> <li><a href="/en/DOM/XMLHttpRequest" title="en/DOM/XMLHttpRequest">XMLHttpRequest</a></li> <li><a href="/en/XMLSerializer" title="en/XMLSerializer">XMLSerializer</a></li> <li><a href="/en/Parsing_HTML_From_Chrome" title="en/Parsing HTML From Chrome">Parsing HTML from chrome</a></li>
</ul>
<p>{{ languages( { "fr": "fr/DOMParser", "ja": "ja/DOMParser" } ) }}</p>
Revert to this revision