Home

Initialization

An XML document is created by calling the create method of the module.

var root = require('xmlbuilder').create('root',
                     {version: '1.0', encoding: 'UTF-8', standalone: true},
                     {pubid: null, sysid: null},
                     {allowSurrogateChars: false, skipNullAttributes: false, 
                      headless: false, ignoreDecorators: false, stringify: {}});

The create method requires the name of the root element. There are also a number of optional arguments for creating the prolog and document type declaration. XML version number will default to 1.0 if omitted. Prolog and document type declaration can be suppressed with the headless option. It is also possible to define the internal subset of the DTD. See this wiki page for details.

The allowSurrogateChars option allows for using characters from the Unicode surrogate blocks. stringify provides a set of functions which tell XMLBuilder how to convert values into strings. For example, the following will prepend myns: to all element names:

var root = xmlbuilder.create('root', {
  stringify: {
    eleName: function(val) {
      return 'myns:' + val;
    }
  }
});

The create method will return the new root element.

Creating Child Nodes

Child nodes are created with the element method (can also be abbreviated to ele or e).

var ele = root.ele('child',
                   'element text',
                   {'attribute': 'value',
                    'attribute2': 'value2'});

Element attributes and text are optional and can be specified later with the att and txt methods.

There are also the insertBefore and insertAfter methods for creating child nodes. They accept the same arguments as the element method.

var ele = root.ele('third')
              .insertBefore('first') // Insert the first node before third
              .insertAfter('second')); // Insert the second node after first

element, insertBefore and insertAfter will return the newly created child node.

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

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

var ele = root.ele(obj);

See this wiki page for conversion details. When called with an object, element, insertBefore and insertAfter will return the last top level child node.

Child nodes can also be created with the node method (can also be abbreviated to nod or n). The difference between node and element is that node does not expand objects (i.e. its first argument must be a string).

Deleting Nodes

Child nodes are deleted with the remove method.

var ele = root.ele('delete me')
              .remove()
              .ele('child'));

remove will return its parent node.

Attributes

Node attributes are created with the attribute method (can also be abbreviated to att or a). attribute will create a new attribute or overwrite the attribute value if it already exists.

ele.att('attribute', 'value');

Attributes can be deleted with the removeAttribute method.

ele.removeAttribue('attribute');

att and removeAttribute will return the parent node.

Text Nodes

Text nodes are created with the text method (can also be abbreviated to txt or t).

ele.txt('element text');

txt will return its parent node.

Raw Text Nodes

Raw text nodes are created with the raw method (can also be abbreviated to r).

ele.raw('this will not be escaped');

raw will return its parent node.

CDATA Nodes

CDATA nodes are created with the cdata method (can also be abbreviated to dat or d). The value should not include CDATA delimiters

ele.dat('this will be surrounded by CDATA delimiters');

dat will return its parent node.

Comment Nodes

XML comments are created with the comment method (can also be abbreviated to com or c).

ele.com('some comment here');

com will return its parent node.

Processing instructions

XML processing instructions are created with the instruction method (can also be abbreviated to ins or i).

ele.ins('xml-stylesheet', 'type="text/xsl" href="style.xsl"');

ins will return its parent node.

Traversing the Document Tree

Each call to ele will return the newly created child node. The up method provides a means to return back to the parent node after creating the child node (can also be abbreviated to u).

root.ele('child')
  .up() // we are back at the root element
  .txt('root element text');

There are also the prev and next methods which return the node before and after the current node. The root method can be used to get to the document's root node from anywhere in the document.

root.ele('first')
    .up()
    .ele('second')
    .prev() // returns first
    .next() // returns second
    .root(); // returns root

The doc method will return the XML document itself. doc can be called from anywhere in the document.

root.doc().end(); // Convert the entire document to string

Converting to String

Once the XML document is created, it can be converted to a string by calling the end method from anywhere in the document.

var xmlString = root.end({ pretty: true, indent: '  ', newline: '\n' });