0
# XML Building
1

2
XML generation functionality for converting JavaScript objects to well-formed XML strings with customizable formatting and structure options.
3

4
## Capabilities
5

6
### Builder Class
7

8
Main class for converting JavaScript objects to XML strings with extensive configuration options for output formatting and structure.
9

10
```javascript { .api }
11
/**
12
 * XML Builder class for converting JavaScript objects to XML
13
 */
14
class Builder {
15
  /**
16
   * Create a new Builder instance
17
   * @param options - Builder configuration options
18
   */
19
  constructor(options?: BuilderOptions);
20
  
21
  /**
22
   * Convert JavaScript object to XML string
23
   * @param rootObj - JavaScript object to convert
24
   * @returns XML string representation
25
   */
26
  buildObject(rootObj: any): string;
27
}
28
```
29

30
**Usage Examples:**
31

32
```javascript
33
const xml2js = require('xml2js');
34

35
// Basic XML building
36
const builder = new xml2js.Builder();
37
const obj = {
38
  person: {
39
    name: 'John Doe',
40
    age: 30,
41
    active: true
42
  }
43
};
44

45
const xml = builder.buildObject(obj);
46
console.log(xml);
47
// Output:
48
// <?xml version="1.0" encoding="UTF-8"?>
49
// <person>
50
//   <name>John Doe</name>
51
//   <age>30</age>
52
//   <active>true</active>
53
// </person>
54

55
// Building with attributes
56
const objWithAttrs = {
57
  product: {
58
    $: { id: '123', category: 'electronics' },
59
    name: 'Laptop',
60
    price: 999.99
61
  }
62
};
63

64
const xmlWithAttrs = builder.buildObject(objWithAttrs);
65
console.log(xmlWithAttrs);
66
// Output:
67
// <?xml version="1.0" encoding="UTF-8"?>
68
// <product id="123" category="electronics">
69
//   <name>Laptop</name>
70
//   <price>999.99</price>
71
// </product>
72
```
73

74
### Builder with Custom Options
75

76
```javascript
77
const xml2js = require('xml2js');
78

79
// Custom builder configuration
80
const customBuilder = new xml2js.Builder({
81
  rootName: 'catalog',
82
  headless: false,
83
  xmldec: {
84
    version: '1.0',
85
    encoding: 'UTF-8',
86
    standalone: true
87
  },
88
  renderOpts: {
89
    pretty: true,
90
    indent: '    ', // 4 spaces
91
    newline: '\n'
92
  },
93
  cdata: true
94
});
95

96
const catalogData = {
97
  item: [
98
    {
99
      $: { id: '1' },
100
      title: 'Product One',
101
      description: 'This contains <special> characters & symbols'
102
    },
103
    {
104
      $: { id: '2' },
105
      title: 'Product Two',
106
      description: 'Another product description'
107
    }
108
  ]
109
};
110

111
const catalogXml = customBuilder.buildObject(catalogData);
112
console.log(catalogXml);
113
```
114

115
## Builder Configuration Options
116

117
### Core Options
118

119
```javascript { .api }
120
interface BuilderOptions {
121
  /** Prefix for accessing XML attributes (default: '$') */
122
  attrkey?: string;
123
  
124
  /** Prefix for accessing character content (default: '_') */
125
  charkey?: string;
126
  
127
  /** Root element name when not specified in object (default: 'root') */
128
  rootName?: string;
129
  
130
  /** Omit XML declaration (default: false) */
131
  headless?: boolean;
132
  
133
  /** Allow Unicode surrogate characters (default: false) */
134
  allowSurrogateChars?: boolean;
135
  
136
  /** Wrap text in CDATA sections when needed (default: false) */
137
  cdata?: boolean;
138
}
139
```
140

141
### XML Declaration Options
142

143
```javascript { .api }
144
interface XMLDeclarationOptions {
145
  /** XML declaration attributes */
146
  xmldec?: {
147
    /** XML version (default: '1.0') */
148
    version?: string;
149
    
150
    /** Character encoding (default: 'UTF-8') */
151
    encoding?: string;
152
    
153
    /** Standalone document declaration (default: true) */
154
    standalone?: boolean;
155
  };
156
}
157
```
158

159
### Rendering Options
160

161
```javascript { .api }
162
interface RenderingOptions {
163
  /** XML formatting options */
164
  renderOpts?: {
165
    /** Pretty-print XML (default: true) */
166
    pretty?: boolean;
167
    
168
    /** Indentation string (default: '  ') */
169
    indent?: string;
170
    
171
    /** Newline character (default: '\n') */
172
    newline?: string;
173
  };
174
  
175
  /** Optional DTD declaration (default: null) */
176
  doctype?: any;
177
}
178
```
179

180
**Usage Examples:**
181

