Skip to content

Latest commit

 

History

History
292 lines (241 loc) · 7.02 KB

3.XMLBuilder.md

File metadata and controls

292 lines (241 loc) · 7.02 KB

XML Builder can be used to parse a JS object into XML. It supports following options;

const {XMLBuilder} = require('fast-xml-parser');

const options = {
    ignoreAttributes : false
};

const builder = new XMLBuilder(options);
let xmlDataStr = builder.build(jObj);

arrayNodeName

When you build XML from an array, it's better to set arrayNodeName option to some name.

const cars = [
    {
        "color": "purple",
        "type": "minivan",
        "registration": "2020-02-03",
        "capacity": 7
        },
        {
        "color": "orange",
        "type": "SUV",
        "registration": "2021-05-17",
        "capacity": 4
        },
];
const builder = new XMLBuilder({
    arrayNodeName: "car"
});
const output = builder.build(cars);
<car>
    <color>purple</color>
    <type>minivan</type>
    <registration>2020-02-03</registration>
    <capacity>7</capacity>
</car>
<car>
    <color>orange</color>
    <type>SUV</type>
    <registration>2021-05-17</registration>
    <capacity>4</capacity>
</car>

attributeNamePrefix

To recognize attribute properties in the JS object so that they can be trimmed.

attributesGroupName

To recognize attribute properties group in the JS object so that they can be trimmed and can form attribute expresstion for a tag.

attributeValueProcessor

To customize the bahaviour of parsing an attribute value to the string value. It accepts attribute name and value.

cdataPropName

To recognize CDATA properties in a JS object so that they can be transformed correcty. This option is supported only if preserveOrder: true

commentPropName

To recognize commentsin a JS object so that they can be transformed correcty. This option is supported only if preserveOrder: true because position of comment is important.

format

By default, parsed XML is single line XML string. By format: true, you can format it for better view.

ignoreAttributes

Don't consider attributes while building XML. Other attributes related properties should be set to correctly identifying an attribute property.

indentBy

Applicable only if format:true is set.

preserveOrder

When you parse a XML using XMLParser with preserveOrder: true, the result JS object has different structure. So parse that structure in original XML, you should set the same option while building the XML from that js object.

processEntities

Set it to true (default) to process XML entities. Check Entities section for more detail. If you don't have entities in your XML document then it is recommanded to disable it processEntities: false for better performance.

suppressEmptyNode

Tags with no text value would be parsed as empty tags. Input

const builder = new XMLBuilder({
    arrayNodeName: "any", //not effective
    suppressEmptyNode: true
});
const output = builder.build({
    a: 32,
    b: ""
});

Outout

<a>32</a>
<b/>

tagValueProcessor

To customize the bahaviour of parsing the text value of a tag to the string value. It accepts tag name and value.

textNodeName

To recognize text value for a tag in the JS object so that they can be properly assigned to the tag.

unpairedTags

Unpaired Tags are the tags which don't have matching closing tag. Eg <br> in HTML. You can parse unpaired tags by providing their list to the parser, validator and builder.

Eg

const xmlData = `
    <rootNode>
        <tag>value</tag>
        <empty />
        <unpaired>
        <unpaired />
        <unpaired></unpaired>
    </rootNode>`;  

const options = {
    // suppressEmptyNode: true,
    unpairedTags: ["unpaired"]
};
const parser = new XMLParser(options);
const result = parser.parse(xmlDataStr);

const builder = new XMLBuilder(options);
const output = builder.build(result);

Output

<rootNode>
  <tag>value</tag>
  <empty></empty>
  <unpaired></unpaired>
  <unpaired></unpaired>
  <unpaired></unpaired>
</rootNode>

when you sets suppressEmptyNode: true;

<rootNode>
    <tag>value</tag>
    <empty />
    <unpaired>
</rootNode>

Restoring original XML

Example 1

When you use XML Parser with alwaysCreateTextNode: true, it doesn't impact XMLBuilder result

   const XMLdata = `
      <car>
        <color>purple</color>
        <type>minivan</type>
        <registration>2020-02-03</registration>
        <capacity>7</capacity>
      </car>`;

      const parser = new XMLParser({
          alwaysCreateTextNode: true,
      });
      let result = parser.parse(XMLdata);
      // console.log(JSON.stringify(result, null,4));

      const builder = new XMLBuilder({ format: true });
      const output = builder.build(result);

Output

<car>
  <color>purple</color>
  <type>minivan</type>
  <registration>2020-02-03</registration>
  <capacity>7</capacity>
</car>

Example 2

When you use XML Parser with isArray, it doesn't impact XMLBuilder result under some extent.

   const XMLdata = `
      <car>
        <color>purple</color>
        <type>minivan</type>
        <registration>2020-02-03</registration>
        <capacity>7</capacity>
      </car>`;

      const parser = new XMLParser({
          isArray: (tagName, jPath, isLeafNode, isAttribute) => {
          if(isLeafNode) return true;
        }
      });
      let result = parser.parse(XMLdata);
      // console.log(JSON.stringify(result, null,4));

      const builder = new XMLBuilder();
      const output = builder.build(result);

Output

<car>
  <color>purple</color>
  <type>minivan</type>
  <registration>2020-02-03</registration>
  <capacity>7</capacity>
</car>

Example 3

When you use XML Parser with preserveOrder, you should use the same option with XMLBuilder.

   const XMLdata = `
      <car>
        <color>purple</color>
        <type>minivan</type>
        <registration>2020-02-03</registration>
        <capacity>7</capacity>
      </car>`;

      const parser = new XMLParser({
          preserveOrder: true
      });
      let result = parser.parse(XMLdata);
      // console.log(JSON.stringify(result, null,4));

      const builder = new XMLBuilder({ preserveOrder: true });
      const output = builder.build(result);

Output

<car>
  <color>purple</color>
  <type>minivan</type>
  <registration>2020-02-03</registration>
  <capacity>7</capacity>
</car>

Example 4

You should set attributeNamePrefix and other properties to the same value for XML Parser and XMLBuilder.

const XMLdata = `
<car>
    <color alpha="7">purple</color>
    <type>minivan</type>
    <registration>2020-02-03</registration>
    <capacity>7</capacity>
</car>`;

const options = {
    ignoreAttributes: false,
    attributeNamePrefix: "@@",
    format: true
};
const parser = new XMLParser(options);
let result = parser.parse(XMLdata);
// console.log(JSON.stringify(result, null,4));

const builder = new XMLBuilder(options);
const output = builder.build(result);

Output

<car>
  <color alpha="7">purple</color>
  <type>minivan</type>
  <registration>2020-02-03</registration>
  <capacity>7</capacity>
</car>

> Next: XmlValidator