xml-js-dom

A lightweight library for parsing xml to DOM tree, and vice versa.

Parsing and serializing operations rely on the project xml-js. The DOM implementation is try the best to be compatible with the W3C Recommendation. However, for the sake of convenient usage, subtle changes and differences may be introduced.

The whole project is written by typescript. We strongly recommend you use typescript to reduce silly bugs. Anyway, if typescript isn't your cup of tea, just take this as a regular javascript project.

Basic usage

import {parse, toXml, Node} from "xml-js-dom";

// Parse xml to the DOM tree
const node: Node = parse('<main><a>Hello</a><b>World</b></main>');  
// node is the toppest item of the XML, usually it's an object of Document.

// Serialize DOM tree to XML
const xml: string = toXml(node);    // Now the xml is exactly the content we just parsed.

DOM tree

A DOM tree consists of different kinds of items, like Document, Element, Text, Attribute, etc. All these items are exported by the index module. So you could import any kinds of items like

import {Document, Element, Text, Attribute} from "xml-js-dom";

or in CommonJS mode:

const {Document, Element, Text, Attribute} = requre('xml-js-dom');

API References

Currently only partial of the types and functions of the XML items have been implemented. We're trying our best to work for this. And of course any contributions to this project are great welcome.

Classes & Modules

index

Node
NodeGroup
Document
Element
CharacterData
Text
CDATASection
Attr
ProcessingInstruction
Declaration
Comment

NodeList
NamedNodeMap

Namespace

BackingData

index

[Methods]

parse(xml: string, opts: ParsingOptions = {}): Node | null Parse the giving xml into the DOM tree, and return the root node(usually is a Document) of the tree. The ParsingOptions is similar to XML2JS, with the extra field nodeFactory indicated which factory for producing nodes should be used. (In most case the default factory is good enough)

toXml(node: Node | BackingData, opts: Options.JS2XML = {}): string Serialize the DOM tree into the XML string. Please refer the JS2XML for more infomation.

(back to API references)

Node

[Attributes]

readonly nodeName: string The name of the node. See doc.

nodeValue: string | null The value of the node.

readonly nodeType: number The type of the node. See doc.

parentNode: Node | null The parent of this node.

childNodes: NodeList<Node> All the children belong to this node.

readonly firstChild: Node | null The first node in the child node list.

readonly lastChild: Node | null The last node in the child node list.

readonly previousSibling: Node | null The previous node in the node list which shares the same parent with this node.

readonly nextSibling: Node | null The next node in the node list which shares the same parent with this node.

readonly localName: string | null The local name of this node. That is, the name without the namespace prefix.

prefix: string | null The namespace prefix of this node. The prefix will be automatically inserted to the front of the tag name.

readonly attributes: NamedNodeMap<Attr> | null All the attributes belong to this node.

readonly ownerDocument: Document | null The root document of this node. Null if this node doesn't belong to any DOM tree.

readonly origin: BackingData The data object representing the sub DOM tree. Could be generated by the xml-js and serialized vice versa.

[Methods]

insertBefore(newChild: Node, refChild?: Node | null): Node Insert the new node right before the specific one. If no ref node specified, append the new node to the tail of the child node list. Return the node inserted.

replaceChild(newChild: Node, oldChild: Node): Node Replace the old node with the new node. Error will be thrown if the old node is null or doesn't belong to this node. Return the replaced node.

removeChild(oldChild: Node): Node Remove the specific node. Error will be thrown if the old node doesn't belong to this node. Return the removed node.

removeAllChildren(): void Clear the child node list.

appendChild(newChild: Node): Node Append the new node to the tail of the child node list. Return the appended node.

hasAttributes(): boolean Whether contains attribute nodes.

hasChildNodes(): boolean Whether contains child nodes.

getTextValue(): string Collect and return all the text(including Text and CDATASection) values belong to this node and all the decedents. Using DFS(depth-first-search).

detach(): Node Remove self from the parent node. Return self.

cloneNode(deep?: boolean): Node Duplicate the node (and all the decedents if deep is true). Modify the cloned node is guaranteed NOT infect the original one, and vice versa.

protected _cloneObject(obj: BackingData | BackingData[]): BackingData | BackingData[] The implementation of deep copy of the objects and arrays using by the cloneNode().

(back to API references)

NodeGroup => Node

(back to API references)

Document => NodeGroup

[Attributes]

readonly documentElement: Element | null The direct child element of this document. If multiple child elements exists(which is actually illegal), the first one obtained.

readonly root: Element | null The alias of documentElement

declaration: Declaration | null The declaration of this XML.

[Methods]

importNode(importedNode: Node, deep: boolean): Node Clone the importedNode and return it.

(back to API references)

Element => NodeGroup

[Attributes]

tagName: string The full name of this element. Consists of the namespace prefix and local name.

readonly localName: string The name of this element without the namespace prefix.

prefix: string | null The prefix of the namespace. Change this value will infect the tagName.

text: string This essentially represents the concatenation of all Text and CDATASection nodes in this.childNodes, without the recurse call into child elements. Modify this value will result for clearing ALL the child nodes of this node and appending the Text node.

readonly textTrim: string Similar to text but trim the value returned.

