index.html | searchcode

/index.html

Large files files are truncated, but you can click here to view the full file

<!doctype html>
<!--
  backgrid
  http://github.com/wyuenho/backgrid

  Copyright (c) 2013 Jimmy Yuen Ho Wong and contributors
  Licensed under the MIT @license.
 -->
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge;chrome=1" />
    <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no" />
    <meta name="keywords" content="backgrid,backgrid.js,backbone,backbone.js,datagrid,grid,paginator,javascript" />
    <meta name="description" content="A powerful widget set for building data grids with Backbone.js" />

    <title>Backgrid.js - A powerful widget set for building data grids with Backbone.js</title>

    <link rel="canonical" href="http://backgridjs.com" />

    <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/2.2.2/css/bootstrap.min.css" />
    <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/2.2.2/css/bootstrap-responsive.min.css" />
    <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/select2/3.3.2/select2.min.css" />
    <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/codemirror/2.36.0/codemirror.min.css" />
    <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/codemirror/2.36.0/ambiance.min.css" />
    <link rel="stylesheet" href="lib/backgrid.min.css" />
    <link rel="stylesheet" href="lib/extensions/paginator/backgrid-paginator.min.css" />
    <link rel="stylesheet" href="lib/extensions/text-cell/backgrid-text-cell.min.css" />
    <link rel="stylesheet" href="lib/extensions/moment-cell/backgrid-moment-cell.min.css" />
    <link rel="stylesheet" href="lib/extensions/select2-cell/backgrid-select2-cell.min.css" />
    <link rel="stylesheet" href="lib/extensions/select-all/backgrid-select-all.min.css" />
    <link rel="stylesheet" href="lib/extensions/filter/backgrid-filter.min.css" />
    <link rel="stylesheet" href="assets/css/doc.css" />
    <!--[if lt IE 9]>
        <script src="//cdnjs.cloudflare.com/ajax/libs/modernizr/2.6.2/modernizr.min.js"></script>
        <![endif]-->
  </head>
  <body>
    <div id="main">
      <header>
        <div class="navbar navbar-fixed-top">
          <div class="navbar-inner">
            <div class="container">
              <a href="."
                 class="brand" title="A powerful widget set for building data grids with Backbone.js">Backgrid.js</a>
              <a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse">
                <span class="icon-bar"></span>
                <span class="icon-bar"></span>
                <span class="icon-bar"></span>
              </a>
              <div class="nav-collapse collapse">
                <ul class="nav nav-pills">
                  <li class="dropdown">
                    <a class="dropdown-toggle" data-toggle="dropdown" data-target="#" href="#">
                      Introduction
                      <b class="caret"></b>
                    </a>
                    <ul class="dropdown-menu">
                      <li><a href="#features">Features</a></li>
                      <li><a href="#getting-started">Getting Started</a></li>
                      <li><a href="#examples">Examples</a></li>
                    </ul>
                  </li>
                  <li class="dropdown">
                    <a class="dropdown-toggle" data-toggle="dropdown" data-target="#" href="#">
                      API Reference
                      <b class="caret"></b>
                    </a>
                    <ul class="dropdown-menu">
                      <li><a href="#api-grid">Grid</a></li>
                      <li><a href="#api-column">Column</a></li>
                      <li><a href="#api-cell">Cell</a></li>
                      <li><a href="#api-formatter">Formatter</a></li>
                      <li><a href="#api-header">Header</a></li>
                      <li><a href="#api-row">Row</a></li>
                      <li><a href="#api-body">Body</a></li>
                      <li><a href="#api-footer">Footer</a></li>
                      <li class="divider"></li>
                      <li><a href="#extensions"><strong class="muted">Extensions</strong></a></li>
                      <li class="divider"></li>
                      <li><a href="#api-select-all">SelectAll</a></li>
                      <li><a href="#api-paginator">Paginator</a></li>
                      <li><a href="#api-filter">Filter</a></li>
                      <li><a href="#api-text-cell">TextCell</a></li>
                      <li><a href="#api-moment-cell">MomentCell</a></li>
                      <li><a href="#api-select2-cell">Select2Cell</a></li>
                    </ul>
                  </li>
                  <li class="dropdown">
                    <a class="dropdown-toggle" data-toggle="dropdown" data-target="#" href="#">
                      More Info
                      <b class="caret"></b>
                    </a>
                    <ul class="dropdown-menu">
                      <li><a href="#styling">Styling</a></li>
                      <li class="divider"></li>
                      <li><a href="#faq">FAQ</a></li>
                      <li><a href="https://github.com/wyuenho/backgrid/blob/master/CHANGELOG.md" target="_blank">Change Log</a></li>
                      <li><a href="#license">License</a></li>
                    </ul>
                  </li>
                  <li id="social-media">
                    <a href="https://twitter.com/share" class="twitter-share-button" data-url="http://backgridjs.com" data-counturl="wyuenho.github.com/backgrid" data-via="wong_jim" data-hashtags="backgridjs,backbone_js">Tweet</a>
                    <div class="g-plusone" data-size="medium"></div>
                    <iframe src="http://ghbtns.com/github-btn.html?user=wyuenho&repo=backgrid&type=watch&count=true"
                            allowtransparency="true" frameborder="0" scrolling="0" width="110" height="20"></iframe>
                    <a href="https://coderwall.com/wyuenho"><img alt="Endorse wyuenho on Coderwall" src="http://api.coderwall.com/wyuenho/endorsecount.png" /></a>
                    <iframe allowtransparency="true" frameborder="0" scrolling="no"
                            style="border: 0; margin: 0 0 0 15px; padding: 0;"
                            src="https://www.gittip.com/wyuenho/widget.html" width="48pt" height="22pt"></iframe>
                  </li>
                </ul>
              </div>
            </div>
            <a class="visible-desktop" href="https://github.com/wyuenho/backgrid">
              <img style="position: absolute; top: 0; right: 0; border: 0;" src="assets/img/forkme_right_gray_6d6d6d.png" alt="Fork me on GitHub">
            </a>
          </div>
        </div>
      </header>
      <div class="container">
        <section class="hero-unit">
          <h1>Backgrid.js</h1>
          <p class="lead">
            Backgrid.js is a set of components for
            building <strong>semantic</strong> and <strong>easily
            stylable</strong> <strong>data grid</strong> widgets.</p>
          <p class="lead">It offers a simple, intuitive
              programming interface that makes easy things easy, but <em>hard things possible</em>
              when dealing with tabular data.</p>
          <p>
            <div class="btn-group">
              <a class="btn btn-large btn-success" href="#examples">See Examples</a>
              <a class="btn btn-large btn-primary hidden-phone hidden-tablet"
                 href="https://github.com/wyuenho/backgrid/tags">Download v0.2.6</a>
              <a class="btn btn-large btn-info"
                 href="https://github.com/wyuenho/backgrid/blob/0.2.6/CHANGELOG.md">What's new?</a>
            </div>
          </p>
        </section>
        <div id="features">
          <div class="page-header">
            <h1>Features</h1>
            <p>The goal of Backgrid.js is to produce a set of core Backbone UI
              elements that offer you all the basic displaying, sorting and
              editing functionalities you&apos;d expect, and to create an
              elegant API that makes extending Backgrid.js with extra
              functionalities easy.</p>
          </div>
          <div class="row-fluid">
            <div class="span6">
              <h2>Advantages</h2>
              <ul>
                <li>No Hungarian notations.</li>
                <li>Solid foundation. Based
                  on <a href="http://backbonejs.org">Backbone.js</a>.</li>
                <li>Semantic and <a href="#styling">easily stylable</a>. Just
                  style with plain CSS like you would a normal HTML table.</li>
                <li>Low learning curve. Works with plain old Backbone models and
                  collections. Easy things are easy, hards things possible.</li>
                <li>Highly modular and customizable. Componenets are just simple
                  Backbone View classes, customization is easy if you already
                  know Backbone.</li>
                <li>Lightweight. Extra features are separated
                  into <a href="#extensions">extensions</a>, which keeps the
                  bloat away.</li>
                <li>Good documentation.</li>
                <li>Well tested. Comes with <a href="test/" title="Jasmine Tests">100s of test cases</a>.</li>
              </ul>
            </div>
            <div class="span6">
              <h2>Supported browsers: <b style="font-size: 14px; font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif; font-weight: normal;">[1]</b></h2>
              <ul>
                <li>Internet Explorer 8+</li>
                <li>Chrome 4+</li>
                <li>Safari 4+</li>
                <li>Firefox 4+</li>
                <li>Opera 9+</li>
              </ul>
              <aside class="note">
                <h3>Notes:</h3>
                <div>1. Both the desktop and mobile versions of the above browsers are supported.</div>
              </aside>
            </div>
          </div>
        </div>
        <section id="getting-started">
          <div class="page-header">
            <h1>Getting Started</h1>
          </div>
          <div class="row-fluid">
            <div class="span6">
              <p>
                Backgrid.js depends on 3 libraries to function:
              </p>
              <ul>
                <li><a href="http://jquery.com">jquery &gt;= 1.7.0</a></li>
                <li><a href="http://underscorejs.org">underscore.js ~ 1.4.0</a></li>
                <li><a href="http://backbonejs.org">backbone.js >= 0.9.10</a></li>
              </ul>
              <aside class="note">
                <h5>Note:</h5> If you don&apos;t care about having the latest
                versions of the dependencies, you can use the bundled libraries
                in the download package.
              </aside>
            </div>
            <div class="span6">
              <p>
                Something like the following will get
                the <strong>Backgrid.js</strong> core loaded:
              </p>
              <textarea class="code-snippet" data-mode="htmlmixed">
                &lt;link rel="stylesheet" href="lib/backgrid.css" /&gt;
                &lt;script src="assets/js/jquery.js"&gt;&lt;/script&gt;
                &lt;script src="assets/js/underscore.js"&gt;&lt;/script&gt;
                &lt;script src="assets/js/backbone.js"&gt;&lt;/script&gt;
                &lt;script src="lib/backgrid.js"&gt;&lt;/script&gt;</textarea>
              <p>Adjust the paths as needed.</p>
            </div>
          </div>
        </section>
        <section id="examples">
          <div class="page-header">
            <h1>Examples</h1>
          </div>
          <div class="row-fluid">
            <div class="span12">
              <div class="row-fluid">
                <div class="span6">
                  <h2>Collection and Model</h2>
                  <p>Before you can display any tabular data in a grid, you must
                    first obtain the data.</p>
                  <p>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.</p>
                  <p>Suppose we have a list of territory info objects:</p>
                </div>
                <div class="span6">
                  <textarea class="code-snippet" data-mode="javascript" data-eval="yes">
                    var Territory = Backbone.Model.extend({});

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

                    var territories = new Territories();</textarea>
                </div>
              </div>
              <div class="row-fluid">
                <div class="span12">
                  <h2 id="example-1">Grid</h2>
                  <p>
                    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:
                  </p>
                  <textarea class="code-snippet" data-mode="javascript" data-eval="yes">
                    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&apos;t be
                      // Defines a cell type, and ID is displayed as an integer without the &apos;,&apos; separating 1000s.
                      cell: Backgrid.IntegerCell.extend({
                        orderSeparator: &apos;&apos;
                      })
                    }, {
                      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 anchor element
                    }];

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

                    // Fetch some countries from the url
                    territories.fetch({reset: true});</textarea>
                </div>
              </div>
              <div class="row-fluid">
                <div class="span12">
                  <h3>Result</h3>
                  <div id="example-1-result" class="backgrid-container"></div>
                  <aside class="note">See <a href="http://en.wikipedia.org/wiki/List_of_countries_by_population">Wikipedia</a></aside>
                  <br />
                  <p>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&apos;t care where the column
                    definitions come from, as long as you supply the list to the
                    Grid constructor.</p>
                  <p>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.</p>
                  <p>Backgrid.js comes with <a href="#api-cell" title="Cells">10
                      basic cell types</a> in the core
                      and <a href="#api-text-cell" title="TextCell">many others
                      as extensions</a>. Cell types such as
                    <a href="#api-select2-cell"
                       title="Select2Cell">Select2Cell</a>
                       and <a href="#api-moment-cell"
                       title="MomentCell">MomentCell</a> give you a much richer
                       editing interface for option lists and datetime values on
                       desktop browsers. In addition, there&apos;s a wide range
                       of possibilities with how the data is converted for
                       display and persistence by using <a href="#api-formatter"
                       title="Formatter">formatters</a> or
                       customizing <a href="#api-cell">cell classes</a>.</p>
                </div>
              </div>
              <div class="row-fluid">
                <div class="span12">
                  <h2 id="example-2">A More Complete Example</h2>
                  <p>If you have a large result set like the above, you&apos;d
                    probably want to be able to paginate and filter your
                    results. This is easily achieved in Backgrid.js.</p>
                  <p>Backgrid.js comes with a number of filters and a paginator
                    extension which you can load by including the following into
                    your <code>head</code> tag:</p>
                  <textarea class="code-snippet" data-mode="htmlmixed">
                    &lt;link rel="stylesheet" href="lib/extensions/filter/backgrid-filter.css" /&gt;
                    &lt;link rel="stylesheet" href="lib/extensions/paginator/backgrid-paginator.css" /&gt;
                    &lt;script src="assets/js/backbone-pageable.js"&gt;&lt;/script&gt;
                    &lt;script src="lib/extensions/filter/backgrid-filter.js"&gt;&lt;/script&gt;
                    &lt;script src="lib/extensions/paginator/backgrid-paginator.js"&gt;&lt;/script&gt;</textarea>
                  <p>To use the paginator, you must first declare your
                    collections to be
                    a <a href="https://github.com/wyuenho/backbone-pageable/"
                         title="Backbone.PageableCollection">Backbone.PageableCollection</a>,
                    which is a simple subclass of the Backbone.js Collection with added
                    pagination behavior.</p>
                  <textarea class="code-snippet" data-mode="javascript" data-eval="yes">
                    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();

                    // Set up a grid to use the pageable collection
                    var pageableGrid = new Backgrid.Grid({
                      columns: columns,
                      collection: pageableTerritories
                    });

                    // Render the grid
                    var $example2 = $("#example-2-result");
                    $example2.append(pageableGrid.render().$el)

                    // Initialize the paginator
                    var paginator = new Backgrid.Extension.Paginator({
                      collection: pageableTerritories
                    });

                    // Render the paginator
                    $example2.append(paginator.render().$el);

                    // Initialize a client-side filter to filter on the client
                    // mode pageable collection's cache.
                    var filter = new Backgrid.Extension.ClientSideFilter({
                      collection: pageableTerritories.fullCollection,
                      fields: ['name']
                    });

                    // Render the filter
                    $example2.prepend(filter.render().$el);

                    // Add some space to the filter and move it to the right
                    filter.$el.css({float: "right", margin: "20px"});

                    // Fetch some data
                    pageableTerritories.fetch({reset: true});</textarea>
                </div>
              </div>
              <div class="row-fluid">
                <div class="span12">
                  <h3>Result</h3>
                  <div id="example-2-result" class="backgrid-container"></div>
                </div>
              </div>
            </div>
          </div>
        </section>
        <section>
          <div class="page-header">
            <h1>API Reference</h1>
          </div>
          <div class="row-fluid">
            <div class="span2">
              <h2 id="api-grid">Grid</h2>
              <ul class="nav">
                <li><a href="api/index.html#!/api/Backgrid.Grid">Backgrid.Grid</a></li>
              </ul>
              <h3>Events</h3>
              <ul class="nav">
                <li><a href="api/index.html#!/api/Backgrid.Grid-method-render">backgrid:rendered</a></li>
              </ul>
            </div>
            <div class="span10">
              <h3>How to Use the Grid</h3>
              <p>As described in the <a href="#examples">examples</a> above, a
                basic grid needs only a collection and a list of column
                definitions.</p>
              <h3>Manipulating Columns and Rows</h3>
              <p>It is very easy to insert or remove a row in a grid, you just
                have to pass a model reference
                to <a href="api/index.html#!/api/Backgrid.Grid-method-insertRow">Grid#insertRow</a>
                or <a href="api/index.html#!/api/Backgrid.Grid-method-removeRow">Grid#removeRow</a>.</p>
              <textarea class="code-snippet" data-mode="javascript">
                // Inserting rows
                grid.insertRow([{
                  // model 1
                }, {
                  // model 2 ... etc
                }]);

                // Remove rows
                var musketeers = grid.collection.where({ job: "Musketeer" });
                grid.removeRow(musketeers);</textarea>
              <p>Inserting and remove columns is similarly easy. You just need
                to pass some definitions
                to <a href="api/index.html#!/api/Backgrid.Grid-method-insertColumn">Grid#insertColumn</a>
                or
                <a href="api/index.html#!/api/Backgrid.Grid-method-removeColumn">Grid#removeColumn</a>.</p>
              <textarea class="code-snippet" data-mode="javascript">
                // 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);</textarea>
              <h3>Customization</h3>
              <p>The various ways of customizing a grid are described in the
                following sections.</p>
            </div>
          </div>
          <div class="row-fluid">
            <div class="span2">
              <h2 id="api-column">Columns</h2>
              <ul class="nav">
                <li><a href="api/index.html#!/api/Backgrid.Column" title="Backgrid.Column">Backgrid.Column</a></li>
                <li><a href="api/index.html#!/api/Backgrid.Columns" title="Backgrid.Columns">Backgrid.Columns</a></li>
              </ul>
            </div>
            <div class="span10">
              <h3>Column Defaults</h3>
              <p>Column defaults and required parameters are defined in
                the <a href="api/index.html#!/api/Backgrid.Column-method-initialize">Backgrid.Column#initialize</a>
                method.</p>
              <h3>Column Definition</h3>
              <p>A Column is a placeholder for a column definition.</p>
              <p>You usually don&apos;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.</p>
              <p>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 <a href="api/index.html#!/api/Backgrid.Columns">Backgrid.Columns</a>
                collection and pass a reference to any subviews that require
                it.</p>
              <h3>Listening to Column Attribute Changes</h3>
              <p>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.</p>
              <textarea class="code-snippet" data-mode="javascript" data-eval="no">
                var myColumns = new Backgrid.Columns({
                  name: "id", label: "ID", cell: "string"
                }, {
                  // ...
                });

                myColumns.on("change:renderable", function (col, colAttr) {
                  if (!colAttr) {
                    // hide the column
                  }
                });</textarea>
            </div>
          </div>
          <div class="row-fluid">
            <div class="span2">
              <h2 id="api-cell">Cell</h2>
              <ul class="nav">
                <li><a href="api/index.html#!/api/Backgrid.Cell">Backgrid.Cell</a></li>
                <li><a href="api/index.html#!/api/Backgrid.DatetimeCell">Backgrid.DatetimeCell</a></li>
                <li><a href="api/index.html#!/api/Backgrid.DateCell">Backgrid.DateCell</a></li>
                <li><a href="api/index.html#!/api/Backgrid.TimeCell">Backgrid.TimeCell</a></li>
                <li><a href="api/index.html#!/api/Backgrid.NumberCell">Backgrid.NumberCell</a></li>
                <li><a href="api/index.html#!/api/Backgrid.IntegerCell">Backgrid.IntegerCell</a></li>
                <li><a href="api/index.html#!/api/Backgrid.StringCell">Backgrid.StringCell</a></li>
                <li><a href="api/index.html#!/api/Backgrid.UriCell">Backgrid.UriCell</a></li>
                <li><a href="api/index.html#!/api/Backgrid.EmailCell">Backgrid.EmailCell</a></li>
                <li><a href="api/index.html#!/api/Backgrid.BooleanCell">Backgrid.BooleanCell</a></li>
                <li><a href="api/index.html#!/api/Backgrid.SelectCell">Backgrid.SelectCell</a></li>
                <li><a href="api/index.html#!/api/Backgrid.CellEditor">Backgrid.CellEditor</a></li>
                <li><a href="api/index.html#!/api/Backgrid.InputCellEditor">Backgrid.InputCellEditor</a></li>
                <li><a href="api/index.html#!/api/Backgrid.SelectCellEditor">Backgrid.SelectCellEditor</a></li>
              </ul>
              <h3>Events</h3>
              <ul class="nav">
                <li><a href="api/index.html#!/api/Backgrid.Cell-method-enterEditMode">backgrid:edit</a></li>
                <li><a href="api/index.html#!/api/Backgrid.Cell-method-enterEditMode">backgrid:editing</a></li>
                <li><a href="api/index.html#!/api/Backgrid.InputCellEditor-method-saveOrCancel">backgrid:edited</a></li>
                <li><a href="api/index.html#!/api/Backgrid.InputCellEditor-method-saveOrCancel">backgrid:error</a></li>
              </ul>
            </div>
            <div class="span10">
              <h3>Demo</h3>
              <p class="label label-success">Try them</p>
              <div id="cell-demo-grid-1" class="backgrid-container" style="height: auto"></div>
              <div id="cell-demo-grid-2" class="backgrid-container" style="height: auto"></div>
              <aside class="note">
                <h5>Note:</h5>
                <p>Backgrid.js and its author are not associated with Santa and
                  santaclaus.com in any way.</p>
              </aside>
              <h3>Configuring Cells</h3>
              <p>While many built-in cells provide reasonable defaults, you may
                choose to configure them to suit your own needs.</p>
              <p>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.</p>
              <textarea class="code-snippet" data-mode="javascript" data-eval="no">
                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 &apos;,&apos;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
                });
              </textarea>
              <p class="label label-info">Pro Tip</p>
              <p>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 <a href="#api-formatter"
                title="Formatter">formatter</a>.</p>
              <p>See the <a href="api/index.html" title="API Doc">JSDoc</a> for
                the various Cell classes for details on what you can configure
                using this method.</p>
              <h3>Custom Cell</h3>
              <p>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.</p>
              <p>If your custom cell will still use a
                <code>&lt;input type="text" /&gt;</code> like the predefined
                ones for editing, you may choose to
                subclass <a href="api/index.html#!/api/Backgrid.Cell">Cell</a>
                or one of the predefined classes and simply define a className
                and a <a href="#api-formatter"
                title="Formatter">formatter</a>. In fact, most of the core cell
                classes are done this way.</p>
              <textarea class="code-snippet" data-mode="javascript" data-eval="no">
                // This is how StringCell is defined.

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

                });</textarea>
              <p>If your cell class will render differently in display mode, you
                may simply
                override <a href="api/index.html#!/api/Backgrid.Cell-method-render">Cell#render()</a>
                in your subclass.</p>
              <h3>Custom CellEditor</h3>
              <p class="label label-warning">Advanced Usage</p>
              <p>Some cell types, like the
                <a href="#api-text-cell" title="TextCell">TextCell</a>
                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 <a href="api/index.html#!/api/Backgrid.InputCellEditor"
                title="InputCellEditor">InputCellEditor</a>, which renders a
                <code>&lt;input type="text" /&gt;</code>, will not be suitable
                and a new <a href="api/index.html#!/api/Backgrid.CellEditor"
                title="CellEditor">CellEditor</a> must be defined.</p>
              <p>A custom cell editor should subclass <a
                href="api/index.html#!/api/Backgrid.CellEditor">CellEditor</a>
                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 <code>backgrid:edit</code> 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.</p>
              <p>Once the cell has entered edit mode, a Backbone event
                <code>backgrid:editing</code> 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.</p>
              <p>During editing, if an error is encountered (see the <a
                href="#api-formatter">formatter protocol</a> below), a cell
                editor should fire a Backbone event <code>backgrid:error</code>
                so that listeners&mdash;usually a cell instance&mdash;can
                respond appropriately. When editing is done, a cell editor
                should fire a Backbone <code>backgrid:done</code> event. A cell
                should be listening to this event so it can remove its editor
                and re-render itsef in display mode.</p>
              <p class="label label-important">Truely Advanced Hacking</p>
              <p>At the most basic level, Cells and CellEditors are simply
                <a href="http://backbonejs.org/#View"
                title="Backbone.View">Backbone.View</a> classes that are
                guaranteed to be given a number of parameters when constructed
                by <a href="api/index.html#!/api/Backgrid.Row"
                title="Row">Row</a>. You can use any Backbone.View as your Cell
                and CellEditor.</p>
            </div>
          </div>
          <div class="row-fluid">
            <div class="span2">
              <h2 id="api-formatter">Formatter</h2>
              <ul class="nav">
                <li><a href="api/index.html#!/api/Backgrid.CellFormatter">Backgrid.CellFormatter</a></li>
                <li><a href="api/index.html#!/api/Backgrid.DatetimeFormatter">Backgrid.DatetimeFormatter</a></li>
                <li><a href="api/index.html#!/api/Backgrid.NumberFormatter">Backgrid.NumberFormatter</a></li>
              </ul>
            </div>
            <div class="span10">
              <h3>Custom Formatters</h3>
              <p>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.</p>
              <p>Any formatters must have the following two methods defined:</p>
              <textarea class="code-snippet" data-mode="javascript" data-eval="no">
                var formatter = {
                  // function (*): string
                  fromRaw: function (rawData) { },
                  // function (string): *|undefined
                  toRaw: function (formattedData) { }
                };</textarea>
              <p><code>fromRaw()</code> is called by Backgrid.Cell and its
                subclasses whenever a raw model value needs to be formatted into
                a humanized form for display.</p>
              <p><code>toRaw()</code> 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.</p>
              <h3>Validation</h3>
              <p>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() <strong>MUST</strong> return <code>undefined</code>
                instead of throwing an Error.</p>
              <p>In addition to using formatters to do simple yes or no
                validations, if your model class has
                a <a href="http://backbonejs.org/#Model-validate"
                title="Backbone.Model#validate">validate()</a> method defined,
                it will also be used for validation after trying with the
                formatter.</p>
              <h3>Using Custom Formatters</h3>
              <p>A custom formatter can be used instead of the cell's default by
                extending the cell:</p>
              <textarea class="code-snippet" data-mode="javascript" data-eval="no">
                var grid = new Backgrid.Grid({
                  columns: [{
                    name: "url",
                    cell: "uri",
                    formatter: _.extend({}, Backgrid.CellFormatter.prototype, {
                      fromRaw: function (rawValue) {
                        return rawValue.replace("http://", '');
                      }
                    })
                  }],
                  collection: col
                });</textarea>
            </div>
          </div>
          <div class="row-fluid">
            <div class="span2">
              <h2 id="api-header">Header</h2>
              <ul class="nav">
                <li><a href="api/index.html#!/api/Backgrid.Header">Backgrid.Header</a></li>
                <li><a href="api/index.html#!/api/Backgrid.HeaderRow">Backgrid.HeaderRow</a></li>
                <li><a href="api/index.html#!/api/Backgrid.HeaderCell">Backgrid.HeaderCell</a></li>
              </ul>
              <h3>Events</h3>
              <ul class="nav">
                <li><a href="api/index.html#!/api/Backgrid.HeaderCell-method-sort">backgrid:sort</a></li>
              </ul>
            </div>
            <div class="span10">
              <h3>Understanding the Default Header</h3>
              <p>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 <em>label</em> is not defined in a
                column definition, its name is used as the label instead.</p>
              <p>The default header cell implementation supports sorting in
                ascending or descending order, using the column&apos;s natural
                ordering. The sorter will also allow cycling back to the
                table&apos;s default sorting order, which is sorting by the
                model <a href="http://backbonejs.org/#Model-id"
                title="Backbone.Model#id">server IDs</a>
                and <a href="http://backbonejs.org/#Model-cid"
                title="Backbone.Model#cid">client IDs</a>.</p>
              <h3>Customizing the Header</h3>
              <p class="label label-warning">Advanced Usage</p>
              <p>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 <a href="http://backbonejs.org/#View"
                title="Backbone.View">Backbone.View</a> class can be
                used. However, if you wish to modify how the sorter behaves, you
                must implement the sorting protocol. See
                the <a href="api/index.html#!/api/Backgrid.HeaderCell"
                title="Backgrid.HeaderCell API">JSDoc</a> for details.</p>
              <textarea class="code-snippet" data-mode="javascript" data-eval="no">
                var SelectAllHeaderCell = Backgrid.HeaderCell.extend({
                  // Implement your "select all" logic here
                });

                var grid = new Backgrid.Grid({

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

                  collection: col
                });</textarea>
            </div>
          </div>
          <div class="row-fluid">
            <div class="span2">
              <h2 id="api-row">Row</h2>
              <ul class="nav">
                <li><a href="api/index.html#!/api/Backgrid.Row">Backgrid.Row</a></li>
              </ul>
            </div>
            <div class="span10">
              <h3>Customizing Row</h3>
              <p class="label label-warning">Advanced Usage</p>
              <p>A row is simply an intermediary view class that constructs the
                appropriate Cell class instances for rendering the model
                columns.</p>
              <p>If you would like to override how a row is rendered, you may
                define your own Row subclass and give it to the Grid constructor
                as an option:</p>
              <textarea class="code-snippet" data-mode="javascript" data-eval="no">
                var ZebraStrippingRow = Backgrid.Row.extend({
                  // ...
                });

                var grid = new Backgrid.Grid({
                  row: ZebraStrippingRow, // <-- Tell the new Body class to use ZebraStrippingRow to render rows.
                  columns: [{
                    //...
                  }],
                  collection: col
                });</textarea>
            </div>
          </div>
          <div class="row-fluid">
            <div class="span2">
              <h2 id="api-body">Body</h2>
              <ul class="nav">
                <li><a href="api/index.html#!/api/Backgrid.Body">Backgrid.Body</a></li>
              </ul>
              <h3>Events</h3>
              <ul class="nav">
                <li><a href="api/index.html#!/api/Backgrid.Body-method-refresh">backgrid:refresh</a></li>
              </ul>
            </div>
            <div class="span10">
              <h3>Customizing Body</h3>
              <p class="label label-important">Truely Advanced Hacking</p>
              <p>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 <a href="api/index.html#!/api/Backgrid.Body">JSDoc</a> for
                details.</p>
              <textarea class="code-snippet" data-mode="javascript" data-eval="no">
                var MyBody = Backgrid.Body.extend({
                  // I really don't know why you would do this, but you can if you want
                });

                var grid = new Backgrid.Grid({
                  body: MyBody,
                  columns: [{
                    // ...
                  }],
                  collection: col
                });</textarea>
            </div>
          </div>
          <div class="row-fluid">
            <div class="span2">
              <h2 id="api-footer">Footer</h2>
              <ul class="nav">
                <li><a href="api/index.html#!/api/Backgrid.Footer">Backgrid.Footer</a></li>
              </ul>
            </div>
            <div class="span10">
              <h3>Putting Things at The End of a Table</h3>
              <p>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.</p>
              <textarea class="code-snippet" data-mode="javascript" data-eval="no">
                var CaptionFooter = Backgrid.Footer.extend({

                  render: function () {
                    this.$el.html("&lt;tr&gt;&lt;td colspan=&apos;6&apos;&gt;Hello World!&lt;/td&gt;&lt;/tr&gt;");
                    return this;
                  }

                });

                var grid = new Backgrid.Grid({
                  columns: [{
                    //...
                  }],
                  collection: col,
                  footer: CaptionFooter // <--
                });</textarea>
              <p>Very often, you&apos;ll want to append a paginator to the end
                of your table if there are too many rows. For this, there&apos;s already
                a <a href="#api-paginator">paginator extension</a> provided for you.</p>
            </div>
          </div>
        </section>
        <section id="extensions">
          <div class="page-header">
            <h1>Extensions</h1>
            <p>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.</p>
            <p>A Backgrid.js extension is a directory structure that packages
              the necessary JS, CSS, tests, and document files.</p>
            <p>To create an extension, clone the tree into your file system and
              type:</p>
            <textarea class="code-snippet" data-mode="shell">
              $ cd backgrid
              $ make extension</textarea>
            <p>A new extension directory structure should have been created for
              you under <code>src/extensions</code>. The current implementation
              of <code>make extension</code> 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.</p>
            <h2>Extension Development Guide</h2>
            <p>The following is a guideline for extension development:</p>
            <ul>
              <li>There should be 1 .js file and 1 .css file. If your code base
                gets too large, consider breaking it into multiple extensions.</li>
              <li>There should be 1 .min.js file and 1 .min.css file produced
                for distribution.</li>
              <li>Your Makefile should emulate other extensions as closely
                as possible. Specifically, you should have a <code>dist</code>
                rule that will take a <code>DIST_DIR</code> variable from
                top-level make invocations and copy the output files to the
                destination directory.</li>
              <li>You should use recess to lint your CSS file(s).</li>
              <li>You should follow the JS coding style defined <a
                href="https://github.com/wyuenho/backgrid/blob/gh-pages/CONTRIBUTING.md#coding-style">here</a>.</li>
              <li>Your .gitignore file inside the extension directory should
                ignore all output files.</li>
              <li>You should wrap your JS file in an immediately invoked
                anonymous function that lists out your dependencies in the
                parameter list.</li>
              <li>Your extension should live under
                the <code>Backgrid.Extension</code> module.</li>
              <li>You should clearly specify your dependencies …
Large files files are truncated, but you can click here to view the full file