Merge pull request #37 from ansuz/gh-pages

diff hooks

Author: johanneswilm

README.md

@@ -97,6 +97,41 @@ dd = new diffDOM({
   });
 ```
 
+#### Pre and post diff hooks
+
+diffDOM provides extension points before and after virtual and actual diffs, exposing some of the internals of the diff algorithm, and allowing you to make additional decisions based on that information.
+
+```
+dd = new diffDOM({
+    preVirtualDiffApply: function (info) {
+        console.log(info);
+    },
+    postVirtualDiffApply: function (info) {
+        console.log(info);
+    },
+    preDiffApply: function (info) {
+        console.log(info);
+    },
+    postDiffApply: function (info) {
+        console.log(info);
+    }
+  });
+```
+
+Additionally, the _pre_ hooks allow you to shortcircuit the standard behaviour of the diff by returning 'true' from this callback. This will cause the diffApply functions to return prematurely, skipping their standard behaviour.
+
+```
+dd = new diffDOM({
+    // prevent removal of attributes
+    preDiffApply: function (info) {
+        if (info.diff.action === 'removeAttribute') {
+            console.log("preventing attribute removal");
+            return true;
+        }
+    }
+  });
+```
+
 #### Debugging
 
 For debugging you might want to set a max number of diff changes between two elements before diffDOM gives up. To allow for a maximum of 500 differences between elements when diffing, initialize diffDOM like this:

diffDOM.js

@@ -438,16 +438,22 @@
                 textDiff: function() {
                     arguments[0].data = arguments[3];
                     return;
-                }
+                },
+                // empty functions were benchmarked as running faster than both
+                // `f && f()` and `if (f) { f(); }`
+                preVirtualDiffApply: function () {},
+                postVirtualDiffApply: function () {},
+                preDiffApply: function () {},
+                postDiffApply: function () {}
             },
             i;
 
-        if (typeof options == "undefined") {
+        if (typeof options === "undefined") {
             options = {};
         }
 
         for (i in defaults) {
-            if (typeof options[i] == "undefined") {
+            if (typeof options[i] === "undefined") {
                 this[i] = defaults[i];
             } else {
                 this[i] = options[i];
@@ -971,6 +977,14 @@
                 nodeIndex = routeInfo.nodeIndex,
                 newNode, route, c;
 
+            // pre-diff hook
+            var info = {
+                diff: diff,
+                node: node
+            };
+
+            if (this.preVirtualDiffApply(info)) { return true; }
+
             switch (diff.action) {
                 case 'addAttribute':
                     if (!node.attributes) {
@@ -1095,6 +1109,10 @@
                     console.log('unknown action');
             }
 
+            // capture newNode for the callback
+            info.newNode = newNode;
+            this.postVirtualDiffApply(info);
+
             return;
         },
 
@@ -1132,6 +1150,14 @@
             var node = this.getFromRoute(tree, diff.route),
                 newNode, reference, route, c;
 
+            // pre-diff hook
+            var info = {
+                diff: diff,
+                node: node
+            };
+
+            if (this.preDiffApply(info)) { return true; }
+
             switch (diff.action) {
                 case 'addAttribute':
                     if (!node || !node.setAttribute) {
@@ -1223,6 +1249,11 @@
                     console.log('unknown action');
             }
 
+            // if a new node was created, we might be interested in it
+            // post diff hook
+            info.newNode = newNode;
+            this.postDiffApply(info);
+
             return true;
         },