feat: Add ElementCache lifecycle events

The DOMRenderer exposes an API for registering callback functions to be
executed on element insertion and removal.

Author: alexanderGugel

dom-renderers/DOMRenderer.js

@@ -28,6 +28,7 @@ var ElementCache = require('./ElementCache');
 var math = require('./Math');
 var PathUtils = require('../core/Path');
 var vendorPrefix = require('../utilities/vendorPrefix');
+var CallbackStore = require('../utilities/CallbackStore');
 var eventMap = require('./events/EventMap');
 
 var TRANSFORM = null;
@@ -68,6 +69,9 @@ function DOMRenderer (element, selector, compositor) {
     this._children = []; // a register for holding the children of the
                          // current target.
 
+     this._insertElCallbackStore = new CallbackStore();
+     this._removeElCallbackStore = new CallbackStore();
+
     this._root = new ElementCache(element, selector); // the root
                                                       // of the dom tree that this
                                                       // renderer is responsible
@@ -457,7 +461,10 @@ DOMRenderer.prototype.insertEl = function insertEl (tagName) {
                 'Void elements are not allowed to have children.'
             );
 
-        if (this._target) this._parent.element.removeChild(this._target.element);
+        if (this._target) {
+            this._parent.element.removeChild(this._target.element);
+            this._removeElCallbackStore.trigger(this._path, this._target);
+        }
 
         this._target = new ElementCache(document.createElement(tagName), this._path);
 
@@ -468,6 +475,8 @@ DOMRenderer.prototype.insertEl = function insertEl (tagName) {
 
         this._parent.element.appendChild(this._target.element);
         this._elements[this._path] = this._target;
+
+        this._insertElCallbackStore.trigger(this._path, this._target);
     }
 };
 
@@ -705,4 +714,69 @@ DOMRenderer.prototype._stringifyMatrix = function _stringifyMatrix(m) {
     return r;
 };
 
+/**
+ * Registers a function to be executed when a new element is being inserted at
+ * the specified path.
+ *
+ * @method
+ *
+ * @param  {String}   path      Path at which to listen for element insertion.
+ * @param  {Function} callback  Function to be executed when an insertion
+ *                              occurs.
+ * @return {DOMRenderer}        this
+ */
+DOMRenderer.prototype.onInsertEl = function onInsertEl(path, callback) {
+    this._insertElCallbackStore.on(path, callback);
+    return this;
+};
+
+/**
+ * Deregisters a listener function to be no longer executed on future element
+ * insertions at the specified path.
+ *
+ * @method
+ *
+ * @param  {String}   path      Path at which the listener function has been
+ *                              registered.
+ * @param  {Function} callback  Callback function to be deregistered.
+ * @return {DOMRenderer}        this
+ */
+DOMRenderer.prototype.offInsertEl = function offInsertEl(path, callback) {
+    this._insertElCallbackStore.off(path, callback);
+    return this;
+};
+
+/**
+ * Registers an event handler to be triggered as soon as an element at the
+ * specified path is being removed.
+ *
+ * @method
+ *
+ * @param  {String}   path      Path at which to listen for the removal of an
+ *                              element.
+ * @param  {Function} callback  Function to be executed when an element is
+ *                              being removed at the specified path.
+ * @return {DOMRenderer}        this
+ */
+DOMRenderer.prototype.onRemoveEl = function onRemoveEl(path, callback) {
+    this._removeElCallbackStore.on(path, callback);
+    return this;
+};
+
+/**
+ * Deregisters a listener function to be no longer executed when an element is
+ * being removed from the specified path.
+ *
+ * @method
+ *
+ * @param  {String}   path      Path at which the listener function has been
+ *                              registered.
+ * @param  {Function} callback  Callback function to be deregistered.
+ * @return {DOMRenderer}        this
+ */
+DOMRenderer.prototype.offRemoveEl = function offRemoveEl(path, callback) {
+    this._removeElCallbackStore.off(path, callback);
+    return this;
+};
+
 module.exports = DOMRenderer;

dom-renderers/test/DOMRenderer.js

@@ -316,4 +316,69 @@ test('DOMRenderer', function(t) {
         t.end();
     });
 
+    t.test('onInsertEl method', function(t) {
+        var element = document.createElement('div');
+        var selector = 'selector';
+        var compositor = createUnidirectionalCompositor();
+        var domRenderer = new DOMRenderer(element, selector, compositor);
+
+        t.equal(typeof domRenderer.onInsertEl, 'function', 'domRenderer.onInsertEl should be a function');
+
+        var triggeredInsertEl = false;
+        var triggeredElementCache = null;
+
+        domRenderer.onInsertEl(selector + '/1/2/3', function(elementCache) {
+            triggeredInsertEl = true;
+            triggeredElementCache = elementCache;
+        });
+
+        domRenderer.loadPath(selector + '/1/2');
+        domRenderer.findTarget();
+        domRenderer.insertEl('div');
+        t.equal(triggeredInsertEl, false, 'domRenderer.onInsertEl should not be triggered on parent of registered path');
+
+
+        domRenderer.loadPath(selector + '/1/2/3');
+        domRenderer.findTarget();
+        domRenderer.insertEl('div');
+        t.equal(triggeredInsertEl, true, 'domRenderer.onInsertEl should be triggered on element insertion at registered path');
+        t.notEqual(triggeredElementCache, null, 'domRenderer.onInsertEl listener should receive newly created ElementCache');
+
+        t.equal(triggeredElementCache.path, selector + '/1/2/3', 'domRenderer.onInsertEl should trigger ElementCache with the correct path');
+        t.equal(triggeredElementCache.element, element.children[0].children[0], 'domRenderer.onInsertEl should trigger ElementCache that manages the correct element');
+
+        t.end();
+    });
+
+    t.test('onRemoveEl method', function(t) {
+        var element = document.createElement('div');
+        var selector = 'selector';
+        var compositor = createUnidirectionalCompositor();
+        var domRenderer = new DOMRenderer(element, selector, compositor);
+
+        t.equal(typeof domRenderer.onRemoveEl, 'function', 'domRenderer.onRemoveEl should be a function');
+
+        var triggeredInsertEl = false;
+        var triggeredElementCache = null;
+
+        domRenderer.onRemoveEl(selector + '/1', function(elementCache) {
+            triggeredInsertEl = true;
+            triggeredElementCache = elementCache;
+        });
+
+        domRenderer.loadPath(selector + '/1');
+        domRenderer.findTarget();
+        domRenderer.insertEl('div');
+
+        t.equal(triggeredInsertEl, false, 'DOMRenderer.onRemoveEl should not be triggered on initial insertion');
+
+        domRenderer.findTarget();
+        domRenderer.insertEl('section');
+
+        t.equal(triggeredInsertEl, true, 'DOMRenderer.onRemoveEl should be triggered when overriding an element at the same path');
+
+        t.equal(triggeredElementCache.element.tagName.toLowerCase(), 'div', 'DOMRenderer.onRemoveEl listener should receive ElementCache with correct tagName');
+
+        t.end();
+    });
 });