JSPM – diffhtml@0.0.6

Package Exports

diffhtml
diffhtml/lib
diffhtml/lib/util/parser

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (diffhtml) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

diffhtml

Allows you to easily swap out markup and have an intelligent virtual diff patch in the changes. Contrast to innerHTML/outerHTML which destroys and creates all elements when set.

Provides a transitions API to hook into state changes. This is useful for animations or reacting to changes.

Install

npm install diffhtml

The module can be required via Node or browser environments. It is exported as a global named diff.

API

The exposed API provides the following methods:

outerHTML(element, markup, options)
innerHTML(element, markup, options)
element(oldElement, newElement, options)
addTransitionState(name, callback)
removeTransitionState(name, callback)
enableProllyfill()

Options

This is an optional argument that can be passed to any diff method. Here you can specify if you'd like to opt into the WebWorker to offload calculates to increase performance. The inner property can only be used with the element method.

inner - Boolean that determines if innerHTML is used.
enableWorker - Boolean that determines if the WebWorker is utilized.

Diff an element with markup

This method will take in a string of markup that matches the element root you are diffing against. This allows you to change attributes and text on the main element. This also allows you to change the document.documentElement.

You cannot override the inner options property here.

diff.outerHTML(document.body, '<body class="test"><h1>Hello world!</h1></body>');

Diff an element's children with markup

This method also takes in a string of markup, but unlike outerHTML this is children-only markup that will be nested inside the element passed.

You cannot override the inner options property here.

diff.innerHTML(document.body, '<h1>Hello world!</h1>');

Diff an element to another element

Unlike the previous two methods, this will take in two elements and diff them together.

The inner options property can be set here to change between inner/outerHTML.

var newBody = document.createElement('body');

newBody.innerHTML = '<h1>Hello world!</h1>';
newBody.setAttribute('class', 'test');

diff.element(document.body, newBody);

With inner set:

var h1 = document.createElement('h1');

h1.innerHTML = 'Hello world!';

diff.element(document.body, h1, { inner: true });

Add a transition state callback

Adds a global transition listener. With many elements this could be an expensive operation, so try to limit the amount of listeners added if you're concerned about performance.

Since the callback triggers with various elements, most of which you probably don't care about, you'll want to filter. A good way of filtering is to use the DOM matches method. It's fairly well supported (http://caniuse.com/#feat=matchesselector) and may suit many projects. If you need backwards compatibility, consider using jQuery's is.

You can do fun, highly specific, filters:

addTransitionState('attached', function(element) {
 // Fade in the main container after it's attached into the DOM.
 if (element.matches('body main.container')) {
   $(element).stop(true, true).fadeIn();
 }
});

Remove a transition state callback

Removes a global transition listener.

When invoked with no arguments, this method will remove all transition callbacks. When invoked with the name argument it will remove all transition state callbacks matching the name, and so on for the callback.

// Removes all.
diff.removeTransitionState();

// Removes by name.
diff.removeTransitionState('attached');

// Removes by name and callback reference.
diff.removeTransitionState('attached', callbackReference);

Prollyfill

I'd love to see this project become a browser standard in the future. To enable how I'd envision it working, simply call enableProllyfill(); on the diff object.

This will augment the Element.prototype and

diff.enableProllyfill();

Now you can use the API defined below.

Diff an element and all children

document.querySelector('main').diffOuterHTML = '<new markup to diff/>';

Diff an element's children

document.querySelector('main').diffInnerHTML = '<new child markup to diff/>';

Diff two elements

var newElement = document.createElement('main');
newElement.innerHTML = '<div></div>';

document.querySelector('main').diff = newElement;

More information and a demo are available on http://www.diffhtml.org/