Node Creation Functions with Callbacks

Once a callback document builder object is created with createCB or fragmentCB functions, further nodes can be created and serialized using the following functions.

att

Creates and serializes an attribute node.

att(namespace: string, name: string, value: string)

Creates and serializes an element attribute with the given namespace URI, name and value.

namespace - namespace URI
name - attribute name
value - attribute value

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

const xmlBuilder = createCB({ 
  data: (chunk) => console.log(chunk)
  end: () => { },
  prettyPrint: true
});

xmlBuilder.ele('root').att('http://example.com/ns1', 'att', 'val').end();

<root xmlns:ns1="http://example.com/ns1" ns1:att="val"/>

att(name: string, value: string)

Creates and serializes an element attribute with the given name and value.

name - attribute name
value - attribute value

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

const xmlBuilder = createCB({ 
  data: (chunk) => console.log(chunk)
  end: () => { },
  prettyPrint: true
});

xmlBuilder.ele('root').att('att', 'val').end();

<root att="val"/>

att(obj: object)

Creates element attributes from each key/value pair of the given object.

obj - a JS object containing element attributes and values

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

const xmlBuilder = createCB({ 
  data: (chunk) => console.log(chunk)
  end: () => { },
  prettyPrint: true
});

xmlBuilder.ele('root').att({ 'att1': 'val1', 'att2': 'val2' }).end();

<root att1="val1" att2="val2"/>

com

Creates and serializes a new comment node.

com(content: string)

content - node content

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

const xmlBuilder = createCB({ 
  data: (chunk) => console.log(chunk)
  end: () => { },
  prettyPrint: true
});

xmlBuilder.ele('root').com('val').end();

<root>
  <!--val-->
</root>

dat

Creates and serializes a new CDATA node.

dat(content: string)

content - node content

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

const xmlBuilder = createCB({ 
  data: (chunk) => console.log(chunk)
  end: () => { },
  prettyPrint: true
});

xmlBuilder.ele('root').dat('val').end();

<root>
  <![CDATA[val]]>
</root>

dec

Creates and serializes the XML declaration.

dec(options: object)

options - declaration options
- 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.

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

const xmlBuilder = createCB({ 
  data: (chunk) => console.log(chunk)
  end: () => { },
  prettyPrint: true
});

xmlBuilder.dec({ 'encoding': 'UTF-8', standalone: true })
  .ele('root').end();

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

dtd

Creates and serializes the DocType node.

dtd(options: object)

Creates a new DocType node and inserts it into the document.

options - DocType options
- name - name of the DTD
- pubID - public identifier of the DTD (optional)
- sysID - system identifier of the DTD (optional)

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

const xmlBuilder = createCB({ 
  data: (chunk) => console.log(chunk)
  end: () => { },
  prettyPrint: true
});

xmlBuilder.dtd({ 
    name: 'HTML',
    pubID: '-//W3C//DTD HTML 4.01//EN',
    sysID: 'http://www.w3.org/TR/html4/strict.dtd'}
  )
  .ele('HTML').end();

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<HTML/>

ele

Creates and serializes a new element node.

ele(namespace: string, name: string, attributes?: object)

Creates a new element node with the given namespace URI, tag name and attributes.

namespace - namespace URI
name - tag name
attributes - a JS object containing key/value pairs of element attributes (optional)

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

const xmlBuilder = createCB({ 
  data: (chunk) => console.log(chunk)
  end: () => { },
  prettyPrint: true
});

xmlBuilder.ele('root')
  .ele('http://example.com/ns1', 'child', { 'att': 'val' }).up()
  .end();

<root>
  <child xmlns="http://example.com/ns1" att="val"/>
</root>

ele(name: string, attributes?: object)

Creates a new element node with the given tag name and attributes.

name - tag name
attributes - a JS object containing key/value pairs of element attributes (optional)

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

const xmlBuilder = createCB({ 
  data: (chunk) => console.log(chunk)
  end: () => { },
  prettyPrint: true
});

xmlBuilder.ele('root')
  .ele('child', { 'att': 'val' }).up()
  .end();

