Option to override cell navigation defaults

Option to override default cell navigation

keyDownOverrides will force the viewPortKeyDown event
to be triggered if the specified key event was pressed
down, even if it is a default key command for the grid.
The handling of the event should then be done in the
viewPortKeyDown handler since the grid is no longer
handling the event.

Author: conner-fallone

misc/tutorial/202_cellnav.ngdoc

@@ -28,6 +28,8 @@ Provides an example of scrolling to and setting the focus on a specific cell, us
 Provides an example of utilizing the modifierKeysToMultiSelectCells option and getCurrentSelection API function to
 extract values of selected cells.
 
+Provides an example of utilizing the keyDownOverrides to add a custom Ctrl + Right to focus the last column in the row,
+while still allowing the right arrow to be handled by the grid.
 @example
 <example module="app">
   <file name="app.js">
@@ -36,6 +38,7 @@ extract values of selected cells.
     app.controller('MainCtrl', ['$scope', '$http', '$log', function ($scope, $http, $log) {
       $scope.gridOptions = {
         modifierKeysToMultiSelectCells: true,
+        keyDownOverrides: [ { keyCode: 39, ctrlKey: true }],
         showGridFooter: true
       };
       $scope.gridOptions.columnDefs = [
@@ -94,6 +97,13 @@ extract values of selected cells.
                  // }
                   $log.log('navigation event');
                 });
+            gridApi.cellNav.on.viewPortKeyDown($scope,function(event, newRowCol){
+                    var row = newRowCol.row;
+                    var col = newRowCol.col
+                    if (event.keyCode === 39) {
+                        $scope.gridApi.cellNav.scrollToFocus(row.entity, $scope.gridApi.grid.columns[$scope.gridApi.grid.columns.length - 1]);
+                    }
+                });
         };
     }]);
   </file>

src/features/cellnav/js/cellnav.js

@@ -418,6 +418,16 @@
            *  <br/>Defaults to false
            */
           gridOptions.modifierKeysToMultiSelectCells = gridOptions.modifierKeysToMultiSelectCells === true;
+          
+          /**
+           *  @ngdoc array
+           *  @name keyDownOverrides
+           *  @propertyOf  ui.grid.cellNav.api:GridOptions
+           *  @description An array of event objects to override on keydown. If an event is overridden, the viewPortKeyDown event will
+           *               be raised with the overridden events, allowing custom keydown behavior.
+           *  <br/>Defaults to []
+           */
+          gridOptions.keyDownOverrides = gridOptions.keyDownOverrides || [];
 
         },
 
@@ -902,7 +912,12 @@
               focuser.on('keydown', function (evt) {
                 evt.uiGridTargetRenderContainerId = containerId;
                 var rowCol = uiGridCtrl.grid.api.cellNav.getFocusedCell();
-                var result = uiGridCtrl.cellNav.handleKeyDown(evt);
+                var raiseViewPortKeyDown = uiGridCtrl.grid.options.keyDownOverrides.some(function (override) {
+                    return Object.keys(override).every( function (property) {
+                        return override[property] === evt[property];
+                    });
+                });
+                var result = raiseViewPortKeyDown ? null : uiGridCtrl.cellNav.handleKeyDown(evt);
                 if (result === null) {
                   uiGridCtrl.grid.api.cellNav.raise.viewPortKeyDown(evt, rowCol);
                   viewPortKeyDownWasRaisedForRowCol = rowCol;

src/features/cellnav/test/uiGridCellNavDirective.spec.js

@@ -11,7 +11,8 @@ describe('ui.grid.cellNav directive', function () {
 
     $scope.gridOpts = {
       data: [{ name: 'Bob' }, {name: 'Mathias'}, {name: 'Fred'}],
-      modifierKeysToMultiSelectCells: true
+      modifierKeysToMultiSelectCells: true,
+      keyDownOverrides: [{ keyCode: 39 }]
     };
 
     $scope.gridOpts.onRegisterApi = function (gridApi) {
@@ -71,4 +72,48 @@ describe('ui.grid.cellNav directive', function () {
 	$scope.grid.cellNav.broadcastCellNav({ row: $scope.grid.rows[0], col: $scope.grid.columns[0] }, true);
 	expect($scope.grid.cellNav.focusedCells.length).toEqual(1);
   });
+
+  it('should not call handleKeyDown if the key event is overridden', function () {
+    spyOn(elm.controller('uiGrid').cellNav, 'handleKeyDown');
+    var focuser = elm.find('focuser');
+    var evt = jQuery.Event("keydown");
+    evt.keyCode = 39;
+
+    focuser.trigger(evt);
+
+    expect(elm.controller('uiGrid').cellNav.handleKeyDown).not.toHaveBeenCalled();
+  });
+
+  it('should call handleKeyDown if the key event is not overridden', function () {
+    spyOn(elm.controller('uiGrid').cellNav, 'handleKeyDown');
+    var focuser = elm.find('.ui-grid-focuser');
+    var evt = jQuery.Event("keydown");
+    evt.keyCode = 37;
+
+    focuser.trigger(evt);
+
+    expect(elm.controller('uiGrid').cellNav.handleKeyDown).toHaveBeenCalled();
+  });
+
+  it('should raise the viewPortKeyDown event if the key is overridden', function () {
+    spyOn(elm.controller('uiGrid').grid.api.cellNav.raise, 'viewPortKeyDown');
+    var focuser = elm.find('.ui-grid-focuser');
+    var evt = jQuery.Event("keydown");
+    evt.keyCode = 39;
+
+    focuser.trigger(evt);
+
+    expect(elm.controller('uiGrid').grid.api.cellNav.raise.viewPortKeyDown).toHaveBeenCalled();
+  });
+
+  it('should not raise the viewPortKeyDown event if the key is not overridden and is part of the base cell navigation keyboard support', function () {
+    spyOn(elm.controller('uiGrid').grid.api.cellNav.raise, 'viewPortKeyDown');
+    var focuser = elm.find('.ui-grid-focuser');
+    var evt = jQuery.Event("keydown");
+    evt.keyCode = 37;
+
+    focuser.trigger(evt);
+
+    expect(elm.controller('uiGrid').grid.api.cellNav.raise.viewPortKeyDown).not.toHaveBeenCalled();
+  });
 });