mozilla

Revision 53823 of nsIDOMParser

  • Revision slug: nsIDOMParser
  • Revision title: nsIDOMParser
  • Revision id: 53823
  • Created:
  • Creator: Hsivonen
  • Is current revision? Yes
  • Comment Refer to Web platform doc for actual parsing; 31 words added

Revision Content

Note: If you're a web developer, please refer to the DOMParser documentation instead.

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

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

Parsing a string

Once you've created a DOMParser object, you can use its parseFromString method to parse XML or HTML as described in the Web platform documentation.

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");

Revision Source

<div class="note"><strong>Note:</strong> If you're a web developer, please refer to the <a href="/en/DOM/DOMParser" title="en/DOM/DOMParser">DOMParser</a> documentation instead.</div>
<h2 id="Creating_a_DOMParser">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="eval deki-transform">var parser = Components.classes["@mozilla.org/xmlextras/domparser;1"]
             .createInstance(Components.interfaces.nsIDOMParser);
// optionally, call parser.init(principal, documentURI, baseURI);
</pre>
<h2 id="Principals,_document_and_base_URI">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 id="Example" name="Example">Parsing a string</h2>
<p>Once you've created a <code>DOMParser</code> object, you can use its <code>parseFromString</code> method to parse XML or HTML as described in the <a href="/en/DOM/DOMParser" title="en/DOM/DOMParser">Web platform documentation</a>.</p>
<h2 id="Example" name="Example">Examples</h2>
<p>Within the context of a window:</p>
<pre class="eval deki-transform">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="eval deki-transform">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="eval deki-transform">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>
Revert to this revision