# jstoxml [![npm downloads](https://img.shields.io/npm/dm/jstoxml.svg)](https://www.npmjs.com/package/jstoxml) ### Convert JavaScript objects (and JSON) to XML (for RSS, Podcasts, etc.) Everyone loves JSON, and more and more folks want to move that direction, but we still need things outputted in XML! Particularly for [RSS feeds](http://www.rssboard.org/rss-specification) and [Podcasts](http://www.apple.com/itunes/podcasts/specs.html). This is inspired by [node-jsontoxml](https://github.com/soldair/node-jsontoxml), which was found to be a bit too rough around the edges. jstoxml attempts to fix that by being more flexible. ### Installation - npm install jstoxml ### Changelog #### Version 2.2.0 * Initial support for XML comments ([#47](https://github.com/davidcalhoun/jstoxml/issues/47)) #### Version 2.1.1 * Fix for [#48](https://github.com/davidcalhoun/jstoxml/issues/48) (various 0-depth issues, bad "is output start" logic) #### Version 2.0.0 (breaking) - New: automatic entity escaping for `&`, `<`, and `>` characters. In addition, quotes `"` in attributes are also escaped (see [#41](/../../issues/41)). Prior to this, users [had to provide their own filter manually](https://github.com/davidcalhoun/jstoxml/issues/4#issuecomment-19165730). Note that `jstoxml` makes an effort not to escape entities that appear to have already been encoded, to prevent double-encoding issues. - E.g. `toXML({ foo: '1 < 2 & 2 > 1' }); // -> "1 < 2 & 2 > 1"` - To restore the default behavior from `v1.x.x`, simply pass in `false` to `filter` and `attributesFilter` options: `toXML({ foo: '1 < 2 & 2 > 1' }, { filter: false, attributesFilter: false }); // -> "1 < 2 & 2 > 1"` #### Past changes - See CHANGELOG.md for a full history of changes. ### Examples First you'll want to require jstoxml in your script, and assign the result to the namespace variable you want to use (in this case jstoxml): ```javascript // Node const { toXML } = require("jstoxml"); // Browser (with the help of something like Webpack or Rollup) import { toXML } from "jstoxml"; // Browser global fallback (requires no bundler) var toXML = window.jstoxml.toXML; ``` #### Example 1: Simple object ```javascript toXML({ foo: "bar", foo2: "bar2", }); ``` Output: ``` barbar2 ``` Note: because JavaScript doesn't allow duplicate key names, only the last defined key will be outputted. If you need duplicate keys, please use an array instead (see Example 2 below). #### Example 2: Simple array (needed for duplicate keys) ```javascript toXML([ { foo: "bar", }, { foo: "bar2", }, ]); ``` Output: ``` barbar2 ``` #### Example 3: Simple functions ```javascript toXML({ currentTime: () => new Date() }); ``` Output: ``` Mon Oct 02 2017 09:34:54 GMT-0700 (PDT) ``` #### Example 4: XML tag attributes ```javascript toXML({ _name: "foo", _content: "bar", _attrs: { a: "b", c: "d", }, }); ``` Output: ``` bar ``` #### Example 5: Tags mixed with text content To output text content, set a key to null: ```javascript toXML({ text1: null, foo: "bar", text2: null, }); ``` Output: ``` text1bartext2 ``` #### Example 6: Nested tags (with indenting) ```javascript const xmlOptions = { header: false, indent: " ", }; toXML( { a: { foo: "bar", foo2: "bar2", }, }, xmlOptions ); ``` Output: ``` bar bar2 ``` #### Example 7: Nested tags with attributes (with indenting) ```javascript const xmlOptions = { header: false, indent: " ", }; toXML( { ooo: { _name: "foo", _attrs: { a: "b", }, _content: { _name: "bar", _attrs: { c: "d", }, }, }, }, xmlOptions ); ``` Output: ``` ``` Note that cases like this might be especially hard to read because of the deep nesting, so it's recommend you use something like this pattern instead, which breaks it up into more readable pieces: ```javascript const bar = { _name: "bar", _attrs: { c: "d", }, }; const foo = { _name: "foo", _attrs: { a: "b", }, _content: bar, }; const xmlOptions = { header: false, indent: " ", }; return toXML( { ooo: foo, }, xmlOptions ); ``` #### Example 8: Complex functions Function outputs will be processed (fed back into toXML), meaning that you can output objects that will in turn be converted to XML. ```javascript toXML({ someNestedXML: () => { return { foo: "bar", }; }, }); ``` Output: ``` bar ``` #### Example 9: RSS Feed ```javascript const xmlOptions = { header: true, indent: " ", }; toXML( { _name: "rss", _attrs: { version: "2.0", }, _content: { channel: [ { title: "RSS Example", }, { description: "Description", }, { link: "google.com", }, { lastBuildDate: () => new Date(), }, { pubDate: () => new Date(), }, { language: "en", }, { item: { title: "Item title", link: "Item link", description: "Item Description", pubDate: () => new Date(), }, }, { item: { title: "Item2 title", link: "Item2 link", description: "Item2 Description", pubDate: () => new Date(), }, }, ], }, }, xmlOptions ); ``` Output: ``` RSS Example Description google.com Sat Jul 30 2011 18:14:25 GMT+0900 (JST) Sat Jul 30 2011 18:14:25 GMT+0900 (JST) en Item title Item link Item Description Sat Jul 30 2011 18:33:47 GMT+0900 (JST) Item2 title Item2 link Item2 Description Sat Jul 30 2011 18:33:47 GMT+0900 (JST) ``` #### Example 10: Podcast RSS Feed (see the [Apple docs](http://www.apple.com/itunes/podcasts/specs.html) for more information) ```javascript const xmlOptions = { header: true, indent: " ", }; toXML( { _name: "rss", _attrs: { "xmlns:itunes": "http://www.itunes.com/dtds/podcast-1.0.dtd", version: "2.0", }, _content: { channel: [ { title: "Title", }, { link: "google.com", }, { language: "en-us", }, { copyright: "Copyright 2011", }, { "itunes:subtitle": "Subtitle", }, { "itunes:author": "Author", }, { "itunes:summary": "Summary", }, { description: "Description", }, { "itunes:owner": { "itunes:name": "Name", "itunes:email": "Email", }, }, { _name: "itunes:image", _attrs: { href: "image.jpg", }, }, { _name: "itunes:category", _attrs: { text: "Technology", }, _content: { _name: "itunes:category", _attrs: { text: "Gadgets", }, }, }, { _name: "itunes:category", _attrs: { text: "TV & Film", }, }, { item: [ { title: "Podcast Title", }, { "itunes:author": "Author", }, { "itunes:subtitle": "Subtitle", }, { "itunes:summary": "Summary", }, { "itunes:image": "image.jpg", }, { _name: "enclosure", _attrs: { url: "http://example.com/podcast.m4a", length: "8727310", type: "audio/x-m4a", }, }, { guid: "http://example.com/archive/aae20050615.m4a", }, { pubDate: "Wed, 15 Jun 2011 19:00:00 GMT", }, { "itunes:duration": "7:04", }, { "itunes:keywords": "salt, pepper, shaker, exciting", }, ], }, { item: [ { title: "Podcast2 Title", }, { "itunes:author": "Author2", }, { "itunes:subtitle": "Subtitle2", }, { "itunes:summary": "Summary2", }, { "itunes:image": "image2.jpg", }, { _name: "enclosure", _attrs: { url: "http://example.com/podcast2.m4a", length: "655555", type: "audio/x-m4a", }, }, { guid: "http://example.com/archive/aae2.m4a", }, { pubDate: "Wed, 15 Jul 2011 19:00:00 GMT", }, { "itunes:duration": "11:20", }, { "itunes:keywords": "foo, bar", }, ], }, ], }, }, xmlOptions ); ``` Output: ``` Title google.com en-us Copyright 2011 Subtitle Author Summary Description Name Email Podcast Title Author Subtitle Summary image.jpg http://example.com/archive/aae20050615.m4a Wed, 15 Jun 2011 19:00:00 GMT 7:04 salt, pepper, shaker, exciting Podcast2 Title Author2 Subtitle2 Summary2 image2.jpg http://example.com/archive/aae2.m4a Wed, 15 Jul 2011 19:00:00 GMT 11:20 foo, bar ``` #### Example 11: Custom filter for XML entities, or whatever ```javascript const xmlOptions = { filter: { "<": "<", ">": ">", '"': """, "'": "'", "&": "&", }, }; toXML( { foo: "", bar: '"b"', baz: "'&whee'", }, xmlOptions ); ``` Output: ``` <a>"b"'&whee' ``` #### Example 11b: Custom filter for XML attributes ```javascript const xmlOptions = { attributesFilter: { "<": "<", ">": ">", '"': """, "'": "'", "&": "&", }, }; toXML( { _name: "foo", _attrs: { a: '<"\'&"foo>' }, }, xmlOptions ); ``` Output: ``` ``` #### Example 12: Avoiding self-closing tags If for some reason you want to avoid self-closing tags, you can pass in a special config option `_selfCloseTag`: ```javascript const xmlOptions = { _selfCloseTag: false, }; toXML( { foo: "", bar: undefined, }, xmlOptions ); ``` Output: ``` whee ``` #### Example 13: Custom XML header ```javascript const xmlOptions = { header: '', }; toXML( { foo: "bar", }, xmlOptions ); ``` Output: ``` barbar2 ``` #### Example 14: Emoji attribute support (needed for AMP) ```javascript toXML({ html: { _attrs: { "⚡": true, }, }, }); ``` Output: ``` ``` #### Example 15: Duplicate attribute key support ```javascript toXML({ html: { _attrs: [ { lang: "en", }, { lang: "klingon", }, ], }, }); ``` Output: ``` ``` #### Example 16: XML comments ```javascript toXML({ _comment: 'Some important comment', a: { b: [1, 2, 3] } }, { indent: ' ' }); ``` Output: ``` 1 2 3 ``` #### Example 17: Multiple XML comments ```javascript toXML([ { _comment: 'Some important comment' }, { _comment: 'This is a very long comment!' }, { _comment: 'More important exposition!' }, { a: { b: [1, 2, 3] } } ], { indent: ' ' }); ``` Output: ``` 1 2 3 ``` ### License MIT