Conversion From Object

Child nodes can also be created by passing an object to the element or create functions. Here is an example:

var obj = {
  person: {
    name: "John",
    '@age': 35,
    address: {
      city: "Istanbul"
    },
    phone: [
      { '#text': "555-1234", '@type': 'home' }, 
      { '#text': "555-1235", '@type': 'mobile' }
    ],
    id: function() {
      return 42;
    }
  }
};

var builder = require('xmlbuilder');
var root = builder.create(obj);

The resulting XML will be:

<?xml version="1.0"?>
<person age="35">
  <name>John</name>
  <address>
    <city>Istanbul</city>
  </address>
  <phone type="home">555-1234</phone>
  <phone type="mobile">555-1235</phone>
  <id>42</id>
</person>

Objects

Objects will be expanded recursively and each name-value pair is converted to an XML node.

root.ele({
  person: { 
    name: "John"
  }
});

<person>
  <name>John</name>
</person>

Arrays

Arrays will also be expanded and each array item is converted to an XML node.

root.ele({
  number: [ 
    "one", 
    "two",
    { three: { "@val": 3 } }
  ]
});

<number>one</number>
<number>two</number>
<number>
  <three val="3"/>
</number>

Arrays are expanded in a different way if the builder was created with the separateArrayItems flag:

<number>
  <one/>
  <two/>
  <three val="3"/>
</number>

Functions

If a function is passed as an object value, it will be evaluated and its return value will be the node value.

root.ele({
  row: { 
    id: function() { return 42; }
  }
});

<row>
  <id>42</id>
</row>

Functions can return objects and arrays which will be passed recursively to the element function to create child nodes.

Decorators

XML attributes and special nodes are recognized with decorator strings. For example, if an object name starts with @, it will be converted to an XML attribute. Decorators can be customized while calling the create function. Default decorators are shown below.

var root = xmlbuilder.create(obj, {
  stringify: {
    convertAttKey: '@',
    convertPIKey: '?',
    convertTextKey: '#text',
    convertCDataKey: '#cdata',
    convertCommentKey: '#comment',
    convertRawKey: '#raw'
  }
});

Decorator strings will be ignored if the builder was created with the ignoreDecorators flag.

Attribute Decorator

Attribute decorator (default @) marks its name-value pair as an attribute. Those attributes are collected and applied to the parent node.

root.ele({ 
  person: {
    name: "John",
    "@age": 35
  }
});

<person age="35">
  <name>John</name>
</person>

Processing Instruction Decorator

Processing instruction decorator (default ?) marks its name-value pair as an XML processing instruction.

root.ele({ 
  person: {
    name: "John",
    "?target": "content"
  }
});

<person>
  <name>John</name>
  <?target content?>
</person>

Text Decorator

Text decorator (default #text) marks its value as a text node.

root.ele({ 
  person: {
    name: "John",
    "#text": "Smith"
  }
});

<person>
  <name>John</name>
  Smith
</person>

CData Decorator

CData decorator (default #cdata) marks its value as a CData node.

root.ele({ 
  person: {
    name: "John",
    "#cdata": "Smith"
  }
});

<person>
  <name>John</name>
  <![CDATA[Smith]]>
</person>

Comment Decorator

Comment decorator (default #comment) marks its value as a comment node.

root.ele({ 
  person: {
    name: "John",
    "#comment": "Smith"
  }
});

<person>
  <name>John</name>
  <!-- Smith -->
</person>

Raw Decorator

Raw decorator (default #raw) marks its value as a text node, but its contents will not be escaped.

root.ele({ 
  person: {
    name: "John",
    "#raw": "&<>&"
  }
});

<person>
  <name>John</name>
  &<>&
</person>