feat(sort): Give more information to the sort functions

Sort functions are now passed additional rowA, rowB, and direction parameters

Author: Rhathe

misc/tutorial/102_sorting.ngdoc

@@ -34,6 +34,11 @@ asynchronously after the columns it will often decide all your columns are strin
 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.
 
+You can pass in a custom sorting algorithm to a column by setting the
+{@link api/ui.grid.class:GridOptions.columnDef#sortingAlgorithm sortingAlgorithm} columnDef option.
+The sorting algorithm function takes 'a' and 'b' parameters like any normal sorting function with additional
+'rowA', 'rowB', and 'direction' parameters that are the row objects and the current direction of the sort respectively.
+
 By default the sorting algorithm will be applied to the row value before any `cellFilters` are applied. The {@link api/ui.grid.class:GridOptions.columnDef#sortCellFiltered sortCellFiltered}
 columnDef option will cause sorting to be applied after the `cellFilters` are applied. For an example of this see the "Month Joined" column in the {@link 401_AllFeatures AllFeatures tutorial}.
 
@@ -83,7 +88,7 @@ columnDef option will cause sorting to be applied after the `cellFilters` are ap
               priority: 0,
             },
             suppressRemoveSort: true,
-            sortingAlgorithm: function(a, b) {
+            sortingAlgorithm: function(a, b, rowA, rowB, direction) {
               var nulls = $scope.grid2Api.core.sortHandleNulls(a, b);
               if( nulls !== null ) {
                 return nulls;

src/js/core/factories/GridColumn.js

@@ -295,21 +295,13 @@ angular.module('ui.grid')
   */
 
 
-  /**
-   * @ngdoc property
-   * @name sortingAlgorithm
-   * @propertyOf ui.grid.class:GridColumn
-   * @description Algorithm to use for sorting this column. Takes 'a' and 'b' parameters
-   * like any normal sorting function.
-   *
-   */
-
   /**
    * @ngdoc property
    * @name sortingAlgorithm
    * @propertyOf ui.grid.class:GridOptions.columnDef
    * @description Algorithm to use for sorting this column. Takes 'a' and 'b' parameters
-   * like any normal sorting function.
+   * like any normal sorting function with additional 'rowA', 'rowB', and 'direction' parameters
+   * that are the row objects and the current direction of the sort respectively.
    *
    */
 

src/js/core/services/rowSorter.js

@@ -418,7 +418,7 @@ module.service('rowSorter', ['$parse', 'uiGridConstants', function ($parse, uiGr
     if (sortCols.length === 0) {
       return rows;
     }
-    
+
     // Re-usable variables
     var col, direction;
 
@@ -444,7 +444,7 @@ module.service('rowSorter', ['$parse', 'uiGridConstants', function ($parse, uiGr
         direction = sortCols[idx].sort.direction;
 
         sortFn = rowSorter.getSortFn(grid, col, r);
-        
+
         var propA, propB;
 
         if ( col.sortCellFiltered ){
@@ -455,7 +455,7 @@ module.service('rowSorter', ['$parse', 'uiGridConstants', function ($parse, uiGr
           propB = grid.getCellValue(rowB, col);
         }
 
-        tem = sortFn(propA, propB);
+        tem = sortFn(propA, propB, rowA, rowB, direction);
 
         idx++;
       }
@@ -467,7 +467,7 @@ module.service('rowSorter', ['$parse', 'uiGridConstants', function ($parse, uiGr
       if (tem === 0 ) {
         return rowA.entity.$$uiGridIndex - rowB.entity.$$uiGridIndex;
       }
-      
+
       // Made it this far, we don't have to worry about null & undefined
       if (direction === uiGridConstants.ASC) {
         return tem;