@xmldom/xmldom
This is a fork of the @xmldom/xmldom that
adds compareDocumentPosition
originally suggested by Rui
Azevedo for the old xmldom
library. It allows the
use of wicked-good-xpath together
with xmldom. For an example see
speech-rule-engine. While
this is not my code, I will try to keep it in sync with developments in the
@xmldom/xmldom
library.
Since version 0.7.0 this package is published to npm as @xmldom/xmldom
and no longer as xmldom
, because we are no longer able to publish xmldom
.
For better readability in the docs we will continue to talk about this library as "xmldom".
xmldom is a javascript ponyfill to provide the following APIs that are present in modern browsers to other runtimes:
- 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
The target runtimes xmldom
supports are currently Node >= v10 (ES5) and Rhino (not tested as part of CI).
When deciding how to fix bugs or implement features, xmldom
tries to stay as close as possible to the various related specifications/standards.
As indicated by the version starting with 0.
, this implementation is not feature complete and some implemented features differ from what the specifications describe.
Issues and PRs for such differences are always welcome, even when they only provide a failing test case.
This project was forked from it's original source in 2019, more details about that transition can be found in the CHANGELOG.
Usage
Install:
npm install @xmldom/xmldom
Example:
In NodeJS
const { DOMParser, XMLSerializer } = require('@xmldom/xmldom')
const source = `<xml xmlns="a">
<child>test</child>
<child/>
</xml>`
const doc = new DOMParser().parseFromString(source, 'text/xml')
const serialized = new XMLSerializer().serializeToString(doc)
Note: in Typescript and ES6(see #316) you can use the import
approach, as follows:
import { DOMParser } from '@xmldom/xmldom'
API Reference
-
DOMParser:
parseFromString(xmlsource,mimeType)
- options extension by xmldom (not DOM standard!!)
new DOMParser(options)
new DOMParser({
locator:{},
errorHandler:{warning:function(w){console.warn(w)},error:callback,fatalError:callback}
})
-
XMLSerializer
serializeToString(node)
DOM level2 method and attribute:
-
Node
readonly class properties (aka NodeType
),
these can be accessed from any Node
instance node
:
if (node.nodeType === node.ELEMENT_NODE) {...
ELEMENT_NODE
(1
)ATTRIBUTE_NODE
(2
)TEXT_NODE
(3
)CDATA_SECTION_NODE
(4
)ENTITY_REFERENCE_NODE
(5
)ENTITY_NODE
(6
)PROCESSING_INSTRUCTION_NODE
(7
)COMMENT_NODE
(8
)DOCUMENT_NODE
(9
)DOCUMENT_TYPE_NODE
(10
)DOCUMENT_FRAGMENT_NODE
(11
)NOTATION_NODE
(12
)
attribute:
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
extends the Error type thrown as part of DOM API.
readonly class properties:
INDEX_SIZE_ERR
(1
)DOMSTRING_SIZE_ERR
(2
)HIERARCHY_REQUEST_ERR
(3
)WRONG_DOCUMENT_ERR
(4
)INVALID_CHARACTER_ERR
(5
)NO_DATA_ALLOWED_ERR
(6
)NO_MODIFICATION_ALLOWED_ERR
(7
)NOT_FOUND_ERR
(8
)NOT_SUPPORTED_ERR
(9
)INUSE_ATTRIBUTE_ERR
(10
)INVALID_STATE_ERR
(11
)SYNTAX_ERR
(12
)INVALID_MODIFICATION_ERR
(13
)NAMESPACE_ERR
(14
)INVALID_ACCESS_ERR
(15
)
attributes:
code
with a value matching one of the above constants.
-
DOMImplementation
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:
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:
readonly attribute:
name
| specified
| ownerElement
-
NodeList
readonly attribute:
method:
-
NamedNodeMap
readonly attribute:
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:
-
CDATASection
-
Comment : CharacterData
-
DocumentType
readonly attribute:
name
| entities
| notations
| publicId
| systemId
| internalSubset
-
Notation : Node
readonly attribute:
-
Entity : Node
readonly attribute:
publicId
| systemId
| notationName
-
EntityReference : Node
-
ProcessingInstruction : Node
attribute:
data
readonly attribute:target
DOM level 3 support:
-
Node
attribute:
method:
isDefaultNamespace(namespaceURI)
lookupNamespaceURI(prefix)
DOM extension by xmldom
Specs
The implementation is based on several specifications:
DOM Parsing and Serialization
From the W3C DOM Parsing and Serialization (WD 2016) xmldom
provides an implementation for the interfaces:
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
DOM
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.
HTML
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 https://github.com/xmldom/xmldom/issues/203.
SAX, XML, XMLNS
xmldom has an own SAX parser implementation to do the actual parsing, which implements some interfaces in alignment with the Java interfaces SAX defines:
There is an idea/proposal to make it possible to replace it with something else in https://github.com/xmldom/xmldom/issues/55