Backgrid.js

Backgrid.js is a set of components for building semantic and easily stylable data grid widgets.

It offers a simple, intuitive programming interface that makes easy things easy, but hard things possible when dealing with tabular data.

See Examples Download

Advantages

No Hungarian notations.
Solid foundation. Based on Backbone.js.
Semantic and easily stylable. Just style with plain CSS like you would a normal HTML table.
Low learning curve. Works with plain old Backbone models and collections. Easy things are easy, hards things possible.
Highly modular and customizable. Componenets are just simple Backbone View classes, customization is easy if you already know Backbone.
Lightweight. Extra features are separated into extensions, which keeps the bloat away.
Good documentation.
Well tested. Comes with 100s of test cases.

Supported browsers: [1]

Internet Explorer 8+
Chrome 4+
Safari 4+
Firefox 4+
Opera 9+

Backgrid.js depends on 3 libraries to function:

Something like the following will get the Backgrid.js core loaded:

                <link rel="stylesheet" href="lib/backgrid.css" />
                <script src="assets/js/jquery.js"></script>
                <script src="assets/js/underscore.js"></script>
                <script src="assets/js/backbone.js"></script>
                <script src="lib/backgrid.js"></script>

Adjust the paths as needed.

Collection and Model

Before you can display any tabular data in a grid, you must first obtain the data.

At the most basic level, Backgrid pretends that every row is a model object and the whole table is backed by a simple Backbone collection.

Suppose we have a list of territory info objects:

                    var Territory = Backbone.Model.extend({});
                    
                    var Territories = Backbone.Collection.extend({
                      model: Territory,
                      url: "examples/territories.json"
                    });
                    
                    var territories = new Territories();

Grid

The main entry point of the Backgrid package is the Backgrid.Grid class. You can create a default Backgrid by first defining some columns, and then put that list of columns and the collection of data into the Grid constructor like this:

                    var columns = [{
                      name: "id", // The key of the model attribute
                      label: "ID", // The name to display in the header
                      editable: false, // By default every cell in a column is editable, but *ID* shouldn't be
                      // Defines a cell type, and ID is displayed as an integer without the ',' separating 1000s.
                      cell: Backgrid.IntegerCell.extend({
                        orderSeparator: ''
                      })
                    }, {
                      name: "name",
                      label: "Name",
                      // The cell type can be a reference of a Backgrid.Cell subclass, any Backgrid.Cell subclass instances like *id* above, or a string
                      cell: "string" // This is converted to "StringCell" and a corresponding class in the Backgrid package namespace is looked up
                    }, {
                      name: "pop",
                      label: "Population",
                      cell: "integer" // An integer cell is a number cell that displays humanized integers
                    }, {
                      name: "percentage",
                      label: "% of World Population",
                      cell: "number" // A cell type for floating point value, defaults to have a precision 2 decimal numbers
                    }, {
                      name: "date",
                      label: "Date",
                      cell: "date",
                    }, {
                      name: "url",
                      label: "URL",
                      cell: "uri" // Renders the value in an HTML <a> element
                    }];

                    // Fetch some countries from the url
                    territories.fetch().done(function () {
                      // Initialize a new Grid instance
                      var grid = new Backgrid.Grid({
                        columns: columns,
                        collection: territories
                      });

                      // Render the grid and attach the root to your HTML document
                      $("#example-1-result").append(grid.render().$el);
                    });

Result

The list of column definitions Backgrid.Grid expects is simply a list of JSON objects, which you can hardcode into your HTML templates or retrieve from a server when the DOM is ready. Backgrid.js doesn't care where the column definitions come from, as long as you supply the list to the Grid constructor.

As expected, you now have a basic editable data grid displayed. All the columns headers are labeled and sortable by default. ID cells are not editable, and all other cell types have reasonable validation built in. If the table gets too large, you get a scroll bar.

Backgrid.js comes with 10 basic cell types in the core and many others as extensions. Cell types such as Select2Cell and MomentCell give you a much richer editing interface for option lists and datetime values on desktop browsers. In addition, there's a wide range of possibilities with how the data is converted for display and persistence by using formatters or customizing cell classes.

Paginator

If you have a large result set like the above, you'd probably want to paginate your results. This is easily achieved in Backgrid.js.