[Methods]

setAttribute(name: string, value: string): void
setAttributeNode(newAttr: Attr): void
Add an attribute to this element.

getAttribute(name: string): string
getAttributeNode(name: string): Attr | undefined
Retrieve the attribute node or value with the specific name.

removeAttribute(name: string): Attr | null
removeAttributeNode(oldAttr: Attr): Attr | null
Remove the specific attribute node and return it.

setNamespace(namespace?: Namespace | null): void
Set the namespace of this element. If the namespace is undefined or null, the namespace of this node will be cleared. The namespace of a child element could be inherited from its ascendants. So if the namespace of the same prefix could be found from the ascendants, (that is, the same url corresponds to the prefix could be found), only the previous xmlns attribute (if any) will be removed and the tagName will be changed. Otherwise, besides the previous xmlns attribute and tagName, a new attribute of xmlns:{prefix}="{url}" will also be added to the element. For example,

<main xmlns="http://app.org">
    <web:sub xmlns:web="http://web.org" />
</main>

If we call

subElement.setNamespace({prefix: '', url: 'http://app.org'});   // subElement represents element <web:sub />

Then we will get

<main xmlns="http://app.org">
    <sub />
</main>

Instead, if we call

subElement.setNamespace({prefix: '', url: 'http://program.org'});   // Again, subElement represents <web:sub />

We will get

<main xmlns="http://app.org">
    <sub xmlns="http://program.org" />
</main>

getNamespace(): Namespace | null Get the namespace of this element. Note that child node could inherit the namespace from its ascendants. So this method may call the ascendants recursively. null will be returned if both prefix and url are empty.

getNamespaceUrl(prefix: string | null): string Get the url of the namespace by the giving prefix. Notice that the prefix doesn't have to be the same as the element's prefix. It will look for the url from ascendants recursively.

protected _constructNsAttrName(prefix: string | null): string Construct the attribute name represents for the namespace. By default, the name is xmlns:{prefix}(colon will be omitted if prefix is empty).

(back to API references)

CharacterData => Node

[Attributes]

data: string The text content of this node.

readonly length: number The length of the content.

[Methods]

appendData(data: string): void Concat the data to the current content.

deleteData(offset: number, count: number): void Remove the substring from offset to offset + count.

insertData(offset: number, data: string): void Insert the data to the position of offset.

replaceData(offset: number, count: number, data: string): void Replace the substring from offset to offset + count with data.

substringData(offset: number, count: number): string Fetch the substring from offset to offset + count.

(back to API references)

Text => CharacterData

[Methods]

splitText(offset: number): Text Split the content from the giving offset position. The former part will be left to this node, while the latter part will be wrapped into a new Text and insert after this node. Return the Text node represents the latter part.

(back to API references)

CDATASection => CharacterData

This is similar to Text, except all the character here will be reserved without escaped.

(back to API references)

Attr => Node

[Attributes]

readonly name: string The name of the attribute.

ownerElement: Element | null The element this attribute node belongs to, or null if it doesn't belong to any element.

value: string The value of the attribute.

valueChangedListener: (attr: Attr) => void | undefined The function be called when the value of this attribute changed. Usually this is using for updating the origin data of the owner element.

[Methods]

detach(): Attr Remove self from the ownerElement and return self.

(back to API references)

ProcessingInstruction => Node

[Attributes]

target: string The target of this processing instruction.

instruction: string The content of this processing instruction.

data: string Alias of instruction.

(back to API references)

Declaration => Node

[Attributes]

ownerDocument: Document | null The document this declaration belongs to.

version: string The version of this XML standard used.

encoding: string The encoding used in this XML. Default is utf-8.

standalone: 'yes' | 'no' | '' It informs the parser whether the document relies on the information from an external source, such as external document type definition (DTD), for its content. The default value is set to no. Setting it to yes tells the processor there are no external declarations required for parsing the document.

(back to API references)

Comment => CharacterData

[Attributes]

data: string The text content of Comment node, which is always an empty string. Being empty ensure that Node.prototype.getTextValue() and Element.prototype.text could return the correct value (without the comment).

length: number The length of the data, which is always 0.

nodeValue: string The actual content of comment.

(back to API references)

NodeList<N extends Node> => Array

[Methods]

item(index: number): N | null Fetch the item at the position of index.

(back to API references)

NamedNodeMap<N extends Node>

[Attributes]

length: number The size of this map.

[Symbol.iterator]: IterableIterator<N> Fetch the iterator of the values of this map.

[Methods]

setNamedItem(node: N): void Add the giving node to this map with the key of the nodeName of the node.

getNamedItem(name: string): N | undefined Fetch the item set before by name.

removeNamedItem(name: string): N | null Remove the item set before by name.

item(index: number): N | null Fetch the item by the giving index. Notice that although this method will return the node according to the order they've been inserted, this behavior has NOT been strictly defined. So use this method only if you exactly know what you're doing.

(back to API references)

Namespace

[Attributes]

prefix: string | null The prefix represents the namespace.

url: string The url identify the namespace.

(back to API references)

BackingData

All the BackingData and its decedents could be referred to xml-js API. Non-compact mode is used here.

(back to API references)