Please note, this is a STATIC archive of website developer.mozilla.org from 03 Nov 2016, cach3.com does not collect or store any user information, there is no "phishing" involved.

nsIDOMParser

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

Document Tags and Contributors

 Contributors to this page: teoli, Hsivonen
 Last updated by: Hsivonen,