Ember.SortableMixin Class
Ember.SortableMixin provides a standard interface for array proxies
to specify a sort order and maintain this sorting when objects are added,
removed, or updated without changing the implicit order of their underlying
content array:
songs = [
{trackNumber: 4, title: 'Ob-La-Di, Ob-La-Da'},
{trackNumber: 2, title: 'Back in the U.S.S.R.'},
{trackNumber: 3, title: 'Glass Onion'},
];
songsController = Ember.ArrayController.create({
content: songs,
sortProperties: ['trackNumber'],
sortAscending: true
});
songsController.get('firstObject'); // {trackNumber: 2, title: 'Back in the U.S.S.R.'}
songsController.addObject({trackNumber: 1, title: 'Dear Prudence'});
songsController.get('firstObject'); // {trackNumber: 1, title: 'Dear Prudence'}
If you add or remove the properties to sort by or change the sort direction the content sort order will be automatically updated.
songsController.set('sortProperties', ['title']);
songsController.get('firstObject'); // {trackNumber: 2, title: 'Back in the U.S.S.R.'}
songsController.toggleProperty('sortAscending');
songsController.get('firstObject'); // {trackNumber: 4, title: 'Ob-La-Di, Ob-La-Da'}
SortableMixin works by sorting the arrangedContent array, which is the array that arrayProxy displays. Due to the fact that the underlying 'content' array is not changed, that array will not display the sorted list:
songsController.get('content').get('firstObject'); // Returns the unsorted original content
songsController.get('firstObject'); // Returns the sorted content.
Although the sorted content can also be accessed through the arrangedContent property, it is preferable to use the proxied class and not the arrangedContent array directly.
Item Index
Methods
Properties
Methods
addObject
-
object
Required. You must implement this method to apply this mixin.
Attempts to add the passed object to the receiver if the object is not already present in the collection. If the object is present, this method has no effect.
If the passed object is of a type not supported by the receiver, then this method should raise an exception.
Parameters:
-
objectObjectThe object to add to the enumerable.
Returns:
the passed object
addObjects
-
objects
Adds each object in the passed enumerable to the receiver.
Parameters:
-
objectsEmber.Enumerablethe objects to add.
Returns:
receiver
removeObject
-
object
Required. You must implement this method to apply this mixin.
Attempts to remove the passed object from the receiver collection if the object is present in the collection. If the object is not present, this method has no effect.
If the passed object is of a type not supported by the receiver, then this method should raise an exception.
Parameters:
-
objectObjectThe object to remove from the enumerable.
Returns:
the passed object
removeObjects
-
objects
Removes each object in the passed enumerable from the receiver.
Parameters:
-
objectsEmber.Enumerablethe objects to remove
Returns:
receiver
Properties
arrangedContent
Unknown
Overrides the default arrangedContent from arrayProxy in order to sort by sortFunction. Also sets up observers for each sortProperty on each item in the content Array.
sortAscending
Boolean
Specifies the arrangedContent's sort direction.
Sorts the content in ascending order by default. Set to false to
use descending order.
Default: true
sortFunction
Function
The function used to compare two values. You can override this if you want to do custom comparisons. Functions must be of the type expected by Array#sort, i.e. return 0 if the two parameters are equal, return a negative value if the first parameter is smaller than the second or return a positive value otherwise:
function(x,y) { // These are assumed to be integers
if (x === y)
return 0;
return x < y ? -1 : 1;
}
Default: Ember.compare
sortProperties
Array
Specifies which properties dictate the arrangedContent's sort order.
When specifying multiple properties the sorting will use properties
from the sortProperties array prioritized from first to last.