Backbone.Datagrid

Backbone.Datagrid is a powerful component, based on Backbone.View, that displays your Backbone collections in a dynamic datagrid table. It is highly customizable and configurable with sensible defaults.

You can refer to the project's website for a nice HTML documentation.

Download

The raw sources can be navigated on GitHub. The distributed sources can be found in the dist/ directory or downloaded directly via one of the following links:

• Production minified version: backbone.datagrid.min.js (v0.3.2).
• Development version: backbone.datagrid.js (v0.3.2).

Getting started

Usage

Create a new datagrid with your collection and options, render it and attach the resulting element to your document:

var myCollection = new MyCollection();
var datagrid = new Backbone.Datagrid({
  collection: myCollection
});
$('#datagrid').html(datagrid.el);

Examples

You will find all the examples listed on this page. Their sources are available in the examples directory of the repository.

• Solar: a simple and complete example with an in memory collection of planets from the Solar System.
  • Live version
  • Sources
• GitHub: an example with a collection connected to GitHub's REST API.
  • Live version
  • Sources

Description

Each component composing the datagrid really are Backbone views. Here is a description of these different components. You'll also find for each component (or view), the events that will cause a rendering of the view.

                  Datagrid
 ____________________/\____________________
/                                          \

+----------+----------+----------+----------+  ˥
| Column 1 | Column 2 | Column 3 | Column 4 |   } Header
ǂ==========ǂ==========ǂ==========ǂ==========ǂ  ˩
| Val 1-1  | Val 1-2  | Val 1-3  | Val 1-4  |
+----------+----------+----------+----------+  ˥
| Val 2-1  | Val 2-2  | Val 2-3  | Val 2-4  |   } Row
+----------+---------\+----------+----------+  ˩
| Val 3-1  | Val 3-2  \ Val 3-3  | Val 3-4  |
+----------+----------+\--------\+----------+
| Val 4-1  | Val 4-2  | \al 4-3  \ Val 4-4  |
+----------+----------+--\-------+\---------+
                          \___  ___\
                              \/
                            2 Cells

          +---+---+---+---+---+---+  ˥
          | « | 1 | 2 | 3 | 4 | » |   } Pagination
          +---+---+---+---+---+---+  ˩

Datagrid

The backbone.datagrid entry point. A Backbone.View that will be responsible for the entire datagrid management and rendering. It uses the collection passed to the constructor as its data source. The Datagrid view takes care of creating the table HTML element and each of the components described below.

Event bindings:

• collection#reset will cause a rendering of the whole datagrid.

Header

A Backbone.View for the datagrid's header which is going to render the thead HTML element. It is also responsible for creating a Cell for each column's header.

Row

A Backbone.View for each row of the datagrid. The Row is responsible for rendering a row in the table, that is to say a tr HTML element, and for creating a Cell for each column of the datagrid. The Row uses an entry of the collection: a model.

Event bindings:

• model#change will cause a rendering of the row.

Cell

A Backbone.View for each cell in a Row. One Cell is responsible for rendering a td (or th for a header) HTML element.

There are specialized cells views extending the base Cell and that allows custom renderings that suit your needs:

• Cell
  • CallbackCell
    • TemplateCell
      • UnderscoreTemplateCell (not available yet)
      • HandlebarsTemplateCell (not available yet)
  • ActionCell

Datagrid options

collection

The Backbone.Collection that is going to be managed by the datagrid.

inMemory

If the collection should be manipulated in memory for pagination and sorting. Otherwise use REST requests.

paginated

Whether or not the datagrid should be paginated.

tableClassName

The class attribute for the generated table. Will override tableAttrs.className.

rowClassName

The class attribute for each datagrid's row: tr tags. Can be a simple string with class names space-separated or a computed string by passing a callback function. The callback function will be called with the model associated to the current row. Will override className attribute that may be returned by rowAttrs.

emptyMessage

A nice message to display when the datagrid is empty. Defaults to <p>No results found.</p>.

tableAttrs (object)

If you provide an object in tableAttrs, they will be used as html attributes of the generated table element.

rowAttrs (function)

Unlike tableAttrs, rowAttr may be a function invoked to generate html attributes of the generated tr elements. It's invoked during rendering on each row, with the Corresponding backbone model as first parameter. It must return an object.

var datagrid = new Datagrid({
  collection: collection,
  rowAttrs: function(model) {
    return {'data-id': model.cid, disabled: true};
  }
  ...

columns

The columns definitions, see the dedicated section below.

Columns definitions

You can customize the datagrid with columns definition. It is an array of definitions, one for each column you want to see in the datagrid. If no definition is passed to the datagrid, a default column definition is going to be created for you for each property of the model managed by the collection you passed to the datagrid.

A column definition can be a string or an object. If a string is passed, a default column definition will be generated with the specified string used as the column's property.

Column definition

property (string)

The model's property that is going to be displayed in the column. Can be omitted if the column describe a combination of different properties of the model: please refer to custom views below.

title (string)

The title of the column which will be displayed in the table header. If not defined, the column's property will be used for generating a nicely formated title, here are some examples:

• name => Name
• events_url => Events Url
• issue_events_url => Issue Events Url

sortable (boolean)

Whether or not the column is sortable. Default to false.

sortBy (string)

The column which will be used for sorting, see dedicated sorting section below for more details.

comparator (function)

If the column is sortable, a comparator function that is going to be used to sort the datagrid by the column. See the dedicated sorting section below for more informations.

cellClassName (string|callback)

The class name of the cell (td or th). It can be a string or a callback which will be passed the model related to the current row. Will override className attribute that may be returned by cellAttrs.

cellAttrs (function)

May be a function invoked to generate html attributes of the generated td elements. It's invoked during rendering on each cell, with the row backbone model as first parameter. It must return an object.

var datagrid = new Datagrid({
  collection: collection,
  columns: [{
    property: 'foo',
    cellAttrs: function(model) {
      return {'data-id': model.cid, disabled: true};
    }
    ...

view (string|callback|object)

The CellView that's gonna be used for rendering the column's cell associated to the current row.

If not defined, the model's attribute corresponding to column.property.

You can pass an Underscore template as a string, it will be compiled and executed with the model.toJSON() as context.

You can also pass a callback function. It will be called with the current row's model (the Backbone full model) and the return value will be displayed in the cell.

You can finally pass an object to use one of the specific views provided or a custom view. This object must have a type property which refers to view's type that gonna be used for the Cell. The other properties are gonna be passed to the constructor function of the view.

{
  title: 'Edit',
  view: {
    type: Backbone.Datagrid.ActionCell,
    label: 'Edit',
    actionClassName: 'btn btn-primary',
    action: function(planet) {
      alert('Would edit ' + planet.get('name') + '!');
      return false;
    }
  }
}

Pagination

By default, pagination controls are displayed for a paginated datagrid. But an API is also available to manually control pagination. Each of the following functions causes a datagrid rendering:

Pager

The Pager is an object extending Backbone.Model which manages the state of the pagination for the datagrid.

datagrid.page(page)

Go to the specified page. Delegates to:

datagrid.pager.page(page);

datagrid.perPage(perPage)