-
Notifications
You must be signed in to change notification settings - Fork 14
Expand file tree
/
Copy pathindex.html
More file actions
573 lines (560 loc) · 27.1 KB
/
index.html
File metadata and controls
573 lines (560 loc) · 27.1 KB
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
<!DOCTYPE html>
<html>
<head>
<title>Backbone.Datagrid</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta name="viewport" content="width=device-width" />
<link rel="stylesheet" href="http://yandex.st/highlightjs/7.3/styles/solarized_dark.min.css" />
<style>
@import url(http://fonts.googleapis.com/css?family=Source+Code+Pro);
body {
margin: 0 auto;
margin-top: 120px;
padding: 0 20px;
max-width: 800px;
font-family: "Helvetica Neue", Helvetica, Arial, sans-serif;
background-color: #eee;
color: #444;
}
h1 {
position: absolute;
top: 0;
left: 0;
width: 100%;
margin: 0;
padding: 30px 0;
background-color: white;
font-weight: normal;
text-align: center;
z-index: -1;
}
h2 {
padding-bottom: 4px;
border-bottom: solid 1px;
}
a {
color: #08c;
text-decoration: none;
}
ul {
padding-left: 20px;
}
code {
font-family: "Source Code Pro",monospace;
font-size: 110%;
overflow-x: auto;
}
</style>
</head>
<body>
<a href="https://github.com/loicfrering/backbone.datagrid"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_green_007200.png" alt="Fork me on GitHub"></a>
<h1>Backbone.Datagrid</h1>
<p><a href="http://loicfrering.github.com/backbone.datagrid/">Backbone.Datagrid</a> is a
powerful component, based on Backbone.View, that displays your Backbone
collections in a dynamic datagrid table. It is highly customizable and
configurable with sensible defaults.</p>
<p>You can refer to the <a href="http://loicfrering.github.com/backbone.datagrid/">project's website</a>
for a nice HTML documentation.</p>
<p><a href="http://travis-ci.org/loicfrering/backbone.datagrid"><img src="https://secure.travis-ci.org/loicfrering/backbone.datagrid.png" alt="Build Status"></a></p>
<h2>Download</h2>
<p>The raw sources can be navigated on <a href="https://github.com/loicfrering/backbone.datagrid">GitHub</a>.
The distributed sources can be found in the <code>dist/</code> directory or
downloaded directly via one of the following links:</p>
<ul>
<li>Production minified version: <a href="https://raw.github.com/loicfrering/backbone.datagrid/v0.3.2/dist/backbone.datagrid.min.js">backbone.datagrid.min.js (v0.3.2)</a>.</li>
<li>Development version: <a href="https://raw.github.com/loicfrering/backbone.datagrid/v0.3.2/dist/backbone.datagrid.js">backbone.datagrid.js (v0.3.2)</a>.</li>
</ul>
<h2>Getting started</h2>
<h3>Usage</h3>
<p>Create a new datagrid with your collection and options, render it and attach
the resulting element to your document:</p>
<pre><code class="lang-javascript"><span class="keyword">var</span> myCollection = <span class="keyword">new</span> MyCollection();
<span class="keyword">var</span> datagrid = <span class="keyword">new</span> Backbone.Datagrid({
collection: myCollection
});
$(<span class="string">'#datagrid'</span>).html(datagrid.el);</code></pre>
<h3>Examples</h3>
<p>You will find all the examples listed on <a href="http://loicfrering.github.com/backbone.datagrid/examples/">this page</a>. Their sources
are available in the <a href="https://github.com/loicfrering/backbone.datagrid/tree/master/examples/">examples</a>
directory of the repository.</p>
<ul>
<li>Solar: a simple and complete example with an in memory collection of planets from the
Solar System.<ul>
<li><a href="http://loicfrering.github.com/backbone.datagrid/examples/solar.html">Live version</a></li>
<li><a href="https://github.com/loicfrering/backbone.datagrid/tree/master/examples/js/solar.js">Sources</a></li>
</ul>
</li>
<li>GitHub: an example with a collection connected to GitHub's REST API.<ul>
<li><a href="http://loicfrering.github.com/backbone.datagrid/examples/github.html">Live version</a></li>
<li><a href="https://github.com/loicfrering/backbone.datagrid/tree/master/examples/js/github.js">Sources</a></li>
</ul>
</li>
</ul>
<h2>Description</h2>
<p>Each component composing the datagrid really are Backbone views. Here is a
description of these different components. You'll also find for each component
(or view), the events that will cause a rendering of the view.</p>
<pre><code> Datagrid
____________________/\____________________
/ \
+----------+----------+----------+----------+ ˥
| Column 1 | Column 2 | Column 3 | Column 4 | } Header
ǂ==========ǂ==========ǂ==========ǂ==========ǂ ˩
| Val 1-1 | Val 1-2 | Val 1-3 | Val 1-4 |
+----------+----------+----------+----------+ ˥
| Val 2-1 | Val 2-2 | Val 2-3 | Val 2-4 | } Row
+----------+---------\+----------+----------+ ˩
| Val 3-1 | Val 3-2 \ Val 3-3 | Val 3-4 |
+----------+----------+\--------\+----------+
| Val 4-1 | Val 4-2 | \al 4-3 \ Val 4-4 |
+----------+----------+--\-------+\---------+
\___ ___\
\/
2 Cells
+---+---+---+---+---+---+ ˥
| « | 1 | 2 | 3 | 4 | » | } Pagination
+---+---+---+---+---+---+ ˩</code></pre>
<h3>Datagrid</h3>
<p>The backbone.datagrid entry point. A Backbone.View that will be responsible for
the entire datagrid management and rendering. It uses the collection passed to
the constructor as its data source. The Datagrid view takes care of creating
the <code>table</code> HTML element and each of the components described below.</p>
<p>Event bindings:</p>
<ul>
<li>collection#reset will cause a rendering of the whole datagrid.</li>
</ul>
<h3>Header</h3>
<p>A Backbone.View for the datagrid's header which is going to render the <code>thead</code>
HTML element. It is also responsible for creating a Cell for each column's
header.</p>
<h3>Row</h3>
<p>A Backbone.View for each row of the datagrid. The Row is responsible for
rendering a row in the table, that is to say a <code>tr</code> HTML element, and for
creating a Cell for each column of the datagrid. The Row uses an entry of the
collection: a model.</p>
<p>Event bindings:</p>
<ul>
<li>model#change will cause a rendering of the row.</li>
</ul>
<h3>Cell</h3>
<p>A Backbone.View for each cell in a Row. One Cell is responsible for rendering a
<code>td</code> (or <code>th</code> for a header) HTML element.</p>
<p>There are specialized cells views extending the base Cell and that allows
custom renderings that suit your needs:</p>
<ul>
<li>Cell<ul>
<li>CallbackCell<ul>
<li>TemplateCell<ul>
<li>UnderscoreTemplateCell (not available yet)</li>
<li>HandlebarsTemplateCell (not available yet)</li>
</ul>
</li>
</ul>
</li>
<li>ActionCell</li>
</ul>
</li>
</ul>
<h2>Datagrid options</h2>
<h3>collection</h3>
<p>The Backbone.Collection that is going to be managed by the datagrid.</p>
<h3>inMemory</h3>
<p>If the collection should be manipulated in memory for pagination and sorting.
Otherwise use REST requests.</p>
<h3>paginated</h3>
<p>Whether or not the datagrid should be paginated.</p>
<h3>tableClassName</h3>
<p>The class attribute for the generated <code>table</code>. Will override
<code>tableAttrs.className</code>.</p>
<h3>rowClassName</h3>
<p>The class attribute for each datagrid's row: <code>tr</code> tags. Can be a simple string
with class names space-separated or a computed string by passing a callback
function. The callback function will be called with the model associated to the
current row. Will override <code>className</code> attribute that may be returned by
<code>rowAttrs</code>.</p>
<h3>emptyMessage</h3>
<p>A nice message to display when the datagrid is empty. Defaults to <code><p>No
results found.</p></code>.</p>
<h3>tableAttrs (object)</h3>
<p>If you provide an object in <code>tableAttrs</code>, they will be used as html
attributes of the generated <code>table</code> element.</p>
<h3>rowAttrs (function)</h3>
<p>Unlike <code>tableAttrs</code>, <code>rowAttr</code> may be a function invoked to generate html
attributes of the generated <code>tr</code> elements.
It's invoked during rendering on each row, with the Corresponding backbone
model as first parameter.
It must return an object.</p>
<pre><code class="lang-javascript"><span class="keyword">var</span> datagrid = <span class="keyword">new</span> Datagrid({
collection: collection,
rowAttrs: <span class="keyword">function</span>(model) {
<span class="keyword">return</span> {<span class="string">'data-id'</span>: model.cid, disabled: <span class="literal">true</span>};
}
...</code></pre>
<h3>columns</h3>
<p>The columns definitions, see the dedicated section below.</p>
<h2>Columns definitions</h2>
<p>You can customize the datagrid with columns definition. It is an array of
definitions, one for each column you want to see in the datagrid. If no
definition is passed to the datagrid, a default column definition is going to
be created for you for each property of the model managed by the collection you
passed to the datagrid.</p>
<p>A column definition can be a string or an object. If a string is passed, a
default column definition will be generated with the specified string used as
the column's property.</p>
<h3>Column definition</h3>
<h4>property (string)</h4>
<p>The model's property that is going to be displayed in the column. Can be
omitted if the column describe a combination of different properties of the
model: please refer to custom views below.</p>
<h4>title (string)</h4>
<p>The title of the column which will be displayed in the table header. If not
defined, the column's property will be used for generating a nicely formated
title, here are some examples:</p>
<ul>
<li>name => Name</li>
<li>events_url => Events Url</li>
<li>issue_events_url => Issue Events Url</li>
</ul>
<h4>sortable (boolean)</h4>
<p>Whether or not the column is sortable. Default to false.</p>
<h4>sortBy (string)</h4>
<p>The column which will be used for sorting, see dedicated sorting section below
for more details.</p>
<h4>comparator (function)</h4>
<p>If the column is sortable, a comparator function that is going to be used to sort
the datagrid by the column. See the dedicated sorting section below for more
informations.</p>
<h4>cellClassName (string|callback)</h4>
<p>The class name of the cell (td or th). It can be a string or a callback which
will be passed the model related to the current row. Will override <code>className</code>
attribute that may be returned by <code>cellAttrs</code>.</p>
<h3>cellAttrs (function)</h3>
<p>May be a function invoked to generate html attributes of the generated <code>td</code>
elements.
It's invoked during rendering on each cell, with the row backbone model as
first parameter.
It must return an object.</p>
<pre><code class="lang-javascript"><span class="keyword">var</span> datagrid = <span class="keyword">new</span> Datagrid({
collection: collection,
columns: [{
property: <span class="string">'foo'</span>,
cellAttrs: <span class="keyword">function</span>(model) {
<span class="keyword">return</span> {<span class="string">'data-id'</span>: model.cid, disabled: <span class="literal">true</span>};
}
...</code></pre>
<h4>view (string|callback|object)</h4>
<p>The CellView that's gonna be used for rendering the column's cell associated to
the current row.</p>
<p>If not defined, the model's attribute corresponding to <code>column.property</code>.</p>
<p>You can pass an <a href="http://underscorejs.org/#template">Underscore template</a> as a
string, it will be compiled and executed with the <code>model.toJSON()</code> as context.</p>
<p>You can also pass a callback function. It will be called with the current row's
model (the Backbone full model) and the return value will be displayed in the cell.</p>
<p>You can finally pass an object to use one of the specific views provided or a
custom view. This object must have a type property which refers to view's type
that gonna be used for the Cell. The other properties are gonna be passed to
the constructor function of the view.</p>
<pre><code class="lang-javascript">{
title: <span class="string">'Edit'</span>,
view: {
type: Backbone.Datagrid.ActionCell,
label: <span class="string">'Edit'</span>,
actionClassName: <span class="string">'btn btn-primary'</span>,
action: <span class="keyword">function</span>(planet) {
alert(<span class="string">'Would edit '</span> + planet.get(<span class="string">'name'</span>) + <span class="string">'!'</span>);
<span class="keyword">return</span> <span class="literal">false</span>;
}
}
}</code></pre>
<h2>Pagination</h2>
<p>By default, pagination controls are displayed for a paginated datagrid. But an
API is also available to manually control pagination. Each of the following
functions causes a datagrid rendering:</p>
<h3>Pager</h3>
<p>The Pager is an object extending Backbone.Model which manages the state of the
pagination for the datagrid.</p>
<h4>datagrid.page(page)</h4>
<p>Go to the specified page. Delegates to:</p>
<pre><code class="lang-javascript">datagrid.pager.page(page);</code></pre>
<h4>datagrid.perPage(perPage)</h4>
<p>Set the number of items displayed per page. Delegates to:</p>
<pre><code class="lang-javascript">datagrid.pager.perPage(perPage);</code></pre>
<h4>datagrid.pager.next()</h4>
<p>Go to the next page.</p>
<h4>datagrid.pager.prev()</h4>
<p>Go to the previous page.</p>
<h4>datagrid.pager.get('currentPage')</h4>
<p>Returns the current page number.</p>
<h4>datagrid.pager.get('perPage')</h4>
<p>Returns the current number of element per page.</p>
<h4>datagrid.pager.hasPrev()</h4>
<p>Tests if the collection has a previous page.</p>
<h4>datagrid.pager.hasNext()</h4>
<p>Tests if the collection has a next page.</p>
<h4>Pager's events</h4>
<p>As Backbone.Model, you can bind <a href="http://backbonejs.org/#FAQ-events">events triggered by any object extending
Backbone.Model</a> if you want to bind some
behavior when the user interact with the pager. You can for example very easily
save the current pager status in the sessionStorage:</p>
<pre><code class="lang-javascript">datagrid.pager.on(<span class="string">'change'</span>, <span class="keyword">function</span>(pager) {
sessionStorage.setItem(<span class="string">'datagrid-current-page'</span>, pager.get(<span class="string">'currentPage'</span>));
sessionStorage.setItem(<span class="string">'datagrid-per-page'</span>, pager.get(<span class="string">'perPage'</span>));
});</code></pre>
<p>Here is another example which observes changes of the current page only:</p>
<pre><code class="lang-javascript">datagrid.pager.on(<span class="string">'change:currentPage'</span>, <span class="keyword">function</span>(pager) {
<span class="comment">// A really convenient alert...</span>
alert(<span class="string">"Hey you are changing page for: "</span> + pager.get(<span class="string">'currentPage'</span>));
});</code></pre>
<h3>In memory</h3>
<p>If the datagrid manages an in memory collection, pagination will be
automatically handled for you by slicing the collection with the right start
and end indexes according to the current page and the number of elements per
page you want to be displayed.</p>
<h3>Server API</h3>
<p>When dealing with a server API, there are two things you need to configure in
your collection for pagination to work properly:</p>
<ul>
<li>set some properties, generally fetched from the API, that will tell the
datagrid if a previous, next or specific page is available to display
relevant pagination controls.</li>
<li>set a <code>data</code> property that will tell the datagrid which request parameters it
needs to send to the server to the specify the current page and the number of
items per page you want.</li>
</ul>
<h4>Configuring pagination controls</h4>
<p>Some of the following properties must be set to the collection:</p>
<ul>
<li><code>hasPrev</code> if there is a previous page to enable a control which links to the
previous page.</li>
<li><code>hasNext</code> if there is a next page to enable a control which links to the next
page.</li>
<li><code>totalPages</code> or <code>total</code> the total number of pages or elements to be able to
display full pagination controls with a link to each of the available pages.</li>
</ul>
<p>In the case you know from the server API the total number of pages or elements,
you just have to set one of these value for the datagrid to be able to display
full pagination controls.</p>
<p>In the case where this information is not available, the datagrid will only be
able to display controls for previous and next page according to the related
hasNext and hasPrev flags.</p>
<p>You will be able to retrieve these informations from the server API you are
dealing with, so the best place to set these properties to the collection is in
<code>collection.parse(resp)</code> which is called by Backbone when fetching from the
server.</p>
<p>For example, if the server API provides the total number of elements by
wrapping the collection:</p>
<pre><code class="lang-javascript">{
total: <span class="number">24</span>
content: [{
foo: <span class="string">'bar'</span>
}, {
foo: <span class="string">'foobar'</span>
}]
}</code></pre>
<p>Here is how you could implement your collection's fetch function:</p>
<pre><code class="lang-javascript">parse: <span class="keyword">function</span>(resp) {
<span class="keyword">this</span>.total = resp.total;
<span class="keyword">return</span> resp.content;
}</code></pre>
<ul>
<li>you first need to store the total number of elements in the collection.</li>
<li>Then you have to return the actual array which gonna be used by Backbone to
populate the collection. See
<a href="http://backbonejs.org/#Collection-parse">collection.parse(resp)</a> for more
details.</li>
</ul>
<p>Here is a second example using GitHub's API with JSON-P:</p>
<pre><code class="lang-javascript">parse: <span class="keyword">function</span>(resp) {
<span class="keyword">this</span>.hasNext = <span class="literal">false</span>;
<span class="keyword">var</span> link = _.find(resp.meta.Link, <span class="keyword">function</span>(link) {
<span class="keyword">if</span> (link[<span class="number">1</span>].rel == <span class="string">'next'</span>) {
<span class="keyword">this</span>.hasNext = <span class="literal">true</span>;
<span class="keyword">return</span> <span class="literal">true</span>;
}
}, <span class="keyword">this</span>);
<span class="keyword">return</span> resp.data;
}</code></pre>
<p>Here we just set an <code>hasNext</code> flag based on the meta link informations provided
by GitHub. As the total number of pages is unknown, only next and previous page
will be available as pagination controls.</p>
<h4>Configuring request parameters</h4>
<p>You have to set the data property in your collection. This can be an object or
a function returning an object. This object will be passed as a data option to
Backone's collection.fetch(options) and finally passed as a query string by
jquery to your server API while fetching a new page.</p>
<p>The pager will be passed to the function so that you will be able to get the
currentPage and the number of element perPage wanted to pass them as query
parameters values. Here is an example (in your collection):</p>
<pre><code class="lang-javascript">data: <span class="keyword">function</span>(pager) {
<span class="keyword">return</span> {
page: pager.get(<span class="string">'currentPage'</span>),
per_page: pager.get(<span class="string">'perPage'</span>)
}
}</code></pre>
<p>Here would be the query string resulted from fetching the 4th page with 10
elements per page:</p>
<pre><code>?page=4&per_page=10</code></pre>
<p>Here is an alternative example that will produce the same query string but by
directly setting an object:</p>
<pre><code class="lang-javascript">data: {
page: <span class="keyword">function</span>(pager) { <span class="keyword">return</span> pager.get(<span class="string">'currentPage'</span>); },
per_page: <span class="number">10</span>
}</code></pre>
<p>Here the number of elements per page is definitely fixed (which is generally
not a good idea).</p>
<h2>Sorting</h2>
<p>Sorted datagrid columns can be sorted by clicking on the column's header cell.
A first click will sort in ascending order, the following clicks will toggle
sorting direction between descending and ascending. You can also control
sorting thanks to the following function.</p>
<h3>Sorter</h3>
<p>As for the Pager, the Sorter is an object extending Backbone.Model. Its role is
to manage the sorting state of the datagrid.</p>
<h4>datagrid.sort(column, [order])</h4>
<p>Sort the datagrid by the specified column in the specified order. The column
can be the column's property name or the column's index (beginning at 0). You
can use <code>Datagrid.Sorter.ASC</code> and <code>Datagrid.Sorter.DESC</code> to specify the
sorting direction.</p>
<p>Delegates to <code>datagrid.sorter.sort(column, [order])</code>.</p>
<h4>sorter.get('column')</h4>
<p>Returns the column which is currently sorted identified by (in order of
priority):</p>
<ul>
<li>sortBy if defined in the column definition.</li>
<li>property if defined in the column definition.</li>
<li>column's index otherwise.</li>
</ul>
<h4>sorter.get('order')</h4>
<p>Returns the sorting direction, can be <code>Datagrid.Sorter.ASC</code> or
<code>Datagrid.Sorter.DESC</code>.</p>
<h4>Sorter's events</h4>
<p>In the same way you can bind events triggered by the Pager, you can also bind
<a href="http://backbonejs.org/#FAQ-events">events triggered by the Sorter</a> (as a
Backbone.Model) and react to sorting state changes.</p>
<pre><code class="lang-javascript">datagrid.sorter.on(<span class="string">'change'</span>, <span class="keyword">function</span>(sorter) {
sessionStorage.setItem(<span class="string">'datagrid-sorted-column'</span>, sorter.get(<span class="string">'column'</span>));
sessionStorage.setItem(<span class="string">'datagrid-sorted-order'</span>, sorter.get(<span class="string">'order'</span>));
});</code></pre>
<h3>In memory</h3>
<p>An in memory collection will be sorted using a comparator function that gonna
be passed to Backbone's <code>collection.sort(options)</code>.</p>
<p>The comparator function is specific to a sortable column and must be specified
in the column's definition. The functions takes two arguments : model1 and
model2 and should follow the specifications of the compareFunction expected for
<a href="https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/sort">Array.sort</a>.</p>
<p>By default the comparator function will be based on
<a href="https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/String/localeCompare">String.localeCompare</a>
for a sensible alphabetical sorting.</p>
<p>Example of a column definition with a custom comparator function:</p>
<pre><code class="lang-javascript">{
property: <span class="string">'rank'</span>,
sortable: <span class="literal">true</span>,
comparator: <span class="keyword">function</span>(p1, p2) {
<span class="keyword">return</span> p1.get(<span class="string">'rank'</span>) - p2.get(<span class="string">'rank'</span>);
}
}</code></pre>
<h3>Server API</h3>
<p>Configuring how the datagrid will pass sorting parameters to the server API is
done in the same way as we configured pagination: using the collection's data
attribute.</p>
<p>In addition to the pager, the sorter is passed as a second parameter to the
functions which generate request parameters data. All you need to do is to map
the request parameters your API is using for sorting to the current sorting
status provided by the datagrid in the sorter.</p>
<p>Here is an example data function implementation in your collection:</p>
<pre><code class="lang-javascript">data: <span class="keyword">function</span>(pager, sorter) {
<span class="keyword">return</span> {
per_page: pager.get(<span class="string">'perPage'</span>),
page: pager.get(<span class="string">'currentPage'</span>),
sort: sorter.get(<span class="string">'column'</span>),
direction: sorter.get(<span class="string">'order'</span>)
};
}</code></pre>
<p>With this configuration, requesting the 4th page with 10 element per page and
sorting by name descendant would produce the following query string:</p>
<pre><code>?page=4&per_page=10&sort=name&direction=desc</code></pre>
<h2>Status</h2>
<p>It is for now in its early stage of developments: the API may be subject to
changes.</p>
<h2>Contributing</h2>
<p><a href="http://gruntjs.com/">Grunt</a> is used for managing the development workflow,
here is how you cant get up everything you need to contribute to
backbone.datagrid:</p>
<ol>
<li>Install <a href="http://nodejs.org/download/">Node.js</a>.</li>
<li>Clone the project:<pre><code>$ git clone https://github.com/loicfrering/backbone.datagrid.git
$ cd backbone.datagrid</code></pre>
</li>
<li>Install dependencies with npm:<pre><code>$ npm install -g grunt-cli
$ npm install</code></pre>
</li>
<li>Use Grunt for:<ul>
<li>Linting and testing:<pre><code>$ grunt test</code></pre>
</li>
<li>Building:<pre><code>$ grunt dist</code></pre>
</li>
</ul>
</li>
</ol>
<h2>Changelog</h2>
<h3>0.4.0-beta.1</h3>
<ul>
<li>The full Backbone.Model is passed to the CallbackCell's callback function
instead of the serialized JSON.</li>
<li>You can now use the TemplateCell if you need the serialized JSON (for a
compiled template function).</li>
<li>Update Backbone to 1.0.0.</li>
<li>Fix some memory leaks.</li>
<li>Introduce configurable controls with:<ul>
<li>Pagination control</li>
<li>ItemsPerPage control.</li>
</ul>
</li>
</ul>
<h3>0.3.2</h3>
<ul>
<li>Fix an issue that caused useless Ajax calls.</li>
<li>Display a nice message when the datagrid is empty.</li>
<li>Support Backbone 0.9.10.</li>
<li>Bower support: backbone.datagrid is now a Bower package and can be installed
via <code>bower install backbone.datagrid</code>.</li>
</ul>
<h3>0.3.1</h3>
<ul>
<li>Datagrid is now responsible for rendering itself.</li>
<li>Improve GitHub example: an input field allows to enter the username.</li>
<li>Bug fixes in datagrid's preparation.</li>
</ul>
<h3>0.3.0</h3>
<ul>
<li>Support server API with request based pagination and sorting.</li>
<li>New example based on GitHub's API which demonstrate server API support.</li>
<li>Add a tableClassName option.</li>
<li>Minor bug fixes.</li>
</ul>
<h3>0.2.0</h3>
<ul>
<li>Group Datagrid objects in Backbone.Datagrid namespace.</li>
<li>Release a dedicated <a href="http://loicfrering.github.com/backbone.datagrid/">Backbone.Datagrid</a>
web page with resources and documentation.</li>
</ul>
<h3>0.1.0</h3>
<ul>
<li>Initial backbone.datagrid release.</li>
<li>Manages in memory collections.</li>
</ul>
<h2>License</h2>
<p>Copyright (c) 2012 <a href="https://github.com/loicfrering">Loïc Frering</a>, licensed
under the MIT license. See the LICENSE file for more informations.</p>
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-36838775-1']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
</body>
</html>