Merge pull request #5248 from fallXone/keyDownOverrides

Option to override cell navigation defaults

Author: mportuga

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();
+  });
 });