102_sorting.ngdoc

@ngdoc overview
@name Tutorial: 102 Sorting
@description

UI-Grid allows you to sort rows. The feature is on by default. You can set the `enableSorting` flag in your grid options to enable/disable it.

<span class="col-xs-12 alert alert-warning">
  <strong>Note:</strong> You can sort columns by accessing the column menu. You must include ngAnimate in your application if you want the menu to slide up/down, but it's not required.
</span>

Sorting can be disabled at the column level by setting `enableSorting: false` in the column def. See the last column below for an example.

Multiple columns can be sorted by shift-clicking on the 2-n columns.  To see it in action, sort Gender then shift-click Name.

When sorting using the menus, the sorts are additive.  So if you have one column sorted and you pick another sort
from a column menu, it will add on to the existing sort rather than replacing it.  You need to use the 'remove sort' option
on the existing column if you don't want to sort by it any more.

When sorting using the headers, clicking on a header removes all other sorts unless you shift-click.

The sort is automatically recalculated when you edit a field (the edit feature calls the dataChange api to notify of a data change).  If
you change the data "behind the scenes" and want the sort to be recalculated, you can notify the grid that your
data has changed by calling `gridApi.core.notifyDataChange( uiGridConstants.dataChange.EDIT )`

If you set a default sort, you can prevent the user from removing that sort by setting `suppressRemoveSort: true`
for that column.  This will let the user change the direction of the sort, but take away the option to remove the sort.

