Builder Options

This page documents the various options that can be used to customize the behavior of the XML builder.

Settings related to the XML declaration

• version A version number string: 1.0 or 1.1. This also changes character validation. 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.
• headless whether XML declaration and doctype will be included: true or false. Defaults to false.

Note: XML declaration can be specified later with the dec function. Also see this wiki page.

builder.create('root')
  .dec('1.0', 'UTF-8', true);

Settings related to the external document type definition

• pubID public identifier of the external subset. No default.
• sysID system identifier of the external subset. No default.

Note: If neither pubID nor sysID is given, an external document type definition will not be produced.

Note: A DTD can also be created at a later time by calling doctype from anywhere in the document (can also be abbreviated to dtd). Also see this wiki page.

var dtd = root.dtd('pubID', 'sysID');

Settings related to value conversions

• keepNullNodes whether nodes with null values will be kept or ignored: true or false. Defaults to false, which silently ignores nodes with null values. When set to true, null will be treated as an empty string.
• keepNullAttributes whether attributes with null values will be kept or ignored: true or false. Defaults to false, which silently ignores attributes with null values. When set to true, null will be treated as an empty string.
• ignoreDecorators whether decorator strings will be ignored when converting JS objects: true or false. Defaults to false. See this page for a list of decorator strings.
• separateArrayItems whether array items are created as separate nodes when passed as an object value: true or false. Defaults to false. See this page for an example.
• noDoubleEncoding whether existing html entities are encoded: true or false. Defaults to false. For example, when converting the following JS object:

const root = {
  '@att': 'attribute value with # and #'
  '#text': 'HTML entities for umlaut are ü and ü.'
}

// with noDoubleEncoding: false (default)
const xmlStr = xml(obj).end({ pretty: true });
// <?xml version="1.0"?>
// <root att="attribute value with &amp;num; and &amp;#35;">
//   HTML entities for umlaut are &amp;uuml; and &amp;#252;.'
// </root>

// with noDoubleEncoding: true
const xmlStr = xml(obj, { noDoubleEncoding: true }).end({ pretty: true });
// <?xml version="1.0"?>
// <root att="attribute value with &num; and &#35;">
//   HTML entities for umlaut are &uuml; and &#252;.'
// </root>

• stringify a set of functions to use for converting values to strings. See this page for value conversion details and decorator strings.
• writer the default XML writer to use for converting nodes to string. If the default writer is not set, the built-in XMLStringWriter will be used instead. See this page for information on writers.