PageRenderTime 8ms CodeModel.GetById 5ms app.highlight 23ms RepoModel.GetById 2ms app.codeStats 0ms

/index.html

https://github.com/rhinoman/backgrid
HTML | 1903 lines | 1785 code | 103 blank | 15 comment | 0 complexity | e1de209f884b16cb7de88602fba882fc MD5 | raw file

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

  1<!doctype html>
  2<!--
  3  backgrid
  4  http://github.com/wyuenho/backgrid
  5
  6  Copyright (c) 2013 Jimmy Yuen Ho Wong and contributors
  7  Licensed under the MIT @license.
  8 -->
  9<html lang="en">
 10  <head>
 11    <meta charset="utf-8" />
 12    <meta http-equiv="X-UA-Compatible" content="IE=edge;chrome=1" />
 13    <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no" />
 14    <meta name="keywords" content="backgrid,backgrid.js,backbone,backbone.js,datagrid,grid,paginator,javascript" />
 15    <meta name="description" content="A powerful widget set for building data grids with Backbone.js" />
 16
 17    <title>Backgrid.js - A powerful widget set for building data grids with Backbone.js</title>
 18
 19    <link rel="canonical" href="http://backgridjs.com" />
 20
 21    <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/2.2.2/css/bootstrap.min.css" />
 22    <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/2.2.2/css/bootstrap-responsive.min.css" />
 23    <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/select2/3.3.2/select2.min.css" />
 24    <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/codemirror/2.36.0/codemirror.min.css" />
 25    <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/codemirror/2.36.0/ambiance.min.css" />
 26    <link rel="stylesheet" href="lib/backgrid.min.css" />
 27    <link rel="stylesheet" href="lib/extensions/paginator/backgrid-paginator.min.css" />
 28    <link rel="stylesheet" href="lib/extensions/text-cell/backgrid-text-cell.min.css" />
 29    <link rel="stylesheet" href="lib/extensions/moment-cell/backgrid-moment-cell.min.css" />
 30    <link rel="stylesheet" href="lib/extensions/select2-cell/backgrid-select2-cell.min.css" />
 31    <link rel="stylesheet" href="lib/extensions/select-all/backgrid-select-all.min.css" />
 32    <link rel="stylesheet" href="lib/extensions/filter/backgrid-filter.min.css" />
 33    <link rel="stylesheet" href="assets/css/doc.css" />
 34    <!--[if lt IE 9]>
 35        <script src="//cdnjs.cloudflare.com/ajax/libs/modernizr/2.6.2/modernizr.min.js"></script>
 36        <![endif]-->
 37  </head>
 38  <body>
 39    <div id="main">
 40      <header>
 41        <div class="navbar navbar-fixed-top">
 42          <div class="navbar-inner">
 43            <div class="container">
 44              <a href="."
 45                 class="brand" title="A powerful widget set for building data grids with Backbone.js">Backgrid.js</a>
 46              <a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse">
 47                <span class="icon-bar"></span>
 48                <span class="icon-bar"></span>
 49                <span class="icon-bar"></span>
 50              </a>
 51              <div class="nav-collapse collapse">
 52                <ul class="nav nav-pills">
 53                  <li class="dropdown">
 54                    <a class="dropdown-toggle" data-toggle="dropdown" data-target="#" href="#">
 55                      Introduction
 56                      <b class="caret"></b>
 57                    </a>
 58                    <ul class="dropdown-menu">
 59                      <li><a href="#features">Features</a></li>
 60                      <li><a href="#getting-started">Getting Started</a></li>
 61                      <li><a href="#examples">Examples</a></li>
 62                    </ul>
 63                  </li>
 64                  <li class="dropdown">
 65                    <a class="dropdown-toggle" data-toggle="dropdown" data-target="#" href="#">
 66                      API Reference
 67                      <b class="caret"></b>
 68                    </a>
 69                    <ul class="dropdown-menu">
 70                      <li><a href="#api-grid">Grid</a></li>
 71                      <li><a href="#api-column">Column</a></li>
 72                      <li><a href="#api-cell">Cell</a></li>
 73                      <li><a href="#api-formatter">Formatter</a></li>
 74                      <li><a href="#api-header">Header</a></li>
 75                      <li><a href="#api-row">Row</a></li>
 76                      <li><a href="#api-body">Body</a></li>
 77                      <li><a href="#api-footer">Footer</a></li>
 78                      <li class="divider"></li>
 79                      <li><a href="#extensions"><strong class="muted">Extensions</strong></a></li>
 80                      <li class="divider"></li>
 81                      <li><a href="#api-select-all">SelectAll</a></li>
 82                      <li><a href="#api-paginator">Paginator</a></li>
 83                      <li><a href="#api-filter">Filter</a></li>
 84                      <li><a href="#api-text-cell">TextCell</a></li>
 85                      <li><a href="#api-moment-cell">MomentCell</a></li>
 86                      <li><a href="#api-select2-cell">Select2Cell</a></li>
 87                    </ul>
 88                  </li>
 89                  <li class="dropdown">
 90                    <a class="dropdown-toggle" data-toggle="dropdown" data-target="#" href="#">
 91                      More Info
 92                      <b class="caret"></b>
 93                    </a>
 94                    <ul class="dropdown-menu">
 95                      <li><a href="#styling">Styling</a></li>
 96                      <li class="divider"></li>
 97                      <li><a href="#faq">FAQ</a></li>
 98                      <li><a href="https://github.com/wyuenho/backgrid/blob/master/CHANGELOG.md" target="_blank">Change Log</a></li>
 99                      <li><a href="#license">License</a></li>
