domJSON v0.1.2

Convert DOM trees into compact JSON objects, and vice versa, as fast as possible.

What is domJSON for?

The purpose of domJSON is to produce very accurate representations of the DOM as JSON objects, and to do it very quickly. Broadly speaking, the goals of this project are:

• Provide as accurate a copy of a given node's DOM properties as possible, but allow optional filtering to remove useless information
• Be able to rebuild JSON nodes into DOM nodes as performantly as possible
• Speed, speed, speed
• No frivolous data: produce JSON objects that are as compact as possible, removing all information not relevant to the developer
• Keep the library lightweight, with no dependencies

DomJSON works in the following browsers (mobile and desktop versions supported):

• Chrome 36+
• Firefox 24+
• Safari 7+
• Internet Explorer 9+

While there are probably dozens of varied use cases for this project, two stick out in my mind. The first is as a front-end debugging or snapshotting tool, which would allow end users to send reports that include "snapshots" of the DOM at any given point in time. Imagine an "I Found a Bug!" button on your web app, which, when clicked, would send an easily rebuildable copy of the DOM in its current state (computed styles included!) to the dev team. DomJSON can do that - to take a peek, check out the first example. Another potential use case is as a poor man's virtual DOM, allowing domJSON to do batch updates on your DOM tree much quicker than normal. Check out the second example for a demonstration. I'm sure there are plenty of other use cases for domJSON that I'm not even considering, but these are the two that make the most sense at first glance.

Getting Started

Installing domJSON is easy. You can pull it from Bower...

								bower install domjson
							

								<script src="bower_components/domjson/dist/domjson.min.js"></script>
							

...or grab it from NPM and manually include it as a script tag.

								npm install domjson --save
							

								<script src="node_modules/domjson/dist/domjson.min.js"></script>
							

Of course, you can also do it the old fashioned way and just download it directly from Github, then include the script tag. Once you've got domJSON installed, working with it is super easy: use the .toJSON() method to create a JSON representation of the DOM tree:

								var someDOMElement = document.getElementById('sampleId');
								var jsonOutput = domJSON.toJSON(someDOMElement);
							

And then rebuild the DOM Node from that JSON using .toDOM():

								var DOMDocumentFragment = domJSON.toDOM(jsonOutput);
								someDOMElement.parentNode.replaceChild(someDOMElement, DOMDocumentFragment);
							

When creating the JSON object, there are many precise options available, ensuring that developers can produce very specific and compact outputs. For example, the following will produce a JSON copy of someDOMElement's DOM tree that is only two levels deep, contains no "offset," "client," or "scroll*" type DOM properties, only keeps the "id" attribute on each DOM Node, and outputs a string (rather than a JSON-friendly object):

								var jsonOutput = domJSON.toJSON(someDOMElement, {
								    attributes: ['id'],
								    domProperties: {
								        exclude: true,
								        values: ['clientHeight', 'clientLeft', 'clientTop', 'offsetWidth', 'offsetHeight', 'offsetLeft', 'offsetTop', 'offsetWidth', 'scrollHeight', 'scrollLeft', 'scrollTop', 'scrollWidth']
								    },
								    deep: 2,
								    stringify: true
								});
							

API Options

Below is a list of all the .toJSON() options, and an explanation of what each one does:

• absolutePaths
• attributes
• computedStyle
• cull
• deep
• domProperties
• htmlOnly
• metadata
• serialProperties
• stringify

									domJSON.toJSON(someNode, {stringify: true});
									JSON.stringify( domJSON.toJSON(someNode, {stringify: false}) );
								

Sample: Turning the DOM into JSON

This is a simple example of how domJSON can take a DOM Tree and turn it into a usable and representative JSON object. When you click the "Go!" button, the output box will show a JSON representation of the div containing this sample. Mess around with the option toggles, then check out the output in the blue area.

Sample: Speeding Up Batch DOM Updates with Web Workers

In theory, rather than updating the DOM piecemeal, developers can grab a branch of the DOM tree and convert it to JSON. They could make all of the changes they want in a JavaScript Web Worker, then re-build a Document Fragment from this modified JSON. Finally, this new fragment could easily inserted into the DOM, replacing the old branch. This should be much more performant than repeatedly updating the DOM.

The reasons for this are twofold. First, the browser can hang during large JavaScript operations, due to JavaScript's single-threaded nature. By using a Web Worker, we can cut down on that "browser freezing" significantly, offering a vastly improved user experience. Secondly, repeated jQuery updates means we have to do many DOM redraws, which can take forever. Instead, we can just convert the DOM to JSON, do all of our updating in JavaScript, and then replace the existing DOM Tree with a new Document Fragment. That's only one redraw - way faster!

For this example, we have a 2500 row table of numbered entries that can be incremented by a specified amount. So what will be quicker: iterating over the table cells using jQuery:

								var increment = parseInt($('[name="increment"]').first().val().trim());
									var frameDoc = $( $('#webworkersFrame').get(0).contentDocument.activeElement );
									var timer = new Date().getTime();

									//Update each row
									$('div', frameDoc).each(function(i,v){
										    $(this).html( parseInt(v.innerText, 10) + increment );
									});
									$('#webworkersResults').prepend('<div class="webworkers-red">Using jQuery ieration, the incrementation took: '+ ((new Date().getTime() - timer)/1000) +' seconds!</div>');
							

or using domJSON with a Web Worker?

								var worker = new Worker('./worker.js');

								var increment = parseInt($('[name="increment"]').first().val().trim());
									var frameDoc = $( $('#webworkersFrame').get(0).contentDocument.activeElement );;
									var timer = new Date().getTime();

									//Update each row using a web worker and domJSON
									worker.postMessage( [domJSON.toJSON($('section', frameDoc).get(0), {
									    attributes: false,
									    domProperties: false,
									}), increment] );
									worker.onmessage = function(e){
										    var x = domJSON.toDOM(e.data);
										    frameDoc.html(x);
										    $('#webworkersResults').prepend('<div class="webworkers-green">Using domJSON and Web Workers, the incrementation took: '+ ((new Date().getTime() - timer)/1000) +' seconds!</div>');
									};
								

									//In a separate file located at './worker.js'
									onmessage = function(e){
										    var increment = e.data[1];
										    var rows = e.data[0].node.childNodes;
										    var length = rows.length;
										    for (var i = 0; i < length; i++){
											        rows[i].childNodes[0].nodeValue = parseInt(rows[i].childNodes[0].nodeValue, 10) + increment;
										    }
										    postMessage(e.data[0]);
									};
									

Note: this demo can take up to 20 seconds per run - please be patient! Also, on Gecko based browsers, the jQuery method will actually be a bit faster...

Contributing

If you'd like to contribute, check out the Github repo, but please make sure to check the contribution guidelines before you make pull requests.

Are you curious about compatibility with a browser not list above? You can run the test suite using the instructions here to see if it passes - if it does, you're (probably) in the clear. Please note that Internet Explorer 8 and lower is explicitly not supported.

The domJSON library is published under the standard MIT License.