backbone-filtered-collection
Create a read-only filtered version of a backbone collection that stays in sync.
var superset = /* ... */;var filtered = superset; // Filtered will contain only models where model.get('foo') === "bar"filtered; // A new model to the superset will automatically show up in the filtered// collection, firing an "add" eventsuperset; // Also supports named multiple named filters and arbitrary functionsfiltered; // Remove a filter and the filtered collection will updatefiltered;
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 = ;
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 = 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;
Or the you can pass a filter function instead of a value.
filtered;
Or you can use an arbitrary filter function on the model itself.
filtered;
filtered.removeFilter(filterName)
Remove a previously applied filter. Accepts a filter name.
filtered;
filtered.resetFilters()
Removes all applied filters. After the collection should be the same as the superset.
filtered;
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;
filtered.hasFilter()
Given a string, return whether or not that filter is currently applied.
filtered;
filtered.superset()
Return a reference to the original collection.
filtered;
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;
Can also be forced to run on one model in particular.
filtered;
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