Backgrid.js comes with a paginator extension which you can load by including the following into your head tag:

                    <link rel="stylesheet" href="lib/extensions/paginator/backgrid-paginator.css" />
                    <script src="assets/js/backbone-pageable.js"></script>
                    <script src="lib/extensions/paginator/backgrid-paginator.js"></script>

To use the paginator, you must first declare your collections to be a Backbone.PageableCollection, which is a simple subclass of the Backbone.js Collection with added pagination behavior.

                    var PageableTerritories = Backbone.PageableCollection.extend({
                      model: Territory,
                      url: "examples/pageable-territories.json",
                      state: {
                        pageSize: 15
                      },
                      mode: "client" // page entirely on the client side
                    });
                    
                    var pageableTerritories = new PageableTerritories();

                    pageableTerritories.fetch().done(function () {

                      var pageableGrid = new Backgrid.Grid({
                        columns: columns,
                        collection: pageableTerritories,
                        footer: Backgrid.Extension.Paginator
                      });
                    
                      $("#example-2-result").append(pageableGrid.render().$el);
                    });

Result

Grid

Backgrid.Grid

How to Use the Grid

As described in the examples above, a basic grid needs only a collection and a list of column definitions.

Manipulating Columns and Rows

It is very easy to insert or remove a row in a grid, you just have to pass a model reference to Grid#insertRow or Grid#removeRow.

                // Inserting rows
                grid.insertRow([{
                  // model 1
                }, {
                  // model 2 ... etc
                }]);

                // Remove rows
                var musketeers = grid.collection.where({ job: "Musketeer" });
                grid.removeRow(musketeers);

Inserting and remove columns is similarly easy. You just need to pass some definitions to Grid#insertColumn or Grid#removeColumn.

                // Insert a few new columns. Make sure your model has these attributes though.
                grid.insertColumn([{

                    name: "selected",
                    label: "",
                    cell: "boolean",
                    sortable: false,
                    headerCell: MySelectAllCell

                  }, {

                    name: "address",
                    label: "Address",
                    cell: "string"

                  }]);

                // Remove a column
                var genderCol = grid.columns.where({ name: "gender" });
                grid.removeColumn(genderCol);

Customization

The various ways of customizing a grid are described in the following sections.

Columns

Column Defaults

Column defaults and required parameters are defined in the Backgrid.Column#initialize method.

Column Definition

A Column is a placeholder for a column definition.

You usually don't need to create an instance of this class yourself, as a collection of column instances will be created for you from a list of column object literals you provide to the Backgrid.js view class constructors.

Internally, columns are stored as a collection in the form of Backgrid.Columns. In addition, all parent views will convert the column definition into a Backgrid.Columns collection and pass a reference to any subviews that require it.

Listening to Column Attribute Changes

Occasionally, you may want to listen to column attribute change events. In that case, you can choose to initialize a Backgrid.Columns collection and listen to events from the individual models.

                var myColumns = new Backgrid.Columns({
                  name: "id", label: "ID", cell: "string"
                }, {
                  // ...
                });

                myColumns.on("change:renderable", function (col, colAttr) {
                  if (!colAttr) {
                    // hide the column
                  }
                });

Cell

Demo

Try them

Name (StringCell)	Age (IntegerCell)	Birthday (DateCell)	Gender (SelectCell)	Alive (BooleanCell)
URL (UriCell)	Email (EmailCell)	Next Delivery Time (DateTimeCell)	His Local Time (TimeCell)	Change in Wallet (NumberCell)

Configuring Cells

While many built-in cells provide reasonable defaults, you may choose to configure them to suit your own needs.

Cell types that you are most likely to configure are the NumberCell, DatetimeCell and SelectCell classes. Once configured, you may use them as the cell attribute values in column definitions.

                var grid = new Backgrid.Grid({

                  columns: [{
                    name: "id",
                    label: "ID",
                    editable: false,
                    // Dynamically defines a new cell type with new defaults.
                    // ID is displayed as an integer without ','s.
                    cell: Backgrid.IntegerCell.extend({
                      orderSeparator: ''
                    })
                  }, {
                    name: "lastaccessed",
                    label: "Last Login Time",
                    editable: false,
                    cell: Backgrid.DatetimeCell.extend({
                      includeMilli: true
                    })
                  }, {
                    name: "gender",
                    label: "Gender",
                    cell: Backgrid.SelectCell.extend({
                      // It's possible to render an option group or use a
                      // function to provide option values too.
                      optionValues: [["Male", "m"], ["Female", "f"]]
                    })
                  }],

                  collection: col
                });

