misc/tutorial/208_save_state.ngdoc

@@ -0,0 +1,118 @@
+@ngdoc overview
+@name Tutorial: 208 Saving and restoring the state of the grid
+@description The save state feature allows you to save the current look of the grid
+and restore it upon returning to the grid.
+
+For example, you may have an application where your user can reorder the columns,
+adjust column widths, apply sorts and filters, and select a specific cell.  The user
+might adjust their grid to look as they wish, and then navigate to another page.  When 
+the user returns to the page with the grid, they might expect it to look like it
+did when they left.  The save state feature permits this.
+
+There are two core methods:
+
+- save, which packages the current grid state into an object which the calling application 
+then stores somewhere (a cookie, session state, a database)
+- restore, which takes a grid state object, and returns the grid to the state that 
+is stored in that object
+
+Note that the saveState functionality deliberately sets out to store the transient state - 
+the information that isn't held in gridOptions nor columnDefs.  The calling application is responsible for
+storing gridOptions and columnDefs (and must have had them in order to render the grid the first time).
+
+The feature also provides some options that control what is saved.  All options are true by
+default:
+
+- saveWidths
+- saveOrder
+- saveScroll
+- saveFocus
+- saveVisible
+- saveSort
+- saveFilter
+
+@example
+In this example we provide a button to save the grid state.  You can then modify the grid layout
+to something different, and use the restore button to set the grid back the way it was.
+
+
+<example module="app">
+  <file name="app.js">
+    var app = angular.module('app', ['ngAnimate', 'ngTouch', 'ui.grid', 'ui.grid.saveState', 'ui.grid.selection', 'ui.grid.cellNav', 'ui.grid.resizeColumns', 'ui.grid.moveColumns' ]);
+
+    app.controller('MainCtrl', ['$scope', '$http', '$interval', function ($scope, $http, $interval) {
+      $scope.gridOptions = {
+        saveFocus: false,
+        saveScroll: true,
+        enableFiltering: true,
+        onRegisterApi: function(gridApi){ 
+          $scope.gridApi = gridApi;
+        }
+      };
+      $scope.state = {};
+
+      $scope.saveState = function() {
+        $scope.state = $scope.gridApi.saveState.save();
+      };
+
+      $scope.restoreState = function() {
+        $scope.gridApi.saveState.restore( $scope, $scope.state );
+      };
+
+      $http.get('/data/100.json')
+        .success(function(data) {
+          $scope.gridOptions.data = data;
+        });
+    }]);
+  </file>
+
+  <file name="index.html">
+    <div ng-controller="MainCtrl">
+      <div id="grid1" ui-grid="gridOptions" ui-grid-save-state ui-grid-selection ui-grid-cellNav ui-grid-resize-columns ui-grid-move-columns class="grid"></div>
+      <button id="save" type="button" class="btn btn-success" ng-click="saveState()">Save</button>
+      <button id="restore" type="button" class="btn btn-success" ng-click="restoreState()">Restore</button>
+    </div>
+  </file>
+
+  <file name="main.css">
+    .grid {
+      width: 500px;
+      height: 400px;
+    }
+  </file>
+  <file name="scenario.js">
+    var gridTestUtils = require('../../test/e2e/gridTestUtils.spec.js');
+    describe( '208 save state', function() {
+      it('Set a sort and a filter, save state, hide a column and remove sort and filter, set another sort and filter, restore the state', function () {
+        gridTestUtils.expectHeaderColumnCount( 'grid1', 3 );
+
+        gridTestUtils.expectHeaderCellValueMatch( 'grid1', 0, 'Name' );
+        gridTestUtils.expectHeaderCellValueMatch( 'grid1', 1, 'Gender' );
+        gridTestUtils.expectHeaderCellValueMatch( 'grid1', 2, 'Company' );
+        gridTestUtils.expectCellValueMatch( 'grid1', 0, 0, 'Ethel Price' );
+
+        gridTestUtils.clickColumnMenuSortAsc( 'grid1', 2 );
+        gridTestUtils.enterFilterInColumn( 'grid1', 1, 'female' );
+        gridTestUtils.expectCellValueMatch( 'grid1', 0, 0, 'Freda Mason' );
+
+        element(by.id('save')).click();
+
+        gridTestUtils.clickColumnMenuRemoveSort( 'grid1', 2 );
+        gridTestUtils.cancelFilterInColumn( 'grid1', 1 );
+        gridTestUtils.expectCellValueMatch( 'grid1', 0, 0, 'Ethel Price' );
+
+        gridTestUtils.clickColumnMenuSortAsc( 'grid1', 0 );
+        gridTestUtils.enterFilterInColumn( 'grid1', 2, 'Gee' );
+        gridTestUtils.clickColumnMenuHide( 'grid1', 1 );
+        gridTestUtils.expectCellValueMatch( 'grid1', 0, 0, 'Alexander Foley' );
+        gridTestUtils.expectHeaderColumnCount( 'grid1', 2 );
+
+        element(by.id('restore')).click();
+
+        gridTestUtils.expectHeaderColumnCount( 'grid1', 3 );
+        gridTestUtils.expectCellValueMatch( 'grid1', 0, 0, 'Freda Mason' );
+      });
+
+    });
+  </file>  
+</example>