182
```javascript
183
const xml2js = require('xml2js');
184

185
// Compact XML output
186
const compactBuilder = new xml2js.Builder({
187
  renderOpts: {
188
    pretty: false
189
  }
190
});
191

192
// Custom indentation
193
const tabBuilder = new xml2js.Builder({
194
  renderOpts: {
195
    pretty: true,
196
    indent: '\t', // Use tabs instead of spaces
197
    newline: '\r\n' // Windows line endings
198
  }
199
});
200

201
// Headless XML (no declaration)
202
const headlessBuilder = new xml2js.Builder({
203
  headless: true,
204
  rootName: 'data'
205
});
206

207
const simpleObj = { message: 'Hello World' };
208
console.log(headlessBuilder.buildObject(simpleObj));
209
// Output: <data><message>Hello World</message></data>
210

211
// CDATA handling
212
const cdataBuilder = new xml2js.Builder({
213
  cdata: true
214
});
215

216
const objWithSpecialChars = {
217
  content: 'This contains <tags> and & special characters'
218
};
219

220
console.log(cdataBuilder.buildObject(objWithSpecialChars));
221
// Output includes CDATA sections for text with special characters
222
```
223

224
## Building Complex XML Structures
225

226
### Working with Attributes
227

228
```javascript
229
const xml2js = require('xml2js');
230
const builder = new xml2js.Builder();
231

232
// Object with attributes using $ key
233
const productWithAttrs = {
234
  product: {
235
    $: {
236
      id: 'P001',
237
      category: 'electronics',
238
      inStock: true
239
    },
240
    name: 'Smartphone',
241
    price: {
242
      $: { currency: 'USD' },
243
      _: 599.99
244
    },
245
    specifications: {
246
      screen: '6.1 inches',
247
      storage: '128GB',
248
      color: 'Black'
249
    }
250
  }
251
};
252

253
const xml = builder.buildObject(productWithAttrs);
254
console.log(xml);
255
```
256

257
### Working with Arrays
258

259
```javascript
260
const xml2js = require('xml2js');
261
const builder = new xml2js.Builder();
262

263
// Arrays create multiple elements
264
const booksData = {
265
  library: {
266
    book: [
267
      {
268
        $: { isbn: '978-0123456789' },
269
        title: 'JavaScript Guide',
270
        author: 'John Smith',
271
        year: 2023
272
      },
273
      {
274
        $: { isbn: '978-0987654321' },
275
        title: 'Node.js Handbook',
276
        author: 'Jane Doe',
277
        year: 2023
278
      }
279
    ]
280
  }
281
};
282

283
const libraryXml = builder.buildObject(booksData);
284
console.log(libraryXml);
285
```
286

287
### Mixed Content and Text Nodes
288

289
```javascript
290
const xml2js = require('xml2js');
291
const builder = new xml2js.Builder({
292
  charkey: '_'
293
});
294

295
// Mixed content with text and child elements
296
const articleData = {
297
  article: {
298
    $: { id: 'art-001' },
299
    title: 'Understanding XML',
300
    content: {
301
      paragraph: [
302
        {
303
          _: 'This is the first paragraph with ',
304
          emphasis: 'emphasized text',
305
          _2: ' and more content.'
306
        },
307
        'This is a simple second paragraph.'
308
      ]
309
    },
310
    author: 'Technical Writer'
311
  }
312
};
313

314
const articleXml = builder.buildObject(articleData);
315
console.log(articleXml);
316
```
317

318
### Namespace Handling
319

320
```javascript
321
const xml2js = require('xml2js');
322
const builder = new xml2js.Builder({
323
  xmldec: {
324
    version: '1.0',
325
    encoding: 'UTF-8'
326
  }
327
});
328

329
// XML with namespaces
330
const namespacedData = {
331
  'soap:Envelope': {
332
    $: {
333
      'xmlns:soap': 'http://schemas.xmlsoap.org/soap/envelope/',
334
      'xmlns:web': 'http://example.com/webservice'
335
    },
336
    'soap:Header': {},
337
    'soap:Body': {
338
      'web:GetUserRequest': {
339
        'web:UserId': '12345'
340
      }
341
    }
342
  }
343
};
344

345
const soapXml = builder.buildObject(namespacedData);
346
console.log(soapXml);
347
```
348

349
## Error Handling
350

351
The Builder class provides straightforward error handling through exceptions:
352

353
```javascript
354
const xml2js = require('xml2js');
355
const builder = new xml2js.Builder();
356

357
try {
358
  // Attempt to build XML from invalid data
359
  const invalidData = {
360
    // Some problematic data structure
361
  };
362
  
363
  const xml = builder.buildObject(invalidData);
364
  console.log('XML generated successfully:', xml);
365
} catch (error) {
366
  console.error('XML building failed:', error.message);
367
  // Handle the error appropriately
368
}
369
```
370

371
## Common Patterns
372

373
### Converting from Parsed XML Back to XML
374

375
```javascript
376
const xml2js = require('xml2js');
377

378
// Parse and then rebuild XML
379
async function roundTripXML(xmlString) {
380
  try {
381
    // Parse XML with specific options
382
    const parseOptions = {
383
      explicitArray: false,
384
      mergeAttrs: false,
385
      explicitCharkey: false
386
    };
387
    
388
    const parsed = await xml2js.parseStringPromise(xmlString, parseOptions);
389
    
390
    // Build XML with matching options
391
    const builder = new xml2js.Builder({
392
      attrkey: '$',
393
      charkey: '_',
394
      headless: false
395
    });
396
    
397
    const rebuiltXml = builder.buildObject(parsed);
398
    return rebuiltXml;
399
  } catch (error) {
400
    console.error('Round-trip conversion failed:', error);
401
    throw error;
402
  }
403
}
404
```