xmlbuilder2

What is xmlbuilder2?

The xmlbuilder2 npm package is a powerful tool for building XML documents programmatically. It allows users to create XML documents from JavaScript objects, convert between XML and JS/JSON, and manipulate XML documents with a simple and fluent API.

What are xmlbuilder2's main functionalities?

Creating XML documents

This feature allows users to create XML documents by defining a JavaScript object structure that represents the XML hierarchy. Attributes are prefixed with '@', and text content is represented with '#text'.

{"root":{"@att":"value","child":{"#text":"content"}}}

Converting XML to JS/JSON

This feature enables users to convert an XML string into a JavaScript object or JSON format, making it easier to manipulate or extract data from XML documents.

"<root att='value'><child>content</child></root>"

Manipulating XML documents

Users can manipulate existing XML documents by modifying the JavaScript object representation of the XML. This includes changing attribute values, text content, and adding or removing elements.

{"root":{"child":{"@att":"newvalue","#text":"newcontent"}}}

Other packages similar to xmlbuilder2

xml2js

xml2js is a similar package that provides the ability to parse XML into a JavaScript object and vice versa. It is known for its simplicity and ease of use but may not offer the same level of control over the XML creation process as xmlbuilder2.

fast-xml-parser

fast-xml-parser is another alternative that focuses on speed and performance. It offers parsing and validation of XML data and can handle large XML files efficiently. However, it might not have as fluent an API for building XML documents as xmlbuilder2.

xml-js

xml-js provides conversion between XML and JSON formats. It allows users to convert XML documents into a JSON representation and back, similar to xmlbuilder2, but it may not have as many features for manipulating or creating XML documents.

README

xmlbuilder2

An XML builder for node.js.

Installation:

npm install xmlbuilder2

Usage:

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

const root = document()
  .ele('topgun')
    .ele('pilots')
      .ele('pilot', { 'callsign': 'Iceman', 'rank': 'Lieutenant' }).txt('Tom Kazansky').up()
      .ele('pilot', { 'callsign': 'Maverick', 'rank': 'Lieutenant' }).txt('Pete Mitchell').up()
      .ele('pilot', { 'callsign': 'Goose', 'rank': 'Lieutenant (j.g.)' }).txt('Nick Bradshaw').up()
    .up()
    .ele('hangar')
      .ele('aircraft').txt('F-14 Tomcat').up()
      .ele('aircraft').txt('MiG-28').up()
    .up()
  .up();

// convert the XML tree to string
const xml = root.end({ prettyPrint: true });
console.log(xml);

will result in:

<?xml version="1.0"?>
<topgun>
  <pilots>
    <pilot callsign="Iceman" rank="Lieutenant">Tom Kazansky</pilot>
    <pilot callsign="Maverick" rank="Lieutenant">Pete Mitchell</pilot>
    <pilot callsign="Goose" rank="Lieutenant (j.g.)">Nick Bradshaw</pilot>
  </pilots>
  <hangar>
    <aircraft>F-14 Tomcat</aircraft>
    <aircraft>MiG-28</aircraft>
  </hangar>
</topgun>

---

The same XML document can be created by converting a JS object into XML nodes:

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

const obj = {
  topgun: {
    pilots: {
      pilot: [
        { '@callsign': 'Iceman', '@rank': 'Lieutenant', '#': 'Tom Kazansky' },
        { '@callsign': 'Maverick', '@rank': 'Lieutenant', '#': 'Pete Mitchell' },
        { '@callsign': 'Goose', '@rank': 'Lieutenant (j.g.)', '#': 'Nick Bradshaw' }
      ]
    },
    hangar: {
      aircraft: ['F-14 Tomcat', 'MiG-28']
    }
  }
}

const doc = document(obj);
const xml = doc.end({ prettyPrint: true });
console.log(xml);

---

xmlbuilder2 can also parse and serialize XML documents from different formats:

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

const xmlStr = '<root att="val"><foo><bar>foobar</bar></foo></root>';
const doc = document(xmlStr);

// append a "baz" element to the root node of the document
doc.root().ele("baz");

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

which would output:

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

or you could return a JS object by changing the format argument to "object":

const obj = doc.end({ format: "object" });
console.log(obj);

{
  root: {
    '@att': 'val',
    foo: {
      bar: 'foobar'
    },
    baz: {}
  }
}

---

If you need to do some processing:

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

const root = document().ele('squares');
root.com('f(x) = x^2');
for(let i = 1; i <= 5; i++)
{
  const item = root.ele('data');
  item.att('x', i);
  item.att('y', i * i);
}

const xml = root.end({ prettyPrint: true });
console.log(xml);

This will result in:

<?xml version="1.0"?>
<squares>
  <!-- f(x) = x^2 -->
  <data x="1" y="1"/>
  <data x="2" y="4"/>
  <data x="3" y="9"/>
  <data x="4" y="16"/>
  <data x="5" y="25"/>
</squares>

See the wiki for details.