backbone-filtered-collection

Create a filtered version of a backbone collection that stays in sync.

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');

Install with Bower:

bower install backbone-filtered-collection

The component can be used as a Common JS module, an AMD module, or a global.

Install with npm, use with Browserify

> npm install backbone-filtered-collection

and in your code

var FilteredCollection = require('backbone-filtered-collection');

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>

Initialize a new FilteredCollection by passing in the original collection.

var filtered = new FilteredCollection(originalCollection);

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', { afunction(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;
});

Remove a previously applied filter. Accepts a filter name.

filtered.removeFilter('age');

Removes all applied filters. After the collection should be the same as the superset.

filtered.resetFilters();

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();

Given a string, return whether or not that filter is currently applied.

filtered.hasFilter('name');

Return a reference to the original collection.

filtered.superset();

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);

Remove all ties to the superset and stop updating. Will now be garbage collected when it falls out of scope.

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

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

MIT