forked from cloudflarearchive/backgrid
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathindex.html
1919 lines (1815 loc) · 95.5 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!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'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. Components 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 >= 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'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">
<link rel="stylesheet" href="lib/backgrid.css" />
<script src="assets/js/jquery.js"></script>
<script src="assets/js/underscore.js"></script>
<script src="assets/js/backbone.js"></script>
<script src="lib/backgrid.js"></script></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't be
// Defines a cell type, and ID is displayed as an integer without the ',' separating 1000s.
cell: Backgrid.IntegerCell.extend({
orderSeparator: ''
})
}, {
name: "name",
label: "Name",
// The cell type can be a reference of a Backgrid.Cell subclass, any Backgrid.Cell subclass instances like *id* above, or a string
cell: "string" // This is converted to "StringCell" and a corresponding class in the Backgrid package namespace is looked up
}, {
name: "pop",
label: "Population",
cell: "integer" // An integer cell is a number cell that displays humanized integers
}, {
name: "percentage",
label: "% of World Population",
cell: "number" // A cell type for floating point value, defaults to have a precision 2 decimal numbers
}, {
name: "date",
label: "Date",
cell: "date",
}, {
name: "url",
label: "URL",
cell: "uri" // Renders the value in an HTML 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'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'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'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">
<link rel="stylesheet" href="lib/extensions/filter/backgrid-filter.css" />
<link rel="stylesheet" href="lib/extensions/paginator/backgrid-paginator.css" />
<script src="assets/js/backbone-pageable.js"></script>
<script src="lib/extensions/filter/backgrid-filter.js"></script>
<script src="lib/extensions/paginator/backgrid-paginator.js"></script></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'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 ','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><input type="text" /></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><input type="text" /></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—usually a cell instance—can
respond appropriately. When editing is done, a cell editor
should fire a Backbone <code>backgrid:edited</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's natural
ordering. The sorter will also allow cycling back to the
table'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>If you want to change the default sort behavior to only toggle
between sorting in ascending or descending order, you do this
by passing ```sortType: "toggle"``` as part of your column
definition.</p>
<textarea class="code-snippet" data-mode="javascript" data-eval="no">
var grid = new Backgrid.Grid({
columns: [{
name: "id",
label: "ID"
},{
name: "name",
label: "Name"
},{
name: "age",
label: "Age",
sortTye: "toggle"
}]
});
</textarea>
<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">
// Suppose you want to highlight the entire row when an editable field is focused
var FocusableRow = Backgrid.Row.extend({
highlightColor: 'lightYellow',
events: {
focusin: 'rowFocused',
focusout: 'rowLostFocus'
},
rowFocused: function() {
this.$el.css('background-color', this.highlightColor);
},
rowLostFocus: function() {
this.$el.removeAttr('style');
}
});
var grid = new Backgrid.Grid({
row: FocusableRow, // <-- Tell the Body class to use FocusableRow 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("<tr><td colspan='6'>Hello World!</td></tr>");
return this;
}
});
var grid = new Backgrid.Grid({
columns: [{
//...
}],
collection: col,
footer: CaptionFooter // <--
});</textarea>
<p>Very often, you'll want to append a paginator to the end
of your table if there are too many rows. For this, there's already
a <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 in the README
file if your extension relies on any libraries other than
Backgrid.js and its dependencies.</li>
<li>When in doubt, look at the other extensions for clues in
organizing your code.</li>
</ul>
</div>
<div class="row-fluid">
<div class="span3">
<h2 id="api-select-all">SelectAll</h2>
<ul class="nav">
<li><a href="api/index.html#!/api/Backgrid.Extension.SelectRowCell">Backgrid.Extension.SelectRowCell</a></li>
<li><a href="api/index.html#!/api/Backgrid.Extension.SelectAllHeaderCell">Backgrid.Extension.SelectAllHeaderCell</a></li>
</ul>
<h3>Events</h3>
<ul class="nav">
<li><a href="api/index.html#!/api/Backgrid.Extension.SelectAllHeaderCell-method-initialize">backgrid:select</a></li>
<li><a href="api/index.html#!/api/Backgrid.Extension.SelectAllHeaderCell-method-initialize">backgrid:selected</a></li>
</ul>
<h4>Best Used On</h4>
<ul>
<li>Desktop</li>
<li>Mobile</li>
</ul>
</div>
<div class="span9">
<h3>When to Use</h3>
<p>When you want to select multiple models at a time for batch operations.</p>