100                    </ul>
101                  </li>
102                  <li id="social-media">
103                    <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>
104                    <div class="g-plusone" data-size="medium"></div>
105                    <iframe src="http://ghbtns.com/github-btn.html?user=wyuenho&repo=backgrid&type=watch&count=true"
106                            allowtransparency="true" frameborder="0" scrolling="0" width="110" height="20"></iframe>
107                    <a href="https://coderwall.com/wyuenho"><img alt="Endorse wyuenho on Coderwall" src="http://api.coderwall.com/wyuenho/endorsecount.png" /></a>
108                    <iframe allowtransparency="true" frameborder="0" scrolling="no"
109                            style="border: 0; margin: 0 0 0 15px; padding: 0;"
110                            src="https://www.gittip.com/wyuenho/widget.html" width="48pt" height="22pt"></iframe>
111                  </li>
112                </ul>
113              </div>
114            </div>
115            <a class="visible-desktop" href="https://github.com/wyuenho/backgrid">
116              <img style="position: absolute; top: 0; right: 0; border: 0;" src="assets/img/forkme_right_gray_6d6d6d.png" alt="Fork me on GitHub">
117            </a>
118          </div>
119        </div>
120      </header>
121      <div class="container">
122        <section class="hero-unit">
123          <h1>Backgrid.js</h1>
124          <p class="lead">
125            Backgrid.js is a set of components for
126            building <strong>semantic</strong> and <strong>easily
127            stylable</strong> <strong>data grid</strong> widgets.</p>
128          <p class="lead">It offers a simple, intuitive
129              programming interface that makes easy things easy, but <em>hard things possible</em>
130              when dealing with tabular data.</p>
131          <p>
132            <div class="btn-group">
133              <a class="btn btn-large btn-success" href="#examples">See Examples</a>
134              <a class="btn btn-large btn-primary hidden-phone hidden-tablet"
135                 href="https://github.com/wyuenho/backgrid/tags">Download v0.2.6</a>
136              <a class="btn btn-large btn-info"
137                 href="https://github.com/wyuenho/backgrid/blob/0.2.6/CHANGELOG.md">What's new?</a>
138            </div>
139          </p>
140        </section>
141        <div id="features">
142          <div class="page-header">
143            <h1>Features</h1>
144            <p>The goal of Backgrid.js is to produce a set of core Backbone UI
145              elements that offer you all the basic displaying, sorting and
146              editing functionalities you&apos;d expect, and to create an
147              elegant API that makes extending Backgrid.js with extra
148              functionalities easy.</p>
149          </div>
150          <div class="row-fluid">
151            <div class="span6">
152              <h2>Advantages</h2>
153              <ul>
154                <li>No Hungarian notations.</li>
155                <li>Solid foundation. Based
156                  on <a href="http://backbonejs.org">Backbone.js</a>.</li>
157                <li>Semantic and <a href="#styling">easily stylable</a>. Just
158                  style with plain CSS like you would a normal HTML table.</li>
159                <li>Low learning curve. Works with plain old Backbone models and
160                  collections. Easy things are easy, hards things possible.</li>
161                <li>Highly modular and customizable. Componenets are just simple
162                  Backbone View classes, customization is easy if you already
163                  know Backbone.</li>
164                <li>Lightweight. Extra features are separated
165                  into <a href="#extensions">extensions</a>, which keeps the
166                  bloat away.</li>
167                <li>Good documentation.</li>
168                <li>Well tested. Comes with <a href="test/" title="Jasmine Tests">100s of test cases</a>.</li>
169              </ul>
170            </div>
171            <div class="span6">
172              <h2>Supported browsers: <b style="font-size: 14px; font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif; font-weight: normal;">[1]</b></h2>
173              <ul>
174                <li>Internet Explorer 8+</li>
175                <li>Chrome 4+</li>
176                <li>Safari 4+</li>
177                <li>Firefox 4+</li>
178                <li>Opera 9+</li>
179              </ul>
180              <aside class="note">
181                <h3>Notes:</h3>
182                <div>1. Both the desktop and mobile versions of the above browsers are supported.</div>
183              </aside>
184            </div>
185          </div>
186        </div>
187        <section id="getting-started">
188          <div class="page-header">
189            <h1>Getting Started</h1>
190          </div>
191          <div class="row-fluid">
192            <div class="span6">
193              <p>
194                Backgrid.js depends on 3 libraries to function:
195              </p>
196              <ul>
197                <li><a href="http://jquery.com">jquery &gt;= 1.7.0</a></li>
198                <li><a href="http://underscorejs.org">underscore.js ~ 1.4.0</a></li>
199                <li><a href="http://backbonejs.org">backbone.js >= 0.9.10</a></li>
200              </ul>
201              <aside class="note">
202                <h5>Note:</h5> If you don&apos;t care about having the latest
203                versions of the dependencies, you can use the bundled libraries
204                in the download package.
205              </aside>
206            </div>
207            <div class="span6">
208              <p>
209                Something like the following will get
210                the <strong>Backgrid.js</strong> core loaded:
211              </p>
212              <textarea class="code-snippet" data-mode="htmlmixed">
213                &lt;link rel="stylesheet" href="lib/backgrid.css" /&gt;
214                &lt;script src="assets/js/jquery.js"&gt;&lt;/script&gt;
215                &lt;script src="assets/js/underscore.js"&gt;&lt;/script&gt;
216                &lt;script src="assets/js/backbone.js"&gt;&lt;/script&gt;
217                &lt;script src="lib/backgrid.js"&gt;&lt;/script&gt;</textarea>
218              <p>Adjust the paths as needed.</p>
219            </div>
220          </div>
221        </section>
222        <section id="examples">
223          <div class="page-header">
224            <h1>Examples</h1>
225          </div>
226          <div class="row-fluid">
227            <div class="span12">
228              <div class="row-fluid">
229                <div class="span6">
230                  <h2>Collection and Model</h2>
231                  <p>Before you can display any tabular data in a grid, you must
232                    first obtain the data.</p>
233                  <p>At the most basic level, Backgrid pretends that every row
234                    is a model object and the whole table is backed by a simple
235                    Backbone collection.</p>
236                  <p>Suppose we have a list of territory info objects:</p>
237                </div>
238                <div class="span6">
239                  <textarea class="code-snippet" data-mode="javascript" data-eval="yes">
240                    var Territory = Backbone.Model.extend({});
241
242                    var Territories = Backbone.Collection.extend({
243                      model: Territory,
244                      url: "examples/territories.json"
245                    });
246
247                    var territories = new Territories();</textarea>
248                </div>
249              </div>
250              <div class="row-fluid">
251                <div class="span12">
252                  <h2 id="example-1">Grid</h2>
253                  <p>
254                    The main entry point of the Backgrid package is the
255                    Backgrid.Grid class. You can create a default Backgrid by
256                    first defining some columns, and then put that list of
257                    columns and the collection of data into the Grid constructor
258                    like this:
259                  </p>
260                  <textarea class="code-snippet" data-mode="javascript" data-eval="yes">
261                    var columns = [{
262                      name: "id", // The key of the model attribute
263                      label: "ID", // The name to display in the header
264                      editable: false, // By default every cell in a column is editable, but *ID* shouldn&apos;t be
265                      // Defines a cell type, and ID is displayed as an integer without the &apos;,&apos; separating 1000s.
266                      cell: Backgrid.IntegerCell.extend({
267                        orderSeparator: &apos;&apos;
268                      })
269                    }, {
270                      name: "name",
271                      label: "Name",
272                      // The cell type can be a reference of a Backgrid.Cell subclass, any Backgrid.Cell subclass instances like *id* above, or a string
273                      cell: "string" // This is converted to "StringCell" and a corresponding class in the Backgrid package namespace is looked up
274                    }, {
275                      name: "pop",
276                      label: "Population",
277                      cell: "integer" // An integer cell is a number cell that displays humanized integers
278                    }, {
279                      name: "percentage",
280                      label: "% of World Population",
281                      cell: "number" // A cell type for floating point value, defaults to have a precision 2 decimal numbers
282                    }, {
283                      name: "date",
284                      label: "Date",
285                      cell: "date",
286                    }, {
287                      name: "url",
288                      label: "URL",
289                      cell: "uri" // Renders the value in an HTML anchor element
290                    }];
291
292                    // Initialize a new Grid instance
293                    var grid = new Backgrid.Grid({
294                      columns: columns,
295                      collection: territories
296                    });
297
298                    // Render the grid and attach the root to your HTML document
299                    $("#example-1-result").append(grid.render().$el);
300
301                    // Fetch some countries from the url
302                    territories.fetch({reset: true});</textarea>
303                </div>
304              </div>
305              <div class="row-fluid">
306                <div class="span12">
307                  <h3>Result</h3>
308                  <div id="example-1-result" class="backgrid-container"></div>
309                  <aside class="note">See <a href="http://en.wikipedia.org/wiki/List_of_countries_by_population">Wikipedia</a></aside>
310                  <br />
311                  <p>The list of column definitions Backgrid.Grid expects is
312                    simply a list of JSON objects, which you can hardcode into
313                    your HTML templates or retrieve from a server when the DOM
314                    is ready. Backgrid.js doesn&apos;t care where the column
315                    definitions come from, as long as you supply the list to the
316                    Grid constructor.</p>
317                  <p>As expected, you now have a basic editable data grid
318                    displayed. All the columns headers are labeled and sortable by
319                    default. ID cells are not editable, and all other cell types
320                    have reasonable validation built in. If the table gets too
321                    large, you get a scroll bar.</p>
322                  <p>Backgrid.js comes with <a href="#api-cell" title="Cells">10
323                      basic cell types</a> in the core
324                      and <a href="#api-text-cell" title="TextCell">many others
325                      as extensions</a>. Cell types such as
326                    <a href="#api-select2-cell"
327                       title="Select2Cell">Select2Cell</a>
328                       and <a href="#api-moment-cell"
329                       title="MomentCell">MomentCell</a> give you a much richer
330                       editing interface for option lists and datetime values on
331                       desktop browsers. In addition, there&apos;s a wide range
332                       of possibilities with how the data is converted for
333                       display and persistence by using <a href="#api-formatter"
334                       title="Formatter">formatters</a> or
335                       customizing <a href="#api-cell">cell classes</a>.</p>
336                </div>
337              </div>
338              <div class="row-fluid">
339                <div class="span12">
340                  <h2 id="example-2">A More Complete Example</h2>
341                  <p>If you have a large result set like the above, you&apos;d
342                    probably want to be able to paginate and filter your
343                    results. This is easily achieved in Backgrid.js.</p>
344                  <p>Backgrid.js comes with a number of filters and a paginator
345                    extension which you can load by including the following into
346                    your <code>head</code> tag:</p>
347                  <textarea class="code-snippet" data-mode="htmlmixed">
348                    &lt;link rel="stylesheet" href="lib/extensions/filter/backgrid-filter.css" /&gt;
349                    &lt;link rel="stylesheet" href="lib/extensions/paginator/backgrid-paginator.css" /&gt;
350                    &lt;script src="assets/js/backbone-pageable.js"&gt;&lt;/script&gt;
351                    &lt;script src="lib/extensions/filter/backgrid-filter.js"&gt;&lt;/script&gt;
352                    &lt;script src="lib/extensions/paginator/backgrid-paginator.js"&gt;&lt;/script&gt;</textarea>
353                  <p>To use the paginator, you must first declare your
354                    collections to be
355                    a <a href="https://github.com/wyuenho/backbone-pageable/"
356                         title="Backbone.PageableCollection">Backbone.PageableCollection</a>,
357                    which is a simple subclass of the Backbone.js Collection with added
358                    pagination behavior.</p>
359                  <textarea class="code-snippet" data-mode="javascript" data-eval="yes">
360                    var PageableTerritories = Backbone.PageableCollection.extend({
361                      model: Territory,
362                      url: "examples/pageable-territories.json",
363                      state: {
364                        pageSize: 15
365                      },
366                      mode: "client" // page entirely on the client side
367                    });
368
369                    var pageableTerritories = new PageableTerritories();
370
371                    // Set up a grid to use the pageable collection
372                    var pageableGrid = new Backgrid.Grid({
373                      columns: columns,
374                      collection: pageableTerritories
375                    });
376
377                    // Render the grid
378                    var $example2 = $("#example-2-result");
379                    $example2.append(pageableGrid.render().$el)
380
381                    // Initialize the paginator
382                    var paginator = new Backgrid.Extension.Paginator({
383                      collection: pageableTerritories
384                    });
385
386                    // Render the paginator
387                    $example2.append(paginator.render().$el);
388
389                    // Initialize a client-side filter to filter on the client
390                    // mode pageable collection's cache.
391                    var filter = new Backgrid.Extension.ClientSideFilter({
392                      collection: pageableTerritories.fullCollection,
393                      fields: ['name']
394                    });
395
396                    // Render the filter
397                    $example2.prepend(filter.render().$el);
398
399                    // Add some space to the filter and move it to the right
400                    filter.$el.css({float: "right", margin: "20px"});
401
402                    // Fetch some data
403                    pageableTerritories.fetch({reset: true});</textarea>
404                </div>
405              </div>
406              <div class="row-fluid">
407                <div class="span12">
408                  <h3>Result</h3>
409                  <div id="example-2-result" class="backgrid-container"></div>
410                </div>
411              </div>
412            </div>
413          </div>
414        </section>
415        <section>
416          <div class="page-header">
417            <h1>API Reference</h1>
418          </div>
419          <div class="row-fluid">
420            <div class="span2">
421              <h2 id="api-grid">Grid</h2>
422              <ul class="nav">
423                <li><a href="api/index.html#!/api/Backgrid.Grid">Backgrid.Grid</a></li>
424              </ul>
425              <h3>Events</h3>
426              <ul class="nav">
427                <li><a href="api/index.html#!/api/Backgrid.Grid-method-render">backgrid:rendered</a></li>
428              </ul>
429            </div>
430            <div class="span10">
431              <h3>How to Use the Grid</h3>
432              <p>As described in the <a href="#examples">examples</a> above, a
433                basic grid needs only a collection and a list of column
434                definitions.</p>
435              <h3>Manipulating Columns and Rows</h3>
436              <p>It is very easy to insert or remove a row in a grid, you just
437                have to pass a model reference
438                to <a href="api/index.html#!/api/Backgrid.Grid-method-insertRow">Grid#insertRow</a>
439                or <a href="api/index.html#!/api/Backgrid.Grid-method-removeRow">Grid#removeRow</a>.</p>
440              <textarea class="code-snippet" data-mode="javascript">
441                // Inserting rows
442                grid.insertRow([{
443                  // model 1
444                }, {
445                  // model 2 ... etc
446                }]);
447
448                // Remove rows
449                var musketeers = grid.collection.where({ job: "Musketeer" });
450                grid.removeRow(musketeers);</textarea>
451              <p>Inserting and remove columns is similarly easy. You just need
452                to pass some definitions
453                to <a href="api/index.html#!/api/Backgrid.Grid-method-insertColumn">Grid#insertColumn</a>
454                or
455                <a href="api/index.html#!/api/Backgrid.Grid-method-removeColumn">Grid#removeColumn</a>.</p>
456              <textarea class="code-snippet" data-mode="javascript">
457                // Insert a few new columns. Make sure your model has these attributes though.
458                grid.insertColumn([{
459
460                    name: "selected",
461                    label: "",
462                    cell: "boolean",
463                    sortable: false,
464                    headerCell: MySelectAllCell
465
466                  }, {
467
468                    name: "address",
469                    label: "Address",
470                    cell: "string"
471
472                  }]);
473
474                // Remove a column
475                var genderCol = grid.columns.where({ name: "gender" });
476                grid.removeColumn(genderCol);</textarea>
477              <h3>Customization</h3>
478              <p>The various ways of customizing a grid are described in the
479                following sections.</p>
480            </div>
481          </div>
482          <div class="row-fluid">
483            <div class="span2">
484              <h2 id="api-column">Columns</h2>
485              <ul class="nav">
486                <li><a href="api/index.html#!/api/Backgrid.Column" title="Backgrid.Column">Backgrid.Column</a></li>
487                <li><a href="api/index.html#!/api/Backgrid.Columns" title="Backgrid.Columns">Backgrid.Columns</a></li>
488              </ul>
489            </div>
490            <div class="span10">
491              <h3>Column Defaults</h3>
492              <p>Column defaults and required parameters are defined in
493                the <a href="api/index.html#!/api/Backgrid.Column-method-initialize">Backgrid.Column#initialize</a>
494                method.</p>
495              <h3>Column Definition</h3>
496              <p>A Column is a placeholder for a column definition.</p>
497              <p>You usually don&apos;t need to create an instance of this class
498                yourself, as a collection of column instances will be created for
499                you from a list of column object literals you provide to the
500                Backgrid.js view class constructors.</p>
501              <p>Internally, columns are stored as a collection in the form of
502                Backgrid.Columns. In addition, all parent views will convert the
503                column definition into
504                a <a href="api/index.html#!/api/Backgrid.Columns">Backgrid.Columns</a>
505                collection and pass a reference to any subviews that require
506                it.</p>
507              <h3>Listening to Column Attribute Changes</h3>
508              <p>Occasionally, you may want to listen to column attribute change
509                events. In that case, you can choose to initialize a
510                Backgrid.Columns collection and listen to events from the
511                individual models.</p>
512              <textarea class="code-snippet" data-mode="javascript" data-eval="no">
513                var myColumns = new Backgrid.Columns({
514                  name: "id", label: "ID", cell: "string"
515                }, {
516                  // ...
517                });
518
519                myColumns.on("change:renderable", function (col, colAttr) {
520                  if (!colAttr) {
521                    // hide the column
522                  }
523                });</textarea>
524            </div>
525          </div>
526          <div class="row-fluid">
527            <div class="span2">
528              <h2 id="api-cell">Cell</h2>
529              <ul class="nav">
530                <li><a href="api/index.html#!/api/Backgrid.Cell">Backgrid.Cell</a></li>
531                <li><a href="api/index.html#!/api/Backgrid.DatetimeCell">Backgrid.DatetimeCell</a></li>
532                <li><a href="api/index.html#!/api/Backgrid.DateCell">Backgrid.DateCell</a></li>
533                <li><a href="api/index.html#!/api/Backgrid.TimeCell">Backgrid.TimeCell</a></li>
534                <li><a href="api/index.html#!/api/Backgrid.NumberCell">Backgrid.NumberCell</a></li>
535                <li><a href="api/index.html#!/api/Backgrid.IntegerCell">Backgrid.IntegerCell</a></li>
536                <li><a href="api/index.html#!/api/Backgrid.StringCell">Backgrid.StringCell</a></li>
537                <li><a href="api/index.html#!/api/Backgrid.UriCell">Backgrid.UriCell</a></li>
538                <li><a href="api/index.html#!/api/Backgrid.EmailCell">Backgrid.EmailCell</a></li>
539                <li><a href="api/index.html#!/api/Backgrid.BooleanCell">Backgrid.BooleanCell</a></li>
540                <li><a href="api/index.html#!/api/Backgrid.SelectCell">Backgrid.SelectCell</a></li>
541                <li><a href="api/index.html#!/api/Backgrid.CellEditor">Backgrid.CellEditor</a></li>
542                <li><a href="api/index.html#!/api/Backgrid.InputCellEditor">Backgrid.InputCellEditor</a></li>
543                <li><a href="api/index.html#!/api/Backgrid.SelectCellEditor">Backgrid.SelectCellEditor</a></li>
544              </ul>
545              <h3>Events</h3>
546              <ul class="nav">
547                <li><a href="api/index.html#!/api/Backgrid.Cell-method-enterEditMode">backgrid:edit</a></li>
548                <li><a href="api/index.html#!/api/Backgrid.Cell-method-enterEditMode">backgrid:editing</a></li>
549                <li><a href="api/index.html#!/api/Backgrid.InputCellEditor-method-saveOrCancel">backgrid:edited</a></li>
550                <li><a href="api/index.html#!/api/Backgrid.InputCellEditor-method-saveOrCancel">backgrid:error</a></li>
551              </ul>
552            </div>
553            <div class="span10">
554              <h3>Demo</h3>
555              <p class="label label-success">Try them</p>
556              <div id="cell-demo-grid-1" class="backgrid-container" style="height: auto"></div>
557              <div id="cell-demo-grid-2" class="backgrid-container" style="height: auto"></div>
558              <aside class="note">
559                <h5>Note:</h5>
560                <p>Backgrid.js and its author are not associated with Santa and
561                  santaclaus.com in any way.</p>
562              </aside>
563              <h3>Configuring Cells</h3>
564              <p>While many built-in cells provide reasonable defaults, you may
565                choose to configure them to suit your own needs.</p>
566              <p>Cell types that you are most likely to configure are the
567                NumberCell, DatetimeCell and SelectCell classes. Once
568                configured, you may use them as the cell attribute values in
569                column definitions.</p>
570              <textarea class="code-snippet" data-mode="javascript" data-eval="no">
571                var grid = new Backgrid.Grid({
572
573                  columns: [{
574                    name: "id",
575                    label: "ID",
576                    editable: false,
577                    // Dynamically defines a new cell type with new defaults.
578                    // ID is displayed as an integer without &apos;,&apos;s.
579                    cell: Backgrid.IntegerCell.extend({
580                      orderSeparator: ''
581                    })
582                  }, {
583                    name: "lastaccessed",
584                    label: "Last Login Time",
585                    editable: false,
586                    cell: Backgrid.DatetimeCell.extend({
587                      includeMilli: true
588                    })
589                  }, {
590                    name: "gender",
591                    label: "Gender",
592                    cell: Backgrid.SelectCell.extend({
593                      // It's possible to render an option group or use a
594                      // function to provide option values too.
595                      optionValues: [["Male", "m"], ["Female", "f"]]
596                    })
597                  }],
598
599                  collection: col
600                });
601              </textarea>
602              <p class="label label-info">Pro Tip</p>
603              <p>SelectCell treats all option values as strings by default, if
604                you need to persist a different type of values into your model,
605                you should extend SelectCell to provide your
606                own <a href="#api-formatter"
607                title="Formatter">formatter</a>.</p>
608              <p>See the <a href="api/index.html" title="API Doc">JSDoc</a> for
609                the various Cell classes for details on what you can configure
610                using this method.</p>
611              <h3>Custom Cell</h3>
612              <p>If the built-in and extension cell classes are not enough for
613                you, you may choose to create your own cell class and supply it
614                to a column definition.</p>
615              <p>If your custom cell will still use a
616                <code>&lt;input type="text" /&gt;</code> like the predefined
617                ones for editing, you may choose to
618                subclass <a href="api/index.html#!/api/Backgrid.Cell">Cell</a>
619                or one of the predefined classes and simply define a className
620                and a <a href="#api-formatter"
621                title="Formatter">formatter</a>. In fact, most of the core cell
622                classes are done this way.</p>
623              <textarea class="code-snippet" data-mode="javascript" data-eval="no">
624                // This is how StringCell is defined.
625
626                Backgrid.StringCell = Cell.extend({
627
628                  // Cell default class names are the lower-cased and dasherized
629                  // form of the the cell class names by convention.
630                  className: "string-cell"
631
632                  formatter: Backgrid.StringFormatter
633
634                });</textarea>
635              <p>If your cell class will render differently in display mode, you
636                may simply
637                override <a href="api/index.html#!/api/Backgrid.Cell-method-render">Cell#render()</a>
638                in your subclass.</p>
639              <h3>Custom CellEditor</h3>
640              <p class="label label-warning">Advanced Usage</p>
641              <p>Some cell types, like the
642                <a href="#api-text-cell" title="TextCell">TextCell</a>
643                extension, may only make sense if the editor is rendered in a
644                modal dialog or a form element in a different part of the
645                page. In that case the
646                default <a href="api/index.html#!/api/Backgrid.InputCellEditor"
647                title="InputCellEditor">InputCellEditor</a>, which renders a
648                <code>&lt;input type="text" /&gt;</code>, will not be suitable
649                and a new <a href="api/index.html#!/api/Backgrid.CellEditor"
650                title="CellEditor">CellEditor</a> must be defined.</p>
651              <p>A custom cell editor should subclass <a
652                href="api/index.html#!/api/Backgrid.CellEditor">CellEditor</a>
653                as it defines a number of required parameters in its initializer
654                and clean up operations that are necessary for most cell
655                editors. When a cell class enters edit mode, a new editor
656                instance is constructed by given it the required parameters, and
657                then a Backbone event <code>backgrid:edit</code> is fired from
658                the cell instance itself. A custom cell class can act on this
659                event to do anything before the cell editor is rendered.</p>
660              <p>Once the cell has entered edit mode, a Backbone event
661                <code>backgrid:editing</code> is fired. A custom cell class can
662                then act on it to do anything after the cell editor has been
663                rendered, e.g. placing the focus inside the editor.</p>
664              <p>During editing, if an error is encountered (see the <a
665                href="#api-formatter">formatter protocol</a> below), a cell
666                editor should fire a Backbone event <code>backgrid:error</code>
667                so that listeners&mdash;usually a cell instance&mdash;can
668                respond appropriately. When editing is done, a cell editor
669                should fire a Backbone <code>backgrid:done</code> event. A cell
670                should be listening to this event so it can remove its editor
671                and re-render itsef in display mode.</p>
672              <p class="label label-important">Truely Advanced Hacking</p>
673              <p>At the most basic level, Cells and CellEditors are simply
674                <a href="http://backbonejs.org/#View"
675                title="Backbone.View">Backbone.View</a> classes that are
676                guaranteed to be given a number of parameters when constructed
677                by <a href="api/index.html#!/api/Backgrid.Row"
678                title="Row">Row</a>. You can use any Backbone.View as your Cell
679                and CellEditor.</p>
680            </div>
681          </div>
682          <div class="row-fluid">
683            <div class="span2">
684              <h2 id="api-formatter">Formatter</h2>
685              <ul class="nav">
686                <li><a href="api/index.html#!/api/Backgrid.CellFormatter">Backgrid.CellFormatter</a></li>
687                <li><a href="api/index.html#!/api/Backgrid.DatetimeFormatter">Backgrid.DatetimeFormatter</a></li>
688                <li><a href="api/index.html#!/api/Backgrid.NumberFormatter">Backgrid.NumberFormatter</a></li>
689              </ul>
690            </div>
691            <div class="span10">
692              <h3>Custom Formatters</h3>
693              <p>In Backgrid.js, cell formatters serves the purpose of converting values
694                between JSON value types and strings, and validation. Writing
695                formatters for value conversion and validation is easy as you only
696                have to conform to a very simple protocol.</p>
697              <p>Any formatters must have the following two methods defined:</p>
698              <textarea class="code-snippet" data-mode="javascript" data-eval="no">
699                var formatter = {
700                  // function (*): string
701                  fromRaw: function (rawData) { },
702                  // function (string): *|undefined
703                  toRaw: function (formattedData) { }
704                };</textarea>
705              <p><code>fromRaw()</code> is called by Backgrid.Cell and its
706                subclasses whenever a raw model value needs to be formatted into
707                a humanized form for display.</p>
708              <p><code>toRaw()</code> is called by Backgrid.CellEditor and its
709                subclasses whenever a user input string needs to be converted back
710                to a raw JSON value for model persistence.</p>
711              <h3>Validation</h3>
712              <p>In addition to user input conversion, toRaw() also validates
713                the user input during conversion. If the user input is invalid
714                or cannot be converted to a JSON value,
715                toRaw() <strong>MUST</strong> return <code>undefined</code>
716                instead of throwing an Error.</p>
717              <p>In addition to using formatters to do simple yes or no
718                validations, if your model class has
719                a <a href="http://backbonejs.org/#Model-validate"
720                title="Backbone.Model#validate">validate()</a> method defined,
721                it will also be used for validation after trying with the
722                formatter.</p>
723              <h3>Using Custom Formatters</h3>
724              <p>A custom formatter can be used instead of the cell's default by
725                extending the cell:</p>
726              <textarea class="code-snippet" data-mode="javascript" data-eval="no">
727                var grid = new Backgrid.Grid({
728                  columns: [{
729                    name: "url",
730                    cell: "uri",
731                    formatter: _.extend({}, Backgrid.CellFormatter.prototype, {
732                      fromRaw: function (rawValue) {
733                        return rawValue.replace("http://", '');
734                      }
735                    })
736                  }],
737                  collection: col
738                });</textarea>
739            </div>
740          </div>
741          <div class="row-fluid">
742            <div class="span2">
743              <h2 id="api-header">Header</h2>
744              <ul class="nav">
745                <li><a href="api/index.html#!/api/Backgrid.Header">Backgrid.Header</a></li>
746                <li><a href="api/index.html#!/api/Backgrid.HeaderRow">Backgrid.HeaderRow</a></li>
747                <li><a href="api/index.html#!/api/Backgrid.HeaderCell">Backgrid.HeaderCell</a></li>
748              </ul>
749              <h3>Events</h3>
750              <ul class="nav">
751                <li><a href="api/index.html#!/api/Backgrid.HeaderCell-method-sort">backgrid:sort</a></li>
752              </ul>
753            </div>
754            <div class="span10">
755              <h3>Understanding the Default Header</h3>
756              <p>Backgrid.js comes with a default header section, a header row
757                and a header cell implementation that renders a sorter if the
758                column is sortable. The text inside the header cells comes from
759                the column definitions. If a <em>label</em> is not defined in a
760                column definition, its name is used as the label instead.</p>
761              <p>The default header cell implementation supports sorting in
762                ascending or descending order, using the column&apos;s natural
763                ordering. The sorter will also allow cycling back to the
764                table&apos;s default sorting order, which is sorting by the
765                model <a href="http://backbonejs.org/#Model-id"
766                title="Backbone.Model#id">server IDs</a>
767                and <a href="http://backbonejs.org/#Model-cid"
768                title="Backbone.Model#cid">client IDs</a>.</p>
769              <h3>Customizing the Header</h3>
770              <p>If you want to change the default sort behavior to only toggle
771                between sorting in ascending or descending order, you do this
772                by passing ```sortType: "toggle"``` as part of your column
773                definition.</p>
774              <textarea class="code-snippet" data-mode="javascript" data-eval="no">
775                var grid = new Backgrid.Grid({
776                  columns: [{
777                    name: "id",
778                    label: "ID"
779                  },{
780                    name: "name",
781                    label: "Name"
782                  },{
783                    name: "age",
784                    label: "Age",
785                    sortTye: "toggle"
786                  }]
787                });
788              </textarea>
789              <p class="label label-warning">Advanced Usage</p>
790              <p>You are allow to use a different header cell class on
791                columns. There is no restriction on what a header cell must do. In fact,
792                any <a href="http://backbonejs.org/#View"
793                title="Backbone.View">Backbone.View</a> class can be
794                used. However, if you wish to modify how the sorter behaves, you
795                must implement the sorting protocol. See
796                the <a href="api/index.html#!/api/Backgrid.HeaderCell"
797                title="Backgrid.HeaderCell API">JSDoc</a> for details.</p>
798              <textarea class="code-snippet" data-mode="javascript" data-eval="no">
799                var SelectAllHeaderCell = Backgrid.HeaderCell.extend({
800                  // Implement your "select all" logic here
801                });
802
803                var grid = new Backgrid.Grid({
804
805                  columns: [{
806                    name: "selected",
807                    label: "",
808                    sortable: false,
809                    cell: "boolean",
810                    headerCell: SelectAllHeaderCell
811                  }],
812
813                  collection: col
814                });</textarea>
815            </div>
816          </div>
817          <div class="row-fluid">
818            <div class="span2">
819              <h2 id="api-row">Row</h2>
820              <ul class="nav">
821                <li><a href="api/index.html#!/api/Backgrid.Row">Backgrid.Row</a></li>
822              </ul>
823            </div>
824            <div class="span10">
825              <h3>Customizing Row</h3>
826              <p class="label label-warning">Advanced Usage</p>
827              <p>A row is simply an intermediary view class that constructs the
828                appropriate Cell class instances for rendering the model
829                columns.</p>
830              <p>If you would like to override how a row is rendered, you may
831                define your own Row subclass and give it to the Grid constructor
832                as an option:</p>
833              <textarea class="code-snippet" data-mode="javascript" data-eval="no">
834                var ZebraStrippingRow = Backgrid.Row.extend({
835                  // ...
836                });
837
838                var grid = new Backgrid.Grid({
839                  row: ZebraStrippingRow, // <-- Tell the new Body class to use ZebraStrippingRow to render rows.
840                  columns: [{
841                    //...
842                  }],
843                  collection: col
844                });</textarea>
845            </div>
846          </div>
847          <div class="row-fluid">
848            <div class="span2">
849              <h2 id="api-body">Body</h2>
850              <ul class="nav">
851                <li><a href="api/index.html#!/api/Backgrid.Body">Backgrid.Body</a></li>
852              </ul>
853              <h3>Events</h3>
854              <ul class="nav">
855                <li><a href="api/index.html#!/api/Backgrid.Body-method-refresh">backgrid:refresh</a></li>
856              </ul>
857            </div>
858            <div class="span10">
859              <h3>Customizing Body</h3>
860              <p class="label label-important">Truely Advanced Hacking</p>
861              <p>Body is the intermediary view that coordinates between the
862                various parts of the grid. Specifically, the default
863                implementation is responsible for re-rendering the rows when any
864                model is inserted into, removed from, or reordered in the
865                underlying collection. See
866                the <a href="api/index.html#!/api/Backgrid.Body">JSDoc</a> for
867                details.</p>
868              <textarea class="code-snippet" data-mode="javascript" data-eval="no">
869                var MyBody = Backgrid.Body.extend({
870                  // I really don't know why you would do this, but you can if you want
871                });
872
873                var grid = new Backgrid.Grid({
874                  body: MyBody,
875                  columns: [{
876                    // ...
877                  }],
878                  collection: col
879                });</textarea>
880            </div>
881          </div>
882          <div class="row-fluid">
883            <div class="span2">
884              <h2 id="api-footer">Footer</h2>
885              <ul class="nav">
886                <li><a href="api/index.html#!/api/Backgrid.Footer">Backgrid.Footer</a></li>
887              </ul>
888            </div>
889            <div class="span10">
890              <h3>Putting Things at The End of a Table</h3>
891              <p>The default Footer class is an abstract class that only defines
892                a number of required constructor parameters. If you wish to
893                append additional information to the end of a table you must
894                subclass Footer and supply the class to the Grid
895                constructor.</p>
896              <textarea class="code-snippet" data-mode="javascript" data-eval="no">
897                var CaptionFooter = Backgrid.Footer.extend({
898
899                  render: function () {
900                    this.$el.html("&lt;tr&gt;&lt;td colspan=&apos;6&apos;&gt;Hello World!&lt;/td&gt;&lt;/tr&gt;");
901                    return this;
902                  }
903
904                });
905
906                var grid = new Backgrid.Grid({
907                  columns: [{
908                    //...
909                  }],
910                  collection: col,
911                  footer: CaptionFooter // <--
912                });</textarea>
913              <p>Very often, you&apos;ll want to append a paginator to the end
914                of your table if there are too many rows. For this, there&apos;s already
915                a <a href="#api-paginator">paginator extension</a> provided for you.</p>
916            </div>
917          </div>
918        </section>
919        <section id="extensions">
920          <div class="page-header">
921            <h1>Extensions</h1>
922            <p>It is not necessary to create an extension project if you simply
923              want to customize or extend some Backgrid.js classes for your own
924              private use; however, if you have one or more Backgrid.js
925              components that add new features to the core, you may consider
926              packaging them up to share with the world.</p>
927            <p>A Backgrid.js extension is a directory structure that packages
928              the necessary JS, CSS, tests, and document files.</p>
929            <p>To create an extension, clone the tree into your file system and
930              type:</p>
931            <textarea class="code-snippet" data-mode="shell">
932              $ cd backgrid
933              $ make extension</textarea>
934            <p>A new extension directory structure should have been created for
935              you under <code>src/extensions</code>. The current implementation
936              of <code>make extension</code> only creates a blank directory
937              filled with a number of blank files for you. You should take a
938              look at other extensions to copy what you need. e.g. Makefile,
939              .gitignore.</p>
940            <h2>Extension Development Guide</h2>
941            <p>The following is a guideline for extension development:</p>
942            <ul>
943              <li>There should be 1 .js file and 1 .css file. If your code base
944                gets too large, consider breaking it into multiple extensions.</li>
945              <li>There should be 1 .min.js file and 1 .min.css file produced
946                for distribution.</li>
947              <li>Your Makefile should emulate other extensions as closely
948                as possible. Specifically, you should have a <code>dist</code>
949                rule that will take a <code>DIST_DIR</code> variable from
950                top-level make invocations and copy the output files to the
951

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