Pro Tip

SelectCell treats all option values as strings by default, if you need to persist a different type of values into your model, you should extend SelectCell to provide your own formatter.

See the JSDoc for the various Cell classes for details on what you can configure using this method.

Custom Cell

If the built-in and extension cell classes are not enough for you, you may choose to create your own cell class and supply it to a column definition.

If your custom cell will still use a <input type="text" /> like the predefined ones for editing, you may choose to subclass Cell or one of the predefined classes and simply define a className and a formatter. In fact, most of the core cell classes are done this way.

                // This is the verbatim Backgrid.StringCell definition

                var StringCell = Backgrid.StringCell = Cell.extend({

                  // Cell default class names are the lower-cased and dasherized
                  // form of the the cell class names by convention.
                  className: "string-cell",

                  formatter: {
                    fromRaw: function (rawData) {
                      return rawData;
                    },
                    toRaw: function (formattedData) {
                      return formattedData;
                    }
                  }
                });

If your cell class will render differently in display mode, you may simply override Cell#render() in your subclass.

Custom CellEditor

Advanced Usage

Some cell types, like the TextCell extension, may only make sense if the editor is rendered in a modal dialog or a form element in a different part of the page. In that case the default InputCellEditor, which renders a <input type="text" />, will not be suitable and a new CellEditor must be defined.

A custom cell editor should subclass CellEditor as it defines a number of required parameters in its initializer and clean up operations that are necessary for most cell editors. When a cell class enters edit mode, a new editor instance is constructed by given it the required parameters, and then a Backbone event edit is fired from the cell instance itself. A custom cell class can act on this event to do anything before the cell editor is rendered.

Once the cell has entered edit mode, a Backbone event editing is fired. A custom cell class can then act on it to do anything after the cell editor has been rendered, e.g. placing the focus inside the editor.

During editing, if an error is encountered (see the formatter protocol below), a cell editor should fire a Backbone event error so that listeners—usually a cell instance—can respond appropriately. When editing is done, a cell editor should fire a Backbone done event. A cell should be listening to this event so it can remove its editor and re-render itsef in display mode.

Truely Advanced Hacking

At the most basic level, Cells and CellEditors are simply Backbone.View classes that are guaranteed to be given a number of parameters when constructed by Row. You can use any Backbone.View as your Cell and CellEditor.

Formatter

Custom Formatters

In Backgrid.js, cell formatters serves the purpose of converting values between JSON value types and strings, and validation. Writing formatters for value conversion and validation is easy as you only have to conform to a very simple protocol.

Any formatters must have the following two methods defined:

                var formatter = {
                  // function (*): string
                  fromRaw: function (rawData) { },
                  // function (string): *|undefined
                  toRaw: function (formattedData) { }
                };

fromRaw() is called by Backgrid.Cell and its subclasses whenever a raw model value needs to be formatted into a humanized form for display.

toRaw() is called by Backgrid.CellEditor and its subclasses whenever a user input string needs to be converted back to a raw JSON value for model persistence.

Validation

In addition to user input conversion, toRaw() also validates the user input during conversion. If the user input is invalid or cannot be converted to a JSON value, toRaw() MUST return undefined instead of throwing an Error.

In addition to using formatters to do simple yes or no validations, if your model class has a validate() method defined, it will also be used for validation after trying with the formatter.

Using Custom Formatters

A custom formatter can be used instead of the cell's default by extending the cell:

                var grid = new Backgrid.Grid({
                  columns: [{
                    name: "url",
                    cell: UriCell.extend({
                      formatter: new MyURLFormatter() // As a cell class attribute
                    })
                  }],
                  collection: col
                });

Header

Understanding the Default Header

Backgrid.js comes with a default header section, a header row and a header cell implementation that renders a sorter if the column is sortable. The text inside the header cells comes from the column definitions. If a label is not defined in a column definition, its name is used as the label instead.

The default header cell implementation supports sorting in ascending or descending order, using the column's natural ordering. The sorter will also allow cycling back to the table's default sorting order, which is sorting by the model server IDs and client IDs.

Customizing the Header

Advanced Usage

