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="https://github.com/jmorrell/backbone-filtered-collection/raw/master/underscore.js"></script>
<script src="https://github.com/jmorrell/backbone-filtered-collection/raw/master/backbone.js"></script>
<script src="https://github.com/jmorrell/backbone-filtered-collection/raw/master/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