Add change event

Author: peyerluk

spec/keyboard.spec.js

@@ -19,6 +19,47 @@ describe('Keyboard', function() {
       expect(called).toEqual(1);
     });
 
-  });
+    describe('notify "character" event', function() {
+
+      it('does not fire the event for a "left" key', function() {
+        keyboard.on('character', function(event) {
+          called += 1
+        });
+
+        event.keyCode = Keyboard.key['left'];
+        keyboard.dispatchKeyEvent(event, {}, true);
+        expect(called).toEqual(0);
+      });
+
+      it('does not fire the event for a "ctrl" key', function() {
+        keyboard.on('character', function(event) {
+          called += 1
+        });
+
+        event.keyCode = Keyboard.key['ctrl'];
+        keyboard.dispatchKeyEvent(event, {}, true);
+        expect(called).toEqual(0);
+      });
 
+      it('does fire the event for a "e" key', function() {
+        keyboard.on('character', function(event) {
+          called += 1
+        });
+
+        event.keyCode = 'e'.charCodeAt(0);
+        keyboard.dispatchKeyEvent(event, {}, true);
+        expect(called).toEqual(1);
+      });
+
+      it('does not fire the event for a "e" key without the notifyCharacterEvent param', function() {
+        keyboard.on('character', function(event) {
+          called += 1
+        });
+
+        event.keyCode = 'e'.charCodeAt(0);
+        keyboard.dispatchKeyEvent(event, {}, false);
+        expect(called).toEqual(0);
+      });
+    });
+  });
 });

src/core.js

@@ -372,6 +372,19 @@ Editable.prototype.empty = function(handler) {
   return this.on('empty', handler);
 };
 
+/**
+ * Subscribe to the {{#crossLink "Editable/change:event"}}{{/crossLink}}
+ * event.
+ *
+ * @method change
+ * @param {Function} handler The callback to execute in response to the
+ *   event.
+ * @chainable
+ */
+Editable.prototype.change = function(handler) {
+  return this.on('change', handler);
+};
+
 /**
  * Subscribe to the {{#crossLink "Editable/switch:event"}}{{/crossLink}}
  * event.

src/dispatcher.js

@@ -8,6 +8,7 @@
 var Dispatcher = function(editable) {
   var win = editable.win;
   eventable(this, editable);
+  this.supportsInputEvent = false;
   this.$document = $(win.document);
   this.config = editable.config;
   this.editable = editable;
@@ -17,6 +18,10 @@ var Dispatcher = function(editable) {
   this.setup();
 };
 
+// This will be set to true once we detect the input event is working.
+// Input event description on MDN:
+// https://developer.mozilla.org/en-US/docs/Web/Reference/Events/input
+var isInputEventSupported = false;
 
 /**
  * Sets up all events that Editable.JS is catching.
@@ -61,12 +66,44 @@ Dispatcher.prototype.setupElementEvents = function() {
   }).on('cut.editable', _this.editableSelector, function(event) {
     log('Cut');
     _this.notify('clipboard', this, 'cut', _this.selectionWatcher.getFreshSelection());
+    _this.triggerChangeEvent(this);
   }).on('paste.editable', _this.editableSelector, function(event) {
     log('Paste');
     _this.notify('clipboard', this, 'paste', _this.selectionWatcher.getFreshSelection());
+    _this.triggerChangeEvent(this);
+  }).on('input.editable', _this.editableSelector, function(event) {
+    log('Input');
+    if (isInputEventSupported) {
+      _this.notify('change', this);
+    } else {
+      // Most likely the event was already handled manually by
+      // triggerChangeEvent so the first time we just switch the
+      // isInputEventSupported flag without notifiying the change event.
+      isInputEventSupported = true;
+    }
   });
 };
 
+/**
+ * Trigger a change event
+ *
+ * This should be done in these cases:
+ * - typing a letter
+ * - delete (backspace and delete keys)
+ * - cut
+ * - paste
+ * - copy and paste (not easily possible manually as far as I know)
+ *
+ * Preferrably this is done using the input event. But the input event is not
+ * supported on all browsers for contenteditable elements.
+ * To make things worse it is not detectable either. So instead of detecting
+ * we set 'isInputEventSupported' when the input event fires the first time.
+ */
+Dispatcher.prototype.triggerChangeEvent = function(target){
+  if (isInputEventSupported) return;
+  this.notify('change', target);
+};
+
 Dispatcher.prototype.dispatchSwitchEvent = function(event, element, direction) {
   var cursor;
   if (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey)
@@ -99,7 +136,8 @@ Dispatcher.prototype.setupKeyboardEvents = function() {
   var _this = this;
 
   this.$document.on('keydown.editable', this.editableSelector, function(event) {
-    _this.keyboard.dispatchKeyEvent(event, this);
+    var notifyCharacterEvent = !isInputEventSupported;
+    _this.keyboard.dispatchKeyEvent(event, this, notifyCharacterEvent);
   });
 
   this.keyboard.on('left', function(event) {
@@ -130,7 +168,11 @@ Dispatcher.prototype.setupKeyboardEvents = function() {
         event.preventDefault();
         event.stopPropagation();
         _this.notify('merge', this, 'before', cursor);
+      } else {
+        _this.triggerChangeEvent(this);
       }
+    } else {
+      _this.triggerChangeEvent(this);
     }
   }).on('delete', function(event) {
     log('Delete key pressed');
@@ -142,7 +184,11 @@ Dispatcher.prototype.setupKeyboardEvents = function() {
         event.preventDefault();
         event.stopPropagation();
         _this.notify('merge', this, 'after', cursor);
+      } else {
+        _this.triggerChangeEvent(this);
       }
+    } else {
+      _this.triggerChangeEvent(this);
     }
   }).on('enter', function(event) {
     log('Enter key pressed');
@@ -165,6 +211,8 @@ Dispatcher.prototype.setupKeyboardEvents = function() {
     event.stopPropagation();
     var cursor = _this.selectionWatcher.forceCursor();
     _this.notify('newline', this, cursor);
+  }).on('character', function(event) {
+    _this.notify('change', this);
   });
 };
 

src/keyboard.js

@@ -6,7 +6,7 @@ var Keyboard = function() {
   eventable(this);
 };
 
-Keyboard.prototype.dispatchKeyEvent = function(event, target) {
+Keyboard.prototype.dispatchKeyEvent = function(event, target, notifyCharacterEvent) {
   switch (event.keyCode) {
 
   case this.key.left:
@@ -52,7 +52,20 @@ Keyboard.prototype.dispatchKeyEvent = function(event, target) {
       this.notify(target, 'enter', event);
     }
     break;
-
+  case this.key.ctrl:
+  case this.key.shift:
+  case this.key.alt:
+    break;
+  // Metakey
+  case 224: // Firefox: 224
+  case 17: // Opera: 17
+  case 91: // Chrome/Safari: 91 (Left)
+  case 93: // Chrome/Safari: 93 (Right)
+    break;
+  default:
+    if (notifyCharacterEvent) {
+      this.notify(target, 'character', event);
+    }
   }
 };
 
@@ -65,7 +78,10 @@ Keyboard.prototype.key = {
   esc: 27,
   backspace: 8,
   'delete': 46,
-  enter: 13
+  enter: 13,
+  shift: 16,
+  ctrl: 17,
+  alt: 18
 };
 
 Keyboard.key = Keyboard.prototype.key;