xmldom is a javascript ponyfill for the following APIs supported in browsers:
- convert an XML string into a DOM tree (
new DOMParser().parseFromString(xml, mimeType)
=>Document
) - create, access and modify a DOM tree (
new DOMImplementation().createDocument(...)
=>Document
, ) - serialize a DOM tree back into an XML string (
new XMLSerializer().serializeToString(node)
=>string
)
Note that this xmldom
library is not required if your code targets a modern browser. But this library is recommended if your code needs to also work in other runtimes like NodeJS or Rhino.
The implementation is based on several specifications:
From the W3C DOM Parsing and Serialization (WD 2016) xmldom
provides an implementation for the interfaces:
DOMParser
XMLSerializer
Note that there are some known deviations between this implementation and the W3 specifications.
Note: The latest version of this spec has the status "Editors Draft", since it is under active development. One major change is that the definition of the DOMParser
interface has been moved to the HTML spec
The original author claims that xmldom implements [DOM Level 2] in a "fully compatible" way and some parts of [DOM Level 3], but there are not enough tests to prove this. Both Specifications are now superseded by the [DOM Level 4 aka Living standard] wich has a much broader scope than xmldom.
xmldom implements the following interfaces (most constructors are currently not exposed):
Attr
CDATASection
CharacterData
Comment
Document
DocumentFragment
DocumentType
DOMException
(constructor exposed)DOMImplementation
(constructor exposed)Element
Entity
EntityReference
LiveNodeList
NamedNodeMap
Node
(constructor exposed)NodeList
Notation
ProcessingInstruction
Text
more details are available in the (incomplete) API Reference section.
xmldom does not have any goal of supporting the full spec, but it has some capability to parse, report and serialize things differently when "detecting HTML" (by checking the default namespace). There is an upcoming change to better align the implementation with the latest specs, related to xmldom#203.
xmldom has an own SAX parser implementation to do the actual parsing, which implements some interfaces in alignment with the Java interfaces SAX defines:
XMLReader
DOMHandler
There is an idea/proposal to make ti possible to replace it with something else in xmldom#55
Original project location: https://github.com/jindw/xmldom
More details about the transition can be found in the CHANGELOG and in xmldom#62
npm install xmldom
const { DOMParser } = require('xmldom')
const doc = new DOMParser().parseFromString(
'<xml xmlns="a" xmlns:c="./lite">\n' +
'\t<child>test</child>\n' +
'\t<child></child>\n' +
'\t<child/>\n' +
'</xml>',
'text/xml'
)
doc.documentElement.setAttribute('x', 'y')
doc.documentElement.setAttributeNS('./lite', 'c:x', 'y2')
console.info(doc)
const nsAttr = doc.documentElement.getAttributeNS('./lite', 'x')
console.info(nsAttr)
Note: in Typescript and ES6 you can use the import approach, as follows:
import { DOMParser } from 'xmldom'
-
parseFromString(xmlsource,mimeType)
- options extension by xmldom(not BOM standard!!)
//added the options argument new DOMParser(options) //errorHandler is supported new DOMParser({ /** * locator is always need for error position info */ locator:{}, /** * you can override the errorHandler for xml parser * @link http://www.saxproject.org/apidoc/org/xml/sax/ErrorHandler.html */ errorHandler:{warning:function(w){console.warn(w)},error:callback,fatalError:callback} //only callback model //errorHandler:function(level,msg){console.log(level,msg)} })
-
serializeToString(node)
-
attribute: nodeValue|prefix readonly attribute: nodeName|nodeType|parentNode|childNodes|firstChild|lastChild|previousSibling|nextSibling|attributes|ownerDocument|namespaceURI|localName method: insertBefore(newChild, refChild) replaceChild(newChild, oldChild) removeChild(oldChild) appendChild(newChild) hasChildNodes() cloneNode(deep) normalize() isSupported(feature, version) hasAttributes()
-
DOMException The DOMException class has the following constants (and
value
of typeNumber
):DOMException.INDEX_SIZE_ERR
(1
)DOMException.DOMSTRING_SIZE_ERR
(2
)DOMException.HIERARCHY_REQUEST_ERR
(3
)DOMException.WRONG_DOCUMENT_ERR
(4
)DOMException.INVALID_CHARACTER_ERR
(5
)DOMException.NO_DATA_ALLOWED_ERR
(6
)DOMException.NO_MODIFICATION_ALLOWED_ERR
(7
)DOMException.NOT_FOUND_ERR
(8
)DOMException.NOT_SUPPORTED_ERR
(9
)DOMException.INUSE_ATTRIBUTE_ERR
(10
)DOMException.INVALID_STATE_ERR
(11
)DOMException.SYNTAX_ERR
(12
)DOMException.INVALID_MODIFICATION_ERR
(13
)DOMException.NAMESPACE_ERR
(14
)DOMException.INVALID_ACCESS_ERR
(15
)
The DOMException object has the following properties: code This property is of type Number.
- extends the Error type thrown as part of DOM API:
-
method: hasFeature(feature, version) createDocumentType(qualifiedName, publicId, systemId) createDocument(namespaceURI, qualifiedName, doctype)
-
Document : Node
readonly attribute: doctype|implementation|documentElement method: createElement(tagName) createDocumentFragment() createTextNode(data) createComment(data) createCDATASection(data) createProcessingInstruction(target, data) createAttribute(name) createEntityReference(name) getElementsByTagName(tagname) importNode(importedNode, deep) createElementNS(namespaceURI, qualifiedName) createAttributeNS(namespaceURI, qualifiedName) getElementsByTagNameNS(namespaceURI, localName) getElementById(elementId)
-
DocumentFragment : Node
-
Element : Node
readonly attribute: tagName method: getAttribute(name) setAttribute(name, value) removeAttribute(name) getAttributeNode(name) setAttributeNode(newAttr) removeAttributeNode(oldAttr) getElementsByTagName(name) getAttributeNS(namespaceURI, localName) setAttributeNS(namespaceURI, qualifiedName, value) removeAttributeNS(namespaceURI, localName) getAttributeNodeNS(namespaceURI, localName) setAttributeNodeNS(newAttr) getElementsByTagNameNS(namespaceURI, localName) hasAttribute(name) hasAttributeNS(namespaceURI, localName)
-
Attr : Node
attribute: value readonly attribute: name|specified|ownerElement
-
readonly attribute: length method: item(index)
-
readonly attribute: length method: getNamedItem(name) setNamedItem(arg) removeNamedItem(name) item(index) getNamedItemNS(namespaceURI, localName) setNamedItemNS(arg) removeNamedItemNS(namespaceURI, localName)
-
CharacterData : Node
method: substringData(offset, count) appendData(arg) insertData(offset, arg) deleteData(offset, count) replaceData(offset, count, arg)
-
Text : CharacterData
method: splitText(offset)
-
Comment : CharacterData
-
readonly attribute: name|entities|notations|publicId|systemId|internalSubset
-
Notation : Node
readonly attribute: publicId|systemId
-
Entity : Node
readonly attribute: publicId|systemId|notationName
-
EntityReference : Node
-
ProcessingInstruction : Node
attribute: data readonly attribute: target
-
attribute: textContent method: isDefaultNamespace(namespaceURI){ lookupNamespaceURI(prefix)
-
[Node] Source position extension;
attribute: //Numbered starting from '1' lineNumber //Numbered starting from '1' columnNumber