307_external_sorting.ngdoc

@ngdoc overview
@name Tutorial: 307 External Sorting
@description

Sometimes you want to sort data externally, either on the client using custom sort routines or on the server as part of
your data retrieve.

UI-Grid provides two functions that support this, firstly a sortChanged event that tells you when a user has
changed their requested sort using the grid ui, and secondly a useExternalSorting property to turn off
the grid native sorting.

For better performance with the following example, you can choose to load the ui-grid.core.js instead:
<pre>
  <script src="/release/ui-grid.core.min.js"></script>
</pre>

@example
In this example we suppress the internal sorting, and emulate an external sort by picking one of three
json files to show - one sorted by name ASC, one sorted by name DESC, and one not sorted.  To further illustrate that this
is using external sorting, the external sort routine (consisting of me manually editing json files) got bored
of sorting after the first 10 or so rows.

We allow sorting by the first and second columns, so that we can show a default sort and that default sort
indicator being removed even when using external sorting.  Our external sort routine ignores that second
column however, so sorting by it has no effect.

<example module="app">
  <file name="app.js">
    var app = angular.module('app', ['ngTouch', 'ui.grid']);

    app.controller('MainCtrl', ['$scope', '$http', '$interval', 'uiGridConstants', function ($scope, $http, $interval, uiGridConstants) {

      $scope.sortChanged = function ( grid, sortColumns ) {
        if( sortColumns.length === 0 || sortColumns[0].name !== $scope.gridOptions.columnDefs[0].name ){
          $http.get('/data/100.json')
          .then(function(response) {
            $scope.gridOptions.data = response.data;
          });
        } else {
          switch( sortColumns[0].sort.direction ) {
            case uiGridConstants.ASC:
              $http.get('/data/100_ASC.json')
              .then(function(response) {
                $scope.gridOptions.data = response.data;
              });
              break;
            case uiGridConstants.DESC:
              $http.get('/data/100_DESC.json')
              .then(function(response) {
                $scope.gridOptions.data = response.data;
              });
              break;
            case undefined:
              $http.get('/data/100.json')
              .then(function(response) {
                $scope.gridOptions.data = response.data;
              });
              break;
          }
        }
      };

      $scope.gridOptions = {
        useExternalSorting: true,
        columnDefs: [
          { name: 'name' },
          { name: 'gender' },
          { name: 'company', enableSorting: false}
        ],
        onRegisterApi: function( gridApi ) {
          $scope.gridApi = gridApi;
          $scope.gridApi.core.on.sortChanged( $scope, $scope.sortChanged );
          $scope.sortChanged($scope.gridApi.grid, [ $scope.gridOptions.columnDefs[1] ] );
        }
      };

    }]);
  </file>
  <file name="index.html">
    <div ng-controller="MainCtrl">
      <div id="grid1" ui-grid="gridOptions" class="grid"></div>
    </div>
  </file>
  <file name="main.css">
    .grid {
      width: 500px;
      height: 250px;
    }
  </file>
    <file name="scenario.js">
    var gridTestUtils = require('../../test/e2e/gridTestUtils.spec.js');

    describe('307 tutorial', function() {
      // Reload the page before each test if on Firefox. Chrome does it automatically.
      gridTestUtils.firefoxReload();

      it('grid should have three visible columns', function () {
        gridTestUtils.expectHeaderColumnCount( 'grid1', 3 );
      });

      it('header values should be as expected', function () {
        gridTestUtils.expectHeaderCellValueMatch( 'grid1', 0, 'Name' );
        gridTestUtils.expectHeaderCellValueMatch( 'grid1', 1, 'Gender' );
        gridTestUtils.expectHeaderCellValueMatch( 'grid1', 2, 'Company' );
      });

      it('grid should be unsorted by default', function () {
        gridTestUtils.expectCellValueMatch( 'grid1', 0, 0, 'Ethel Price' );
        gridTestUtils.expectCellValueMatch( 'grid1', 1, 0, 'Claudine Neal' );
      });

      it('sort by name by clicking header', function () {
        gridTestUtils.clickHeaderCell( 'grid1', 0 )
          .then(function () {
            gridTestUtils.expectCellValueMatch( 'grid1', 0, 0, 'Alexander Foley' );
            gridTestUtils.expectCellValueMatch( 'grid1', 1, 0, 'Alisha Myers' );
          });
      });

      it('reverse sort by name by clicking header', function () {
        gridTestUtils.clickHeaderCell( 'grid1', 0 )
          .then(function () {
            return gridTestUtils.clickHeaderCell( 'grid1', 0 );
          })
          .then(function () {
            gridTestUtils.expectCellValueMatch( 'grid1', 0, 0, 'Yvonne Parsons' );
            gridTestUtils.expectCellValueMatch( 'grid1', 1, 0, 'Woods Key' );
          });
      });

      it('return to original sort by name by clicking header', function () {
        gridTestUtils.clickHeaderCell( 'grid1', 0 )
          .then(function () {
            return gridTestUtils.clickHeaderCell( 'grid1', 0 );
          })
          .then(function () {
            return gridTestUtils.clickHeaderCell( 'grid1', 0 );
          })
          .then(function () {
            gridTestUtils.expectCellValueMatch( 'grid1', 0, 0, 'Ethel Price' );
            gridTestUtils.expectCellValueMatch( 'grid1', 1, 0, 'Claudine Neal' );
          });
      });

      it('sort ignored on second column', function() {
        gridTestUtils.clickHeaderCell( 'grid1', 1 )
          .then(function () {
            gridTestUtils.expectCellValueMatch( 'grid1', 0, 0, 'Ethel Price' );
            gridTestUtils.expectCellValueMatch( 'grid1', 1, 0, 'Claudine Neal' );
          });
      });

      it('sort disabled on last column', function() {
        gridTestUtils.clickHeaderCell( 'grid1', 2 )
          .then(function () {
            gridTestUtils.expectCellValueMatch( 'grid1', 0, 0, 'Ethel Price' );
            gridTestUtils.expectCellValueMatch( 'grid1', 1, 0, 'Claudine Neal' );
          });
      });
    });
  </file>
</example>