ampersand-subcollection
v2.0.3
Published
Filterable, sortable, proxy of a collection that behaves like a collection.
Downloads
4,510
Readme
ampersand-subcollection
#notice
This module is deprecated and further non-security updates will not be done on it. The functionality here has been broken into two modules:
ampersand-filtered-subcollection ampersand-paginagted-subcollection
Please use them instead for new projects, and consider moving to one or both of them in your existing ones.
#overview
Filtered subset of a collection that emits events like a collection.
Often for one part of an app you want a whole collection of models, but for another you want some sort of filtered subcollection. That's what this is for. It gives you a "pseudo collection" that behaves much like a full collections, but really is a subset.
Part of the Ampersand.js toolkit for building clientside applications.
browser support
install
npm install ampersand-subcollection
example
var WidgetCollection = require('./mycollection');
var SubCollection = require('ampersand-subcollection');
var widgets = new WidgetCollection();
widgets.fetch();
// this will create a collection-like object
// that will only include models that match
// the `where` filters.
// It will be sorted by the comparator
// independent of base collection order
var favoriteWidgets = new SubCollection(widgets, {
where: {
awesome: true
},
comparator: function (model) {
return model.rating;
}
});
API reference
new SubCollection(collection, [config])
collection
{Collection} An instance of an ampersand-collection or Backbone.Collection that contains our full set of models.config
{Object} [optional] The config object that specifies whether or not a model in the base should be considered part of this subcollection.where
{Object} [optional] Object where each key is a property name of the model and the value is what you want that property to be in order for it to be included. Often used for boolean properties.filter
{Function} [optional] If you need more control than what you get fromwhere
you can use a filter function to determine if the model should be included. It will get called with a model and you simply returntrue
orfalse
.filters
{Array} [optional] If you for some reason want to pass in multiple filter functions you can do so. This can be useful in cases where you keep a reference to one that you may remove later without wanting to remove all your filtering rules. But, most of the time you would just do usefilter
and do all your logic in that one function.watched
{Array} [optional] This is an array of property names to watch for changes to in the base collection. This happens automatically if you usewhere
. If your comparator and filters are all functions, then you will need to manually specify the relevant properties to watch so that re-filtering and re-sorting will occur when needed.comparator
{Function || String} [optional] If you want to determine sort order separate from the base collection provide this argument. If you pass a string it should be the name of the property that should be used to sort by, and it will be watched for changes automatically. If you pass a function, it will be passed the model and should return the value from the model that should be used to sort. If you pass a function that names two incoming arguments it will be used as a nativeArray.prototype.sort
, where you get passed two models and return a1
,0
,-1
to specify how they compare.limit
{Number} [optional] If specified will limit the number of matched models to this maximum number. This is useful for things like pagination.offset
{Number} [optional] Similar tolimit
setting anoffset
will specify what number to start at. So you can think oflimit
as number of results per page, andoffset
being the index of the start of the current page of results.
.configure(config, [reset])
Config can get used to update subcollection config post-init.
config
{Object} Same config object as what you pass to init.reset
{Boolean} Default:false
. Whether or not to remove all previous filter config options. If you specify{where: {read: true}}
in the init and then do.configure({where: {from: 'steve'}})
without passingtrue
the collection will contain only read items from steve. The filters are combined by default. Whenreset
istrue
, thecomparator
is also reset.
.reset()
Convenience method that calls .configure({}, true)
.addFilter(filterFunction)
filterFunction
{Function} A filter function as described above. Gets called with the model, you returntrue
orfalse
.
.removeFilter(filterFunction)
filterFunction
{Function} If you have a reference in your code to the filter function you added, you can remove it by callingremoveFilter
.
.clearFilters()
Removes filter functions, watches, limit, and offset. After calling this, the subcollection should have the same models as your base collection.
The only thing that does not get cleared is your comparator
method or property if you have one.
.swapFilters(newFilters, [oldFilters])
newFilters
{Function} or array of filter functions to be applied to the collection.oldFilters
{Function} or array of filter functions to be removed from the collection. IfoldFilters
is undefined, then it is assumed to be the set of currently active filters.
Replaces a set of existing filter functions with a set of new filters, and does not apply the results of the new filter combination until all have been added and removed.
For example:
.swapFilters(newFilter, []) // Same as .addFilter(newFilter)
.swapFilters([], oldFilter) // Same as .removeFilter(oldFilter)
.at(index)
index
{Number} returns model as specified index in the subcollection.
.length
The subcollection maintains a read-only length property that simply proxies to the array length of the models it contains.
.filtered
The array of filtered models before offset
and/or limit
is applied.
.models
The array of filtered models with offset
and/or limit
applied (if set).
all the underscore methods
Since we're already depending on underscore for much of the functionality in this module, we also mixin underscore methods into the subcollection in the same way that Backbone does for collections.
This means you can just call collection.each()
or collection.find()
to find/filter/iterate the models in the subcollection. You can see which underscore methods are included by referencing ampersand-collection-underscore-mixin.
SubCollection.extend(mixins...)
Subcollection attaches extend
to the constructor so if you want to add custom methods to your subcollection constructor, it's easy:
var SubCollection = require('ampersand-subcollection');
// this exports a new constructor that includes
// the methods you passed on the prototype while
// maintaining the inheritance chain for instanceof
// checks.
module.exports = SubCollection.extend({
myMethod: function () { ... },
myOtherMethod: function () { ... }
});
This is done by using: ampersand-class-extend
changelog
- 1.4.5 fixed bug where passing the
reset
option toconfigure()
wasn't working. - 2.0.0
- add
reset()
convenience method - auto-watch string comparator
- add
.filtered
property containing all filtered models before applyingoffset
andlimit
- add better documentation about manual watches
- fixed bug where
configure()
withreset
option did not reset comparator - fixed bug where
destroy
,invalid
, andsync
events were not bubbling due to missing arg to_.contains
- add
credits
If you like this follow @HenrikJoreteg on twitter.
license
MIT