Backgridjs

Paginator

When to Use

When you have more data than your grid can fit, you can use Paginator to break the display of your data into pages.

Prerequisites

Backgrid.Extension.Paginator needs a Backbone.Collection subclass that supports pagination. Luckily, there is already one available specially written for this purpose - Backbone.PageableCollection.

Backbone.PageableCollection is a strict superset of the vanilla Backbone.Collection with additional pagination and sorting functionality. If you like, you can use Backbone.PageableCollection throughout your application and it will work exactly the same as Backbone.Collection.

Backbone.PageableCollection

Out of the box, Backbone.PageableCollection works with RESTful APIs that accept Ruby's will_paginate pagination query parameters but you are able to configure the query string mapping anyway you like. The following example works with Github's API:

          // Works exactly like Backbone.Collection.
          var Issues = Backbone.PageableCollection.extend({

            url: "https://api.github.com/search/issues",

            // Initial pagination states
            state: {
              pageSize: 15,
              sortKey: "updated",
              order: 1
            },

            // You can remap the query parameters from `state` keys from
            // the default to those your server supports
            queryParams: {
              totalPages: null,
              totalRecords: null,
              sortKey: "sort",
              q: "state:closed repo:jashkenas/backbone"
            },

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

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

          });

          var issues = new Issues();

Configuring Backgrid.Extension.Paginator

Backgrid.Extension.Paginator supports a number of configuration options to adjust to the size of the result set. You can control the default window size, how many pages to slide an whether the grid should go back to the first page after sorting.

          var issueGrid = new Backgrid.Grid({

            columns: [{
              name: "id",
              cell: Backgrid.IntegerCell.extend({ orderSeparator: '' }),
              sortable: false,
              editable: false
            }, {
              name: "title",
              cell: "string",
              sortable: false,
              editable: false
            }, {
              name: "body",
              cell: "text", // See the TextCell extension
              sortable: false
            }, {
              name: "comments",
              cell: "integer"
            }],

            collection: issues
          });

          var $paginatorExample = $("#paginator-example-result");
          $paginatorExample.append(issueGrid.render().el);

          var paginator = new Backgrid.Extension.Paginator({

            // If you anticipate a large number of pages, you can adjust
            // the number of page handles to show. The sliding window
            // will automatically show the next set of page handles when
            // you click next at the end of a window.
            windowSize: 20, // Default is 10

            // Used to multiple windowSize to yield a number of pages to slide,
            // in the case the number is 5
            slideScale: 0.25, // Default is 0.5

            // Whether sorting should go back to the first page
            goBackFirstOnSort: false, // Default is true

            collection: issues
          });

          $paginatorExample.append(paginator.render().el);

          issues.fetch({reset: true});

Result

Advanced Usage

You can control how the control and page handles are rendered, you can even control how the sliding window algorithm works. Please refer to the JSDoc for details.