Backgrid.js

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 how StringCell is defined.

          Backgrid.StringCell = Backgrid.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: Backgrid.StringFormatter

          });

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 backgrid: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 backgrid: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 backgrid:error so that listeners—usually a cell instance—can respond appropriately. When editing is done, a cell editor should fire a Backbone backgrid:edited 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.

Cell

Events

Demo

Configuring Cells

Custom Cell

Custom CellEditor