The sort algorithm is chosen based on the column type.  ui-grid will guess the type based on the data, although if you load data
asynchronously after the columns it will often decide all your columns are string.  You can explicitly set the column type in the
column def using `type='number'`.  Valid types are documented in {@link api/ui.grid.class:GridOptions.columnDef columnDef}, and
include `string`, `number`, `numberStr` and `date`.  If you use date be aware the code expects a javascript date object.

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

    app.controller('MainCtrl', ['$scope', '$http', 'uiGridConstants', function ($scope, $http, uiGridConstants) {
      $scope.gridOptions1 = {
        enableSorting: true,
        columnDefs: [
          { field: 'name' },
          { field: 'gender' },
          { field: 'company', enableSorting: false }
        ],
        onRegisterApi: function( gridApi ) {
          $scope.grid1Api = gridApi;
        }
      };

      $scope.toggleGender = function() {
        if( $scope.gridOptions1.data[64].gender === 'male' ) {
          $scope.gridOptions1.data[64].gender = 'female';
        } else {
          $scope.gridOptions1.data[64].gender = 'male';
        };
        $scope.grid1Api.core.notifyDataChange( uiGridConstants.dataChange.EDIT );
      };

       $scope.gridOptions2 = {
        enableSorting: true,
        onRegisterApi: function( gridApi ) {
          $scope.grid2Api = gridApi;
        },
        columnDefs: [
          {
            field: 'name',
            sort: {
              direction: uiGridConstants.DESC,
              priority: 1
            }
          },
          {
            field: 'gender',
            sort: {
              direction: uiGridConstants.ASC,
              priority: 0,
            },
            suppressRemoveSort: true,
            sortingAlgorithm: function(a, b) {
              var nulls = $scope.grid2Api.core.sortHandleNulls(a, b);
              if( nulls !== null ) {
                return nulls;
              } else {
                if( a === b ) {
                  return 0;
                }
                if( a === 'male' ) {
                  return 1;
                }
                if( b === 'male' ) {
                  return -1;
                }
                if( a == 'female' ) {
                  return 1;
                }
                if( b === 'female' ) {
                  return -1;
                }
                return 0;
              }
            }
          },
          { field: 'company', enableSorting: false  }
        ]
      };

     $http.get('/data/100.json')
        .success(function(data) {
          $scope.gridOptions1.data = data;
          $scope.gridOptions2.data = data;
        });
    }]);
  </file>
  <file name="index.html">
    <div ng-controller="MainCtrl">
      Click on a column header to sort by that column. (The third column has sorting disabled.)
      To demonstrate the live sorting we provide a button that toggles the gender of Alexander Foley.
      Sort by gender (ASC - so click twice) then name (using shift click), so that Alexander is at the top of the grid,
      then click the toggleGender button.

      <br>
      <br>
      <button id='toggleGender' ng-click='toggleGender()' class="btn btn-success" >Toggle Gender</button>
      <div id="grid1" ui-grid="gridOptions1" class="grid"></div>

      <br>
      You can set an initial sort state for the grid by defining the `sort` property on your column definitions.
      The `direction` sub-property says which way to sort, and the `priority` says what order to sort the columns
      in (lower priority gets sorted first).
      <br>
      <br>

      <div id="grid2" ui-grid="gridOptions2" class="grid"></div>
    </div>
  </file>
  <file name="main.css">
    .grid {
      width: 500px;
      height: 200px;
    }
  </file>
  <file name="scenario.js">
    var gridTestUtils = require('../../test/e2e/gridTestUtils.spec.js');

    describe('first grid on the page, no default sort', 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 asc by clicking menu', function() {
        gridTestUtils.clickColumnMenuSortAsc( 'grid1', 0 )
          .then(function () {
            gridTestUtils.expectCellValueMatch( 'grid1', 0, 0, 'Alexander Foley' );
            gridTestUtils.expectCellValueMatch( 'grid1', 1, 0, 'Alisha Myers' );
          });
      });

      it('sort desc by clicking menu, then remove sort', function() {
        gridTestUtils.clickColumnMenuSortDesc( 'grid1', 0 )
          .then(function () {
            gridTestUtils.expectCellValueMatch( 'grid1', 0, 0, 'Yvonne Parsons' );
            gridTestUtils.expectCellValueMatch( 'grid1', 1, 0, 'Woods Key' );
            return true;
          })
          .then(function () {
            return gridTestUtils.clickColumnMenuRemoveSort( 'grid1', 0 );
          })
          .then(function () {
            gridTestUtils.expectCellValueMatch( 'grid1', 0, 0, 'Ethel Price' );
            gridTestUtils.expectCellValueMatch( 'grid1', 1, 0, 'Claudine Neal' );
          });
      });

      it('sort two columns, gender then name, by shift clicking', function() {
        gridTestUtils.clickHeaderCell( 'grid1', 1 )
          .then(function () {
            return gridTestUtils.shiftClickHeaderCell( 'grid1', 0 );
          })
          .then(function () {
            gridTestUtils.expectCellValueMatch( 'grid1', 0, 0, 'Alisha Myers' );
            gridTestUtils.expectCellValueMatch( 'grid1', 1, 0, 'Beryl Rice' );
          });
      });

      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' );
          });
      });

      it('click one menu, then click another menu, expect undisplay and redisplay on second click', function() {
        gridTestUtils.expectVisibleColumnMenuItems( 'grid1', 0, 3 );
        gridTestUtils.expectVisibleColumnMenuItems( 'grid1', 1, 3 );
      });

      it('toggle gender, expect Alexander Foley to move around', function() {
        // sort gender asc, then name
        gridTestUtils.clickHeaderCell( 'grid1', 1 )
          .then(function () {
            return gridTestUtils.clickHeaderCell( 'grid1', 1 );
          })
          .then(function () {
            return gridTestUtils.shiftClickHeaderCell( 'grid1', 0 );
          })
          .then(function () {
            gridTestUtils.expectCellValueMatch( 'grid1', 0, 0, 'Alexander Foley' );
          })
          .then(function () {
            return gridTestUtils.click(element(by.id('toggleGender')));
          })
          .then(function () {
            gridTestUtils.expectCellValueMatch( 'grid1', 0, 0, 'Anthony Joyner' );
          })
          .then(function () {
            return gridTestUtils.click(element(by.id('toggleGender')));
          })
          .then(function () {
            gridTestUtils.expectCellValueMatch( 'grid1', 0, 0, 'Alexander Foley' );
          });
      });

    });


    describe('second grid on the page, has default sort', function() {
      it('grid should have three visible columns', function () {
        gridTestUtils.expectHeaderColumnCount( 'grid2', 3 );
      });

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

      it('grid should be sorted by default', function () {
        gridTestUtils.expectCellValueMatch( 'grid2', 0, 0, 'Yvonne Parsons' );
        gridTestUtils.expectCellValueMatch( 'grid2', 1, 0, 'Velma Fry' );
      });

      it('sort on second column can\'t be removed when cycle through header clicks', function () {
        gridTestUtils.clickHeaderCell( 'grid2', 0 )
          .then(function () {
            gridTestUtils.expectCellValueMatch( 'grid2', 0, 0, 'Ethel Price' );
          })
          .then(function () {
            return gridTestUtils.clickHeaderCell( 'grid2', 1 );
          })
          .then(function () {
            gridTestUtils.expectCellValueMatch( 'grid2', 0, 0, 'Wilder Gonzales' );
          })
          .then(function () {
            return gridTestUtils.clickHeaderCell( 'grid2', 1 );
          })
          .then(function () {
            gridTestUtils.expectCellValueMatch( 'grid2', 0, 0, 'Ethel Price' );
          });
      });
    });

  </file>
</example>