You are allow to use a different header cell class on columns. There is no restriction on what a header cell must do. In fact, any Backbone.View class can be used. However, if you wish to modify how the sorter behaves, you must implement the sorting protocol. See the JSDoc for details.

                var SelectAllHeader = Backgrid.HeaderCell.extend({
                  // Implement your "select all" logic here
                });

                var grid = new Backgrid.Grid({

                  columns: [{
                    name: "selected",
                    label: "",
                    sortable: false,
                    cell: "boolean",
                    headerCell: SelectAllHeader
                  }],

                  collection: col
                });

Row

Backgrid.Row

Customizing Row

A row is simply an intermediary view class that constructs the appropriate Cell class instances for rendering the model columns.

If you would like to override how a row is rendered, you may define your own Row subclass and give it to a Body described below.

Body

Backgrid.Body

Using a Custom Row

Advanced Usage

If you have a custom Row class that you would like to use in place of the default Row, you may supply it to the Body constructor as follows:

                var ZebraStrippingRow = Backgrid.Row.extend({
                  // ...
                });

                var grid = new Backgrid.Grid({
                  body: Backgrid.Body.extend({ // <-- Supplies a new Body class created on the spot to the grid.
                    row: ZebraStrippingRow // <-- Tell the new Body class to use ZebraStrippingRow to render rows.
                  }),
                  columns: [{
                    //...
                  }],
                  collection: col
                });

Customizing Body

Advanced Usage

Body is the intermediary view that coordinates between the various parts of the grid. Specifically, the default implementation is responsible for re-rendering the rows when any model is inserted into, removed from, or reordered in the underlying collection. See the JSDoc for details.

Backgrid.Footer

Putting Things at The End of a Table

The default Footer class is an abstract class that only defines a number of required constructor parameters. If you wish to append additional information to the end of a table you must subclass Footer and supply the class to the Grid constructor.

                var CaptionFooter = Backgrid.Footer.extend({

                  render: function () {
                    this.$el.html("<tr><td colspan='6'>Hello World!</td></tr>");
                    return this;
                  }

                });

                var grid = new Backgrid.Grid({
                  columns: [{
                    //...
                  }],
                  collection: col,
                  footer: CaptionFooter // <--
                });

Very often, you'll want to append a paginator to the end of your table if there are too many rows. For this, there's already a paginator extension provided for you.

Extensions

It is not necessary to create an extension project if you simply want to customize or extend some Backgrid.js classes for your own private use; however, if you have one or more Backgrid.js components that add new features to the core, you may consider packaging them up to share with the world.

A Backgrid.js extension is a directory structure that packages the necessary JS, CSS, tests, and document files.

To create an extension, clone the tree into your file system and type:

              $ cd backgrid
              $ make extension

A new extension directory structure should have been created for you under src/extensions. The current implementation of make extension only creates a blank directory filled with a number of blank files for you. You should take a look at other extensions to copy what you need. e.g. Makefile, .gitignore.

Extension Development Guide

The following is a guideline for extension development:

There should be 1 .js file and 1 .css file. If your code base gets too large, consider breaking it into multiple extensions.
There should be 1 .min.js file and 1 .min.css file produced for distribution.
Your Makefile should emulate other extensions as closely as possible. Specifically, you should have a dist rule that will take a DIST_DIR variable from top-level make invocations and copy the output files to the destination directory.
You should use recess to lint your CSS file(s).
You should follow the JS coding style defined here.
Your .gitignore file inside the extension directory should ignore all output files.
You should wrap your JS file in an immediately invoked anonymous function that lists out your dependencies in the parameter list.
Your extension should live under the Backgrid.Extension module.
You should clearly specify your dependencies in the README file if your extension relies on any libraries other than Backgrid.js and its dependencies.
When in doubt, look at the other extensions for clues in organizing your code.

Paginator

Backgrid.Extension.Paginator

Best Used On

