Backgridjs

Filter

When to Use

When you have lots of rows with lots of text, and you just want to quickly get to the row that only contain certain keywords.

Prerequisites

There are no extra dependencies for ServerSideFilter and ClientSideFilter.

For LunrFilter, it has a hard dependency on lunr.js for full-text searching.

ServerSideFilter is suitable if you have a server where you send the search queries to get back a result. The follow example will create a collection that uses Github's excellent API to search for Github users. See here for the valid search terms to use.

          // Creates a Backbone.PageableCollection to talk to Github's API.

          // While you don't have to use Backbone.PageableCollection, it is
          // recommended that you do because of its good support for querying
          // RESTful APIs that support pagination and sorting.

          // See https://github.com/backbone-paginator/backbone.paginator
          var GithubUsers = Backbone.PageableCollection.extend({
            url: "https://api.github.com/search/users",

            state: {
              pageSize: 15,
              sortKey: "joined",
              order: 1
            },

            queryParams: {
              totalPages: null,
              totalRecords: null,
              sortKey: "sort"
            },

            parseState: function (resp, queryParams, state, options) {
              return {totalRecords: resp.total_count};
            },

            parseRecords: function (resp, options) {
              return resp.items;
            }

          });

          var githubUsers = new GithubUsers();

          // ... and then give the collection instance to a grid as usual ...

          // ServerSideFilter delegates the searching to the server by submitting a query.
          var serverSideFilter = new Backgrid.Extension.ServerSideFilter({
            collection: githubUsers,
            // the name of the URL query parameter
            name: "q",
            placeholder: "ex: location:your country" // HTML5 placeholder for the search box
          });

          $("#server-side-filter-example-result .backgrid-container").before(serverSideFilter.render().el);

Tip Github Search User API

ClientSideFilter

          // ClientSideFilter performs a case-insensitive regular
          // expression search on the client side by OR-ing the keywords in
          // the search box together.
          var clientSideFilter = new Backgrid.Extension.ClientSideFilter({
            collection: clientTerritories,
            placeholder: "Search in the browser",
            // The model fields to search for matches
            fields: ['name'],
            // How long to wait after typing has stopped before searching can start
            wait: 150
          });

          $("#client-side-filter-example-result").prepend(clientSideFilter.render().el);

LunrFilter

          // LunrFilter is a specialized ClientSideFilter that uses
          // lunr.js to perform full-text searching on the client side.
          var lunrFilter = new Backgrid.Extension.LunrFilter({
            collection: lunrTerritories,
            placeholder: "Full-text searching",
            // lunr.js field name and boost value
            fields: {
              name: 10
            },
            // lunr.js document key for indexing
            ref: 'id',
            wait: 150
          });

          $("#lunr-filter-example-result").prepend(lunrFilter.render().el);

Pro Tip

ClientSideFilter and LunrFilter won't work unless the collection contains all the data for filtering at the time the filters are initialized. If you are fetching data after the filters were initialized and using Backbone 1.0.0+, you should pass {remove: true} or {reset: true} to Collection#fetch() due to the change to Collection#set() after fetching.