yobo-filtered-collection
v0.4.1
Published
Create a filtered version of a backbone collection that stays in sync.
Downloads
687
Maintainers
Readme
backbone-filtered-collection
Create a read-only filtered version of a backbone collection that stays in sync.
var superset = new Backbone.Collection(/* ... */);
var filtered = new FilteredCollection(superset);
// Filtered will contain only models where model.get('foo') === "bar"
filtered.filterBy({ foo: "bar" });
// A new model to the superset will automatically show up in the filtered
// collection, firing an "add" event
superset.add({ foo: "bar", baz: "qux" });
// Also supports named multiple named filters and arbitrary functions
filtered.filterBy('age-range', function(model) {
return model.get('age') > 17 && model.get('age') < 70;
});
// Remove a filter and the filtered collection will update
filtered.removeFilter('age-range');
Installation
Usage with Bower
Install with Bower:
bower install backbone-filtered-collection
The component can be used as a Common JS module, an AMD module, or a global.
Usage with Browserify
Install with npm, use with Browserify
> npm install backbone-filtered-collection
and in your code
var FilteredCollection = require('backbone-filtered-collection');
Usage as browser global
You can include backbone-filtered-collection.js
directly in a script tag. Make
sure that it is loaded after underscore and backbone. It's exported as FilteredCollection
on the global object.
<script src="underscore.js"></script>
<script src="backbone.js"></script>
<script src="backbone-filtered-collection.js"></script>
Methods
new FilteredCollection
Initialize a new FilteredCollection by passing in the original collection.
var filtered = new FilteredCollection(originalCollection);
filtered.filterBy([filterName], filter)
Apply a new filter to the set. Takes an optional filter name.
Can be a simple object that defines required key / value pairs.
filtered.filterBy('foo and bar filter', { foo: 2, bar: 3 });
Or the you can pass a filter function instead of a value.
filtered.filterBy('a > 2', { a: function(val) {
return val > 2;
}});
Or you can use an arbitrary filter function on the model itself.
filtered.filterBy('age', function(model) {
return model.get('age') > 10 && model.get('age') < 40;
});
filtered.removeFilter(filterName)
Remove a previously applied filter. Accepts a filter name.
filtered.removeFilter('age');
filtered.resetFilters()
Removes all applied filters. After the collection should be the same as the superset.
filtered.resetFilters();
filtered.getFilters()
Returns a list of the names of applied filters.
Note: If added a filter with no name, it will show up here as __default
.
filtered.getFilters();
filtered.hasFilter()
Given a string, return whether or not that filter is currently applied.
filtered.hasFilter('name');
filtered.superset()
Return a reference to the original collection.
filtered.superset();
filtered.refilter()
If the collections get out of sync (ex: change events have been suppressed) force the collection to refilter all of the models.
filtered.refilter();
Can also be forced to run on one model in particular.
filtered.refilter(model);
filtered.destroy()
Remove all ties to the superset and stop updating. Will now be garbage collected when it falls out of scope.
Events
add
, remove
, change
, reset
should fire as you expect.
filtered:add
- Fired when a new filter is added. Passes the filter name.
filtered:remove
- Fired with a filter is removed. Passes the filter name.
filtered:reset
- Fired when all of the filters are removed.
`filtered:destroy' - Fired when the proxy is destroyed
Testing
Install Node (comes with npm) and Bower.
From the repo root, install the project's development dependencies:
npm install
bower install
Testing relies on the Karma test-runner. If you'd like to use Karma to automatically watch and re-run the test file during development, it's easiest to globally install Karma and run it from the CLI.
npm install -g karma
karma start
To run the tests in Firefox, just once, as CI would:
npm test
License
MIT