src/features/cellnav/js/cellnav.js

@@ -208,13 +208,11 @@
                  * @name scrollTo
                  * @methodOf  ui.grid.cellNav.api:PublicApi
                  * @description brings the specified row and column into view
-                 * @param {Grid} grid the grid you'd like to act upon, usually available
-                 * from gridApi.grid
                  * @param {object} $scope a scope we can broadcast events from
                  * @param {object} rowEntity gridOptions.data[] array instance to make visible
                  * @param {object} colDef to make visible
                  */
-                scrollTo: function (grid, $scope, rowEntity, colDef) {
+                scrollTo: function ($scope, rowEntity, colDef) {
                   service.scrollTo(grid, $scope, rowEntity, colDef);
                 },
 
@@ -224,13 +222,11 @@
                  * @methodOf  ui.grid.cellNav.api:PublicApi
                  * @description brings the specified row and column into view, and sets focus
                  * to that cell
-                 * @param {Grid} grid the grid you'd like to act upon, usually available
-                 * from gridApi.grid
                  * @param {object} $scope a scope we can broadcast events from
                  * @param {object} rowEntity gridOptions.data[] array instance to make visible and set focus
                  * @param {object} colDef to make visible and set focus
                  */
-                scrollToFocus: function (grid, $scope, rowEntity, colDef) {
+                scrollToFocus: function ($scope, rowEntity, colDef) {
                   service.scrollToFocus(grid, $scope, rowEntity, colDef);
                 },
 
@@ -350,11 +346,11 @@
         scrollTo: function (grid, $scope, rowEntity, colDef) {
           var gridRow = null, gridCol = null;
 
-          if (rowEntity !== null) {
+          if (rowEntity !== null && typeof(rowEntity) !== 'undefined' ) {
             gridRow = grid.getRow(rowEntity);
           }
 
-          if (colDef !== null) {
+          if (colDef !== null && typeof(colDef) !== 'undefined' ) {
             gridCol = grid.getColumn(colDef.name ? colDef.name : colDef.field);
           }
           this.scrollToInternal(grid, $scope, gridRow, gridCol);

src/features/exporter/js/exporter.js

@@ -158,7 +158,7 @@
            * @ngdoc object
            * @name ui.grid.exporter.api:GridOptions
            *
-           * @description GridOptions for selection feature, these are available to be  
+           * @description GridOptions for exporter feature, these are available to be  
            * set using the ui-grid {@link ui.grid.class:GridOptions gridOptions}
            */
           /**