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
(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 callingnew DOMParser()
, it inherits the calling code's principal (except that for chrome callers the principal is set to the null principal) and thedocumentURI
andbaseURI
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 tonull
.- 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 callingcreateInstance()
, and you don't call theDOMParser
'sinit()
method, attempting to initiate a parsing operation will automatically callinit()
on theDOMParser
with a null principal andnull
pointers fordocumentURI
andbaseURI
.
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");