Builder Functions View on GitHub

Following functions exported by xmlbuilder2 are typically imported with:

const { create, fragment, convert, builder } = require('xmlbuilder2');

create

The create function creates and returns a new XML document. When called without arguments, create creates an empty XML document (one without any child nodes). create accepts an optional parameters object for customizing its behavior. These parameters are explained in below. create also accepts an optional argument defining an XML document to be parsed as detailed in this page.

const { create } = require('xmlbuilder2');

const doc = create({ encoding: "UTF-8" }, '<root><node/></root>');
console.log(doc.end({ prettyPrint: true }));

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <node/>
</root>

const { create } = require('xmlbuilder2');

const doc = create({ encoding: 'UTF-8' });
console.log(doc.end({ prettyPrint: true }));

<?xml version="1.0" encoding="UTF-8"?>

const { create } = require('xmlbuilder2');

const doc = create('<root><foo><bar>foobar</bar></foo></root>');
console.log(doc.end({ prettyPrint: true }));

<?xml version="1.0"?>
<root>
  <foo>
    <bar>foobar</bar>
  </foo>
</root>

const { create } = require('xmlbuilder2');

const doc = create();
console.log(doc.end({ prettyPrint: true }));

<?xml version="1.0"?>

fragment

The fragment function creates and returns a document fragment node. fragment accepts the same types of arguments as with the document function.

const { fragment } = require('xmlbuilder2');

const frag = fragment({ encoding: 'UTF-8' }, '<node/><node>text</node>');
console.log(frag.toString({ prettyPrint: true }));

<node/>
<node>text</node>

const { fragment } = require('xmlbuilder2');

const frag = fragment({ encoding: 'UTF-8' });
frag.ele('node');
console.log(frag.toString({ prettyPrint: true }));

<node/>

const { fragment } = require('xmlbuilder2');

const frag = fragment('<foo>foo</foo><foo>foobar</foo><bar/>');
console.log(frag.toString({ prettyPrint: true }));

<foo>foo</foo>
<foo>foobar</foo>
<bar/>

const { fragment } = require('xmlbuilder2');

const frag = fragment();
frag.ele('node');
console.log(frag.toString({ prettyPrint: true }));

<node/>

convert

The convert function converts an XML document into a given format. See below and serialization settings for the options arguments. The input of the convert function should be a string containing an XML document in either XML or JSON format or a JS object representing XML nodes.

const { convert } = require('xmlbuilder2');

const obj = convert({ encoding: 'UTF-8' }, '<root><node/></root>', { format: 'object' });
console.log(obj);

{ root:
  node: { }
}

const { convert } = require('xmlbuilder2');

const obj = convert('<root><node/></root>', { format: 'object' });
console.log(obj);

{ root:
  node: { }
}

const { convert } = require('xmlbuilder2');

const xml = convert({ encoding: 'UTF-8' }, { root: { node: { } });
console.log(xml);

<?xml version="1.0" encoding="UTF-8"?><root><node/></root>

const { convert } = require('xmlbuilder2');

const xml = convert({ root: { node: { } });
console.log(xml);

<?xml version="1.0"?><root><node/></root>

builder

The builder function wraps an existing DOM node and returns a builder object.

const { builder } = require('xmlbuilder2');

const node = document.createElement('node');

const xml = builder({ version: '1.0' }, node)
  .ele('child')
  .end({ prettyPrint: true });

console.log(xml);

<node>
  <child/>
</node>

const { builder } = require('xmlbuilder2');

const node = document.createElement('node');

const xml = builder(node)
  .ele('child')
  .end({ prettyPrint: true });

console.log(xml);

<node>
  <child/>
</node>

Builder options

Settings related to XML declaration

• version - a version number string. Defaults to '1.0' if omitted.
• encoding - encoding declaration, e.g. 'UTF-8'. No encoding declaration will be produced if omitted.
• standalone - standalone document declaration: true or false. No standalone document declaration will be produced if omitted.

Settings related to value conversions

• keepNullNodes - whether nodes with null and undefined values will be kept or ignored: true or false. Defaults to false, which silently ignores nodes with null and undefined values. When set to true, null will be treated as an empty string.
• keepNullAttributes - whether attributes with null and undefined values will be kept or ignored: true or false. Defaults to false, which silently ignores attributes with null and undefined values. When set to true, null will be treated as an empty string.
• ignoreConverters - whether converter strings will be ignored when converting JS objects: true or false. Defaults to false.
• convert - an object defining converter strings. Default converter strings are described below.
  • att - when prepended to a JS object key, converts its key-value pair to an attribute. Defaults to '@'.
  • ins - when prepended to a JS object key, converts its value to a processing instruction node. Defaults to '?'.
  • text - when prepended to a JS object key, converts its value to a text node. Defaults to '#'.
  • cdata - when prepended to a JS object key, converts its value to a CDATA section node. Defaults to '$'.
  • comment - when prepended to a JS object key, converts its value to a comment node. Defaults to '!'.
• invalidCharReplacement - defines a replacement value for invalid characters in input strings. If value is a string, each invalid character in an input string will be replaced with it; otherwise if value is a function it will be passed each invalid character and should return a replacement character. The arguments to the replacement function are:
  • char - the invalid character to be replaced
  • offset - the offset of the invalid character
  • str - the input string

• parser - defines custom parser functions:
  • parse - main parser function
  • docType - creates a DocType node from parsed content
  • comment - creates a comment node from parsed content
  • text - creates a text node from parsed content
  • instruction - creates a processing instruction node from parsed content
  • cdata - creates a CData node from parsed content
  • element - creates an element node from parsed content
  • attribute - creates an attribute or namespace declaration from parsed content

See custom parsers for more information and examples.

Settings related to XML namespaces

• defaultNamespace - contains default namespaces to apply to all elements and attributes (see: example)
  • ele - default namespace for element nodes
  • att - default namespace for attributes
• namespaceAlias - contains namespace aliases where object keys are namespace aliases and object values are namespaces (see: example)