Merge pull request angular-ui#1582 from PaulL1/external_filter_sort_f…

…alse

Add useExternalFiltering option and event

misc/site/data/100_female.json

@@ -0,0 +1,77 @@
+[
+    {
+        "name": "Ethel Price",
+        "gender": "female",
+        "company": "Enersol"
+    },
+    {
+        "name": "Claudine Neal",
+        "gender": "female",
+        "company": "Sealoud"
+    },
+    {
+        "name": "Beryl Rice",
+        "gender": "female",
+        "company": "Velity"
+    },
+    {
+        "name": "Georgina Schultz",
+        "gender": "female",
+        "company": "Suretech"
+    },
+    {
+        "name": "Valarie Atkinson",
+        "gender": "female",
+        "company": "Hopeli"
+    },
+    {
+        "name": "Lynda Mendoza",
+        "gender": "female",
+        "company": "Dogspa"
+    },
+    {
+        "name": "Sarah Massey",
+        "gender": "female",
+        "company": "Bisba"
+    },
+    {
+        "name": "Nellie Whitfield",
+        "gender": "female",
+        "company": "Exospace"
+    },
+    {
+        "name": "Lelia Gates",
+        "gender": "female",
+        "company": "Proxsoft"
+    },
+    {
+        "name": "Letitia Vasquez",
+        "gender": "female",
+        "company": "Slumberia"
+    },
+    {
+        "name": "Blanche Conley",
+        "gender": "female",
+        "company": "Imkan"
+    },
+    {
+        "name": "Kelli Leon",
+        "gender": "female",
+        "company": "Verbus"
+    },
+    {
+        "name": "Freda Mason",
+        "gender": "female",
+        "company": "Accidency"
+    },
+    {
+        "name": "Yvonne Parsons",
+        "gender": "female",
+        "company": "Zolar"
+    },
+    {
+        "name": "Jocelyn Sawyer",
+        "gender": "female",
+        "company": "Fortean"
+    }
+]

misc/site/data/100_male.json

@@ -0,0 +1,97 @@
+[
+    {
+        "name": "Wilder Gonzales",
+        "gender": "male",
+        "company": "Geekko"
+    },
+    {
+        "name": "Carroll Buchanan",
+        "gender": "male",
+        "company": "Ecosys"
+    },
+    {
+        "name": "Schroeder Mathews",
+        "gender": "male",
+        "company": "Polarium"
+    },
+    {
+        "name": "Robles Boyle",
+        "gender": "male",
+        "company": "Comtract"
+    },
+    {
+        "name": "Evans Hickman",
+        "gender": "male",
+        "company": "Parleynet"
+    },
+    {
+        "name": "Dawson Barber",
+        "gender": "male",
+        "company": "Dymi"
+    },
+    {
+        "name": "Bruce Strong",
+        "gender": "male",
+        "company": "Xyqag"
+    },
+    {
+        "name": "Jackson Macias",
+        "gender": "male",
+        "company": "Aquamate"
+    },
+    {
+        "name": "Pena Pena",
+        "gender": "male",
+        "company": "Quarx"
+    },
+    {
+        "name": "Trevino Moreno",
+        "gender": "male",
+        "company": "Conjurica"
+    },
+    {
+        "name": "Barr Page",
+        "gender": "male",
+        "company": "Apex"
+    },
+    {
+        "name": "Kirkland Merrill",
+        "gender": "male",
+        "company": "Utara"
+    },
+    {
+        "name": "Atkins Dunlap",
+        "gender": "male",
+        "company": "Comveyor"
+    },
+    {
+        "name": "Everett Foreman",
+        "gender": "male",
+        "company": "Maineland"
+    },
+    {
+        "name": "Gould Randolph",
+        "gender": "male",
+        "company": "Intergeek"
+    },
+    {
+        "name": "Tucker Maxwell",
+        "gender": "male",
+        "company": "Lumbrex"
+    },
+    {
+        "name": "Woods Key",
+        "gender": "male",
+        "company": "Bedder"
+    },
+    {
+        "name": "Stephens Reilly",
+        "gender": "male",
+        "company": "Acusage"
+    },
+    {
+        "name": "Mcfarland Sparks",
+        "gender": "male",
+        "company": "Comvey"
+    }
+]

misc/tutorial/308_external_filtering.ngdoc

