angular-groupsort by yuval oren

The group And Sort is a transcluding directive to will group an array of objects into categories as deep as you like. After grouping your objects into categories, you may sort your categories at every level and finally, sort your items.

Objects may not be fully categorised, if some of the objects do not have as many sub-categories as other objects, they simply remain at the group into which they were categorised.

Grouping and sorting is not mandatory. You can group item and skip sort or skip grouping and justsort items. (however, if you do not group - you cannot sort by categories).

Grouping and sorting of categories and items is acheived by calling your assigned grouping and sorting functions as described bellow.

The group And Sort directive does nothing until data is requested by its transcluded directive. You call the directive's 'data' function in order to retreive the groupd and sorted objects which are encapsulated in a convinient-to-retreive data structure.

Dependencies

The Angular Group and Sort sole dependency is on AngularJS 1.5.6 [get AngularJS](http://angularjs.org/)

Demo

Below you can see examples of 3-level and 2-level grouping of America's professional Baseball teams. The leage, divisions and clubs are than sorted in asccending order.

Properties

The directive exihibts the following properties:

objects

An array of objects you wish to group and/or sort.

group-by

The name of the grouping function used for dividing objects into different caregories. The function will be passed an object and a level (specifying grouping depth) one at a time until all objects are categorised. The function is expected to return a string (the category name) or null if the item has been fully categorised.

                
groupingFunction = function(object, level) {
    your grouping logic ...
    return categoryName or return null
}

sort-categories

The name of sorting function used to sort categories (only when grouping is in effect). The function will be passed two category names at a time and should return a value less than zero if the first category should be ordered before the second category, zero if the categories may appear in any order, or a value greater than zero if the second category should be ordered before the first.

                
categorySortingFunction = function(categoryName1, categoryName2) {
	your sorting logic ...
	return -1 // category1 appears before category2
	or return 0 // either one may appear before the other
	or return 1 // category2 appears before category1
}

sort-items

The name of sorting function used to sort the inputed objects (regardless of grouping and/or categry sorting). The function will be passed two objects at a time and should return a value less than zero if the first object should be ordered before the second object, zero if the objects may appear in any order, or a value greater than zero if the second object should be ordered before the first.

                
itemSortingFunction=function(obj1, obj2) {
    your sorting logic ...
    return -1 // obj1 appears before obj2
    or return 0 // either one may appear before the other
    or return 1 // obj2 appears before obj1
}

Methods

data

The data function should be called by the transcluded directive in order to pull its data from the Group and Sort directive. Only then will the directive proccess its input array of objects - group and sort (categories and/or items) if needed - before returning an array of output objects as specified bellow:

                
[
    {
        category: categoryName,
        isLeaf: true / false
        objects: [ array of objects ]
    },
]

The value of the top-most category will always be null as this is the root of the catgories tree.

If no grouping is requested, then all the objects are present in the 'objects' array. (the objects may still be sorted, if a sort-items function was provided to the directive.)

If grouping is requested, then each category will be manifested in the 'object' array as an object whose properties are 'category' 'isLeaf' and 'objects' as the object depicted above. At each level objects who are cannot be further categorised (as the rest) are collected into an array which is the last element of the objects array.

If the value of property 'isLeaf' equals 'true' then you know that there are no further sub-categories in this group and that the objects array contains (fully categorised) plain objects only.

If all your objects are fully categorised, then you need not worry about not fully categorised items. All your objects will like the one above, and all your objects will be at leafs.

Install with Bower

When you install with bower, you only get the javascript source file and the README.md file. If you want to download the example, get the zip or tar files from Github.

$ bower install angular-groupsort

angular-groupsort

angular grouping and sorting directive