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 = builder.create(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 = builder.create(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>

• noValidation whether XML character validation will be disabled: true or false. Defaults to false.
• invalidCharReplacement sets a character to replace invalid characters in input strings. Defaults to undefined. Note that setting this option also disables character validation. See XML 1.0, §2.2 Characters and XML 1.1, §2.2 Characters for valid and invalid character definitions.

const obj = {
  'node\x00': 'text\x08content'
}

const xmlStr = builder.create(obj, { invalidCharReplacement: '' }).end({ pretty: true });
// <?xml version="1.0"?>
// <node>textcontent</node>

or using a replacement function:

const obj = {
  'node\x00': 'text\x08content'
}
const options = { 
  invalidCharReplacement: (c) => c === '\x00' ? '' : '_'
};
const xmlStr = builder.create(obj, options).end({ pretty: true });
// <?xml version="1.0"?>
// <node>text_content</node>

• 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.