@@ -0,0 +1,77 @@
+@ngdoc overview
+@name Tutorial: 308 External Filtering
+@description
+
+Sometimes you want to filter data externally, either on the client using custom filter routines, or on 
+the server as part of your data retrieve.
+
+UI-Grid provides two functions that support this, firstly a filterChanged event that tells you when a user has
+changed their requested filter using the grid ui, and secondly a useExternalFiltering property to turn off
+the grid native filtering.
+
+@example
+In this example we suppress the internal filtering, and emulate an external filter by picking one of three 
+json files to show - one filtered by gender 'male', one filtered by gender 'female', and one not sorted.  
+
+To further illustrate that this is using external sorting, the external filter routine (consisting of me manually 
+editing json files) got bored of filtering after the first 10 or so rows, and deleted all other rows in the file.
+
+<example module="app">
+  <file name="app.js">
+    var app = angular.module('app', ['ui.grid']);
+
+    app.controller('MainCtrl', ['$scope', '$http', '$interval', 'uiGridConstants', function ($scope, $http, $interval, uiGridConstants) {
+
+      $scope.gridOptions = {
+        enableFiltering: true,
+        useExternalFiltering: true,
+        columnDefs: [
+          { name: 'name', enableFiltering: false },
+          { name: 'gender' },
+          { name: 'company', enableFiltering: false}
+        ],
+        onRegisterApi: function( gridApi ) {
+          $scope.gridApi = gridApi;
+          $interval(function() {
+            $scope.gridApi.core.on.filterChanged( $scope, function() {
+              var grid = this.grid;
+              if( grid.columns[1].filters[0].term === 'male' ) {
+                $http.get('/data/100_male.json')
+                .success(function(data) {
+                  $scope.gridOptions.data = data;
+                });
+              } else if ( grid.columns[1].filters[0].term === 'female' ) {
+                $http.get('/data/100_female.json')
+                .success(function(data) {
+                  $scope.gridOptions.data = data;
+                });
+              } else {
+                $http.get('/data/100.json')
+                .success(function(data) {
+                  $scope.gridOptions.data = data;
+                });
+              }
+            });
+          }, 200, 1);
+        }
+      };
+
+      $http.get('/data/100.json')
+      .success(function(data) {
+        $scope.gridOptions.data = data;
+      });
+
+    }]);
+  </file>
+  <file name="index.html">
+    <div ng-controller="MainCtrl">
+      <div ui-grid="gridOptions" class="grid"></div>
+    </div>
+  </file>
+  <file name="main.css">
+    .grid {
+      width: 500px;
+      height: 250px;
+    }
+  </file>
+</example>

src/js/core/directives/ui-grid-header-cell.js

@@ -24,6 +24,21 @@
 
           post: function ($scope, $elm, $attrs, uiGridCtrl) {
             $scope.grid = uiGridCtrl.grid;
+
+            /**
+             * @ngdoc event
+             * @name filterChanged
+             * @eventOf  ui.grid.core.api:PublicApi
+             * @description  is raised after the filter is changed.  The nature
+             * of the watch expression doesn't allow notification of what changed,
+             * so the receiver of this event will need to re-extract the filter 
+             * conditions from the columns.
+             * 
+             */
+            if (!$scope.grid.api.core.raise.filterChanged){
+              $scope.grid.api.registerEvent( 'core', 'filterChanged' );
+            }
+
 
             $elm.addClass($scope.col.getColClass(false));
     // shane - No need for watch now that we trackby col name
@@ -154,6 +169,7 @@
               var filterDeregisters = [];
               angular.forEach($scope.col.filters, function(filter, i) {
                 filterDeregisters.push($scope.$watch('col.filters[' + i + '].term', function(n, o) {
+                  uiGridCtrl.grid.api.core.raise.filterChanged();
                   uiGridCtrl.grid.refresh()
                     .then(function () {
                       if (uiGridCtrl.prevScrollArgs && uiGridCtrl.prevScrollArgs.y && uiGridCtrl.prevScrollArgs.y.percentage) {

src/js/core/services/rowSearcher.js

@@ -254,6 +254,16 @@ module.service('rowSearcher', ['$log', 'uiGridConstants', function ($log, uiGrid
     return true;
   };
 
+  /**
+   * @ngdoc boolean
+   * @name useExternalFiltering
+   * @propertyOf ui.grid.class:GridOptions
+   * @description False by default. When enabled, this setting suppresses the internal filtering.
+   * All UI logic will still operate, allowing filter conditions to be set and modified.
+   * 
+   * The external filter logic can listen for the `filterChange` event, which fires whenever
+   * a filter has been adjusted.
+   */
   /**
    * @ngdoc function
    * @name searchColumn
@@ -267,10 +277,13 @@ module.service('rowSearcher', ['$log', 'uiGridConstants', function ($log, uiGrid
   rowSearcher.searchColumn = function searchColumn(grid, row, column, termCache) {
     var filters = [];
 
+    if (grid.options.useExternalFiltering) {
+      return true;
+    }
+
     if (typeof(column.filters) !== 'undefined' && column.filters && column.filters.length > 0) {
       filters = column.filters;
-    }
-    else {
+    } else {
       // If filters array is not there, assume no filters for this column. 
       // This array should have been built in GridColumn::updateColumnDef.
       return true;

test/unit/core/row-filtering.spec.js

@@ -227,6 +227,18 @@ describe('rowSearcher', function() {
     });
   });
 
+  describe('with external filtering', function () {
+    it('should not filter at all', function () {
+      grid.options.useExternalFiltering = true;
+      setFilter(columns[0], 'Bi*ll');
+
+      var ret = rowSearcher.search(grid, rows, columns);
+
+      expect(ret[0].visible).toBe(true);
+      expect(ret[1].visible).toBe(true);
+    });
+  });
+
   describe('with a custom filter function', function() {
     var custom, ret;
     beforeEach(function() {