Desktop
Mobile

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.

                <link rel="stylesheet" href="lib/extensions/paginator/backgrid-paginator.css" />
                <script src="assets/js/backbone-pageable.js"></script>
                <script src="lib/extensions/paginator/backgrid-paginator.js"></script>

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:

                var Issue = Backbone.Model.extend({});

                // Works exactly like Backbone.Collection.
                var Issues = Backbone.PageableCollection.extend({
                  model: Issue,

                  // Enable infinite paging
                  mode: "infinite",

                  url: "https://api.github.com/repos/documentcloud/backbone/issues?state=closed",

                  // 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",
                    order: "direction",
                    directions: {
                      "-1": "asc",
                      "1": "desc"
                    }
                  }
                });

                var issues = new Issues();

                // If you aren't bootstrapping your data via the constructor, you
                // need to issue a fetch first.
                issues.getFirstPage().done(function () { // Do work only after the fetching is done

Configuring Backgrid.Extention.Paginator

Backgrid.Extension.Paginator supports a few configuration options to adjust to the size of the result set.

                var issueGrid = new Backgrid.Grid({

                  columns: [{
                    name: "number",
                    cell: Backgrid.IntegerCell.extend({ orderSeparator: '' }),
                    editable: false,
                    sortable: false
                  }, {
                    name: "title",
                    cell: "string",
                    sortable: false
                  }, {
                    name: "body",
                    cell: "text", // See the TextCell extension in the next section
                    sortable: false
                  }, {
                    name: "updated_at",
                    cell: "datetime",
                    editable: false,
                    sortable: false
                  }, {
                    name: "closed_at",
                    cell: "datetime",
                    editable: false,
                    sortable: false
                  }],

                  collection: issues,

                  footer: Backgrid.Extension.Paginator.extend({

                    // 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

                    // If you anticipate a small number of pages, you can choose
                    // to disable the rendering of fast forward handles to save
                    // space.
                    hasFastForward: true, // true is the default

                    fastForwardHandleLabels: {
                      prev: "<",
                      next: ">"
                    }
                  })
                });

                $("#example-3-result").append(issueGrid.render().el);
              });

Result

TextCell

Best Used On

Desktop
Mobile

When to Use

TextCell is a string cell type that renders a form with a text area in a modal dialog instead of an <input type="text" /> editor. It is best suited for entering a large body of text.

Prerequisites