<root>
  <child att="val"/>
</root>

ele(contents: string | object)

Creates a new element node by converting the given JS object into XML nodes. See the object conversion page for details.

contents - a JS object representing nodes to insert or a string containing an XML document in either XML or JSON format

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

const xmlBuilder = createCB({ 
  data: (chunk) => console.log(chunk)
  end: () => { },
  prettyPrint: true
});

xmlBuilder.ele('root')
  .ele({
    foo: {
       bar: 'foobar'
    },
    baz: ''
  }).end();

<root>
  <foo>
    <bar>
      foobar
    </bar>
  </foo>
  <baz/>
</root>

If the contents argument contains an XML or JSON string, ele parses the string and creates new nodes under the current node.

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

const xmlBuilder = createCB({ 
  data: (chunk) => console.log(chunk)
  end: () => { },
  prettyPrint: true
});

xmlBuilder.ele('root')
  .ele('<foo><bar>foobar</bar></foo>')
  .end();

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

ins

Creates and serializes a new processing instruction node.

ins(target: string, content: string)

Creates a new processing instruction node with the given target and content.

target - instruction target
content - node content (optional)

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

const xmlBuilder = createCB({ 
  data: (chunk) => console.log(chunk)
  end: () => { },
  prettyPrint: true
});

xmlBuilder.ele('root').ins('bar', 'version="13.0"').end();

<root>
  <?bar version="13.0"?>
</root>

ins(obj: object)

Creates new processing instructions from the key/value pairs of the given object.

obj - a JS object containing key/value pairs of processing instruction targets and values

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

const xmlBuilder = createCB({ 
  data: (chunk) => console.log(chunk)
  end: () => { },
  prettyPrint: true
});

xmlBuilder.ele('root').ins({ bar: 'version="13.0"', baz: 'public=true' }).end();

<root>
  <?bar version="13.0"?>
  <?baz public=true?>
</root>

ins(arr: string[])

Creates new processing instructions from the given string array.

arr - a string array containing space concatenated processing instruction targets and values

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

const xmlBuilder = createCB({ 
  data: (chunk) => console.log(chunk)
  end: () => { },
  prettyPrint: true
});

xmlBuilder.ele('root').ins(['bar version="13.0"', 'bar public=true']).end();

<root>
  <?bar version="13.0"?>
  <?bar public=true?>
</root>

txt

Creates and serializes a new text node.

txt(content: string)

content - node content

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

const xmlBuilder = createCB({ 
  data: (chunk) => console.log(chunk)
  end: () => { },
  prettyPrint: true
});

xmlBuilder.ele('root').txt('val').end();

<root>
  val
</root>

import

Imports and serializes a node. Descendant nodes and attributes will also be imported.

Note: The node will be cloned before being imported and this clone will be inserted into the document; not the original node.

Note: If the imported node is a document, its document element node will be imported. If the imported node is a document fragment, its child nodes will be imported.

import(node: XMLBuilderNode)

node - the node to import

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

const xmlBuilder = createCB({ 
  data: (chunk) => console.log(chunk)
  end: () => { },
  prettyPrint: true
});
const item1 = create().ele('item').txt('001').up();
const item2 = create().ele('item').txt('002').up();

xmlBuilder.ele('root').import(item1).import(item2).end();

<root>
  <item>
    001
  </item>
  <item>
    002
  </item>
</root>

on

Adds a listener function for an event.

on(event: string, listener: function)

event - event name, either "data", "end" or "error"
listener - a listener function. For the "data" event, the listener function receives the serialized XML chunk as its first argument and the depth of the XML tree as its second argument. For the "end" event, the listener callback receives no arguments. For the "error" event, the listener callback receives the error object as its single argument.

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

const xmlBuilder = createCB({ prettyPrint: true });
xmlBuilder.on('data', (chunk) => console.log(chunk));

xmlBuilder.ele('root').txt('val').end();

<root>
  val
</root>

Node Creation Functions with Callbacks View on GitHub

att

com

dat

dec

dtd

ele

ins

txt

import

on