Neil Patrick's Mansion

    backbone-filtered-collection

    0.4.0 • Public • Published

    backbone-filtered-collection

    Build Status

    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

    Install

    npm i backbone-filtered-collection

    DownloadsWeekly Downloads

    948

    Version

    0.4.0

    License

    MIT

    Last publish

    Collaborators

    • jmorrell