TextCell require bootstrap-modal.js to render it's modal dialog.

                <link rel="stylesheet" href="assets/css/bootstrap.css" />
                <!-- include this if you want to use TextCell on mobile browsers -->
                <link rel="stylesheet" href="assets/css/bootstrap-responsive.css" />
                <link rel="stylesheet" href="lib/extensions/text-cell/backgrid-text-cell.css" />
                <script src="assets/js/bootstrap.js"></script>
                <script src="lib/extensions/text-cell/backgrid-text-cell.js"></script>

                var Book = Backbone.Model.extend({});
                var Books = Backbone.Collection.extend({
                  model: Book
                });
                var books = new Books([{ description: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent sed nibh tortor, nec mollis diam. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Morbi venenatis sollicitudin vulputate. Aenean dapibus ultrices odio. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla id molestie erat. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Ut nec erat quis massa gravida facilisis. Ut at nisi ac tortor consectetur ullamcorper id nec purus. Fusce condimentum, lacus vitae convallis condimentum, velit orci auctor dui, et mattis dui est sed purus. Praesent pharetra, metus sit amet lacinia adipiscing, purus dolor sodales orci, non malesuada orci orci sit amet dolor. Sed id nisl et neque sollicitudin condimentum eget in nisl." }]);

                var grid = new Backgrid.Grid({
                  columns: [{
                    name: "description",
                    label: "Description",
                    // You can use Backgrid.Extension.TextCell.extend() too.
                    // See the JSDoc for a list of configurable options.
                    cell: "text"
                  }],

                  collection: books
                });

                $("#example-4-result").append(grid.render().el);

Result

MomentCell

Best Used On

Desktop
Mobile

When to Use

While the core DatetimeCell is light-weight and does the job of formatting IS0-8601 datetime strings fairly well, it may not be well suited when the datatime strings are not in ISO format.

Prerequisites

MomentCell uses Moment.js to render a very powerful datetime cell.

                <link rel="stylesheet" href="lib/extensions/moment-cell/backgrid-moment-cell.css" />
                <script src="assets/js/moment/moment.js"></script>
                <script src="lib/extensions/moment-cell/backgrid-moment-cell.js"></script>
                <!-- Moment.js language files for i18n. -->
                <!-- Moment.js language files must be included after
                     backgrid-moment-cell.js because it changes moment.js' default
                     language -->
                <script src="assets/js/moment/lang/zh-tw.js"></script>

Usage

The default MomentCell acts just like DatetimeCell, so if you have a column with datetime values, the default MomentCell is almost a drop-in replacement, with the only difference being that an offset is always present in the output.

In addition to the ability to read and write ISO-8601 datetime strings. By specifying the model and display formats, MomentCell can convert and validated any datetime values moment.js understands.

Like the core cell types, you can configure MomentCell simply by extending it.

                var Datum = Backbone.Model.extend({});
                
                var Data = Backbone.Collection.extend({
                  model: Datum
                });
                
                var data = new Data([{
                  date: "270/3/1",
                  time: "12:34:56.789",
                  datetime: "1911-10-10T07:00:00"
                }]);

                var grid = new Backgrid.Grid({
                  columns: [{
                    name: "datetime",
                    // You can use a default MomentCell by just writing a name
                    cell: "moment"
                  }, {
                    name: "date",
                    cell: Backgrid.Extension.MomentCell.extend({
                      modelFormat: "YYYY/M/D",
                      // You can specify the locales of the model and display formats too
                      displayLang: "zh-tw",
                      displayFormat: "YYYY-MMM-DD" 
                    })
                  }, {
                    name: "time",
                    cell: Backgrid.Extension.MomentCell.extend({
                      modelInUTC: true,
                      modelFormat: "HH:mm:ss.SSS",
                      displayFormat: "H:m:s",
                      // By default all the values are presumed to be in UTC,
                      // you can convert it to the browser's local time if you
                      // want
                      displayInUTC: false
                    })
                  }],
                  collection: data
                });

                $("#example-5-result").append(grid.render().el);

Result

Select2Cell

Best Used On

Desktop

When to Use

When you have a relatively large number of available options for a column, or want to use a select box with autocomplete capability.

Prerequisites

Select2Cell uses the Select2 jQuery plugin to render its select box.

                <link rel="stylesheet" href="assets/css/select2.css" />
                <link rel="stylesheet" href="lib/extensions/select2-cell/backgrid-select2-cell.css" />
                <script src="assets/js/select2.js"></script>
                <script src="lib/extensions/select2-cell/backgrid-select2-cell.js"></script>

Usage

Select2Cell is a very simple extension of the default SelectCell. You can configure individual instances by supplying a select2Options object hash during extension, in addition to the options SelectCell supports.

                
                var data = new Backbone.Collection([{number: 5}]);

                // Just like SelectCell, Select2Cell supports option lists and groups
                var numbers = [{name: 10, values: [
                  [1, 1], [2, 2], [3, 3], [4, 4], [5, 5],
                  [6, 6], [7, 7], [8, 8], [9, 9], [10, 10]
                ]}];

                var grid = new Backgrid.Grid({
                  columns: [{
                    name: "number",
                    cell: Backgrid.Extension.Select2Cell.extend({
                      select2Options: {
                        // any options specific to `select2` goes here
                      },
                      optionValues: numbers
                    })
                  }],
                  collection: data
                });

                $("#example-6-result").append(grid.render().el);

Result

LatLngCell

Coming soon...

Out of the box, Backgrid.js generates simple semantic HTML table elements that you can style with pure CSS. This section is only going to briefly describe some of the more important classes, and things that you should be aware of when styling.

.backgrid-container

This is the class that you should put into any container element that will hold the generated table. By default, it has a fixed maximum height and 100% width with no borders and paddings. It also serves as a positioned element so if you need to absolutely position any elements inside your custom table element classes, you can position them against this container.

                    .backgrid-container {
                      position: relative;
                      display: block;
                      width: 100%;
                      height: 494px;
                      padding: 0;
                      overflow: auto;
                      border: 0;
                    }

.backgrid

This is the class that will be applied to every Backgrid.js generated table. All other Backgrid.js default styles on table elements will only apply to descendents of tables of this class.

                    /* Say you want to give some shiny gradient background colors
                       to your table header */
                    .backgrid th {
                      background-color: linear-gradient(top, #2F2727, #1a82f7);
                    }

Although usually unnecessary, if you want to completely remove all Backgrid.js styles, you can supply a className attribute to the Backgrid.Grid constructor:

                    var grid = new Backgrid.Grid({
                      className: "my-awesome-css-animated-grid",
                      ...
                    });

.backgrid .*-cell

Every cell class Backgrid.js defines has a CSS class applied to them of the same, but dasherized name. The default styles apply a text-align: left to text cells and text-align: right to numeric and datetime cells. All cell editor that uses the <input> element is absolutely positioned against the table cell.

See the relevant cell classes for details.

How do I validate user input?

See Formatter.

Why doesn't Backgrid.js support AMD (or NPM)?

The same question can be asked for volo, bower, ender, browserify and many other competing solutions. The number one reason Backgrid.js does not support AMD is because of the barrier it presents to writing extensions that require third-party libraries that don't support AMD. In addition to this, Underscore.js and Backbone.js also do not support AMD at this time.

The problem with supporting any package manager is that Backgrid.js is a highly modular project, and that deciding to use any package manager presupposes all its submodules and dependency is compatible with such a package manager and its importing mechanism. The Javascript ecosystem has gotten so diverse now that there is still not yet a clear packaging winner that everybody uses and works well under most situations, it is also not clear that ES Harmony's module system will be backward compatible with AMD.

Having said that, Backgrid.js doesn't do anything to prevent you from adding support to your favorite package manager. You are encouraged to fork and maintain your own Backgrid.js packages.

You are also more than welcomed to convince me on Github as you may probably know more than I do about packaging Javascripts.

Where do I go to ask questions?

Ask on the Google Group mailing list or go to Stackoverflow with the tag backgrid where either I or fellow users can help you.

Does Backgrid.js support adaptive scrolling?

Some data grid widgets out there support a technique called adaptive scrolling, meaning the DOM elements will be swapped out of a viewport and new ones appended as the models are loaded from the server, thus keeping the memory more or less constant while providing an illusion to end-users that there's no limit to the number of rows the data grid can handle.

Backgrid.js has something better and achieves the same effect with much cleaner code - paginator extension, which uses backbone-pageable. The paginator supports both paging on the server-side, or preloading all the models and paging purely through the browser. Paginated Backgrid.Grid instances only render one page of DOM nodes at a time to save memory and keep your web page responsive.

Does Backgrid.js support function aggregates?

No, because it is not the goal of this project to produce a full-fledged web-based spreadsheet. However, doing aggregation is trivial using Underscore.js methods

                // sum all the values of a column
                var sum = collection.reduce(function (accum, num) {
                  return accum + num;
                });

Does Backgrid.js support multi-user editing?

Again, it is out of the scope of this project as this functionality requires a broker to arbitrage between users and is mostly found in web-based online spreadsheet products.

Does Backgrid.js support feature (X)?

If the feature you have in mind isn't found here in this Backgrid.js version, it could either be in the works or under consideration.

See the list of tasks and enhancements.

How to build Backgrid.js?

See Building.

How do I contribute?

See Contributing.

Changelog

0.1: Initial Release

Backgrid.js Javascript and CSS source code licensed under the MIT license.

Documentation licensed under GPLv3.

Backgrid.js

Features

Advantages

Supported browsers: [1]

Getting Started

Examples

Collection and Model

Grid

Result

Paginator

Result

API Reference

Grid

How to Use the Grid

Manipulating Columns and Rows

Customization

Columns

Column Defaults

Column Definition

Listening to Column Attribute Changes

Cell

Demo

Configuring Cells

Custom Cell

Custom CellEditor

Formatter

Custom Formatters

Validation

Using Custom Formatters

Header

Understanding the Default Header

Customizing the Header

Row

Customizing Row

Body

Using a Custom Row

Customizing Body

Footer

Putting Things at The End of a Table

Extensions

Extension Development Guide

Paginator

Best Used On

When to Use

Prerequisites

Backbone.PageableCollection

Configuring Backgrid.Extention.Paginator

Result

TextCell

Best Used On

When to Use

Prerequisites

Result

MomentCell

Best Used On

When to Use

Prerequisites

Usage

Result

Select2Cell

Best Used On

When to Use

Prerequisites

Usage

Result

LatLngCell

Styling

.backgrid-container

.backgrid

.backgrid .*-cell

Frequently Asked Questions

How do I validate user input?

Why doesn't Backgrid.js support AMD (or NPM)?

Where do I go to ask questions?

Does Backgrid.js support adaptive scrolling?

Does Backgrid.js support function aggregates?

Does Backgrid.js support multi-user editing?

Does Backgrid.js support feature (X)?

How to build Backgrid.js?

How do I contribute?