← Back to branch summary

~smagoun/whoopsie/whoopsie-lp1017637

« back to all changes in this revision

Viewing changes to backend/stats/static/js/yui/docs/datatable/index.html

  • Committer: Evan Dandrea
  • Date: 2012-05-09 05:53:45 UTC
  • Revision ID: evan.dandrea@canonical.com-20120509055345-z2j41tmcbf4as5uf
The backend now lives in lp:daisy and the website (errors.ubuntu.com) now lives in lp:errors.

Show diffs side-by-side

added added

removed removed

Lines of Context:
backend/stats/static/js/yui/docs/datatable/index.html
1
 
<!DOCTYPE html>
2
 
<html lang="en">
3
 
<head>
4
 
    <meta charset="utf-8">
5
 
    <title>DataTable</title>
6
 
    <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Maven+Pro:400,700">
7
 
    <link rel="stylesheet" href="../../build/cssgrids/grids-min.css">
8
 
    <link rel="stylesheet" href="../assets/css/main.css">
9
 
    <link rel="stylesheet" href="../assets/vendor/prettify/prettify-min.css">
10
 
    <script src="../../build/yui/yui-min.js"></script>
11
 
</head>
12
 
<body>
13
 
 
14
 
<div id="doc">
15
 
    <h1>DataTable</h1>
16
 
 
17
 
    
18
 
        <a href="#toc" class="jump">Jump to Table of Contents</a>
19
 
    
20
 
 
21
 
    <div class="yui3-g">
22
 
        <div class="yui3-u-3-4">
23
 
            <div id="main">
24
 
                <div class="content"><style type="text/css">
25
 
    td code {
26
 
        white-space: nowrap;
27
 
        background: #fcfbfa;
28
 
        border: 1px solid #d0d5ec;
29
 
        padding: 0 3px;
30
 
    }
31
 
    .yui3-datatable table {
32
 
        width: auto;
33
 
    }
34
 
 
35
 
    .yui3-datatable td, .yui3-datatable th {
36
 
        border: 0 none;
37
 
    }
38
 
 
39
 
    .yui3-datatable-col-Module {
40
 
        white-space: nowrap;
41
 
    }
42
 
 
43
 
    .yui3-skin-sam .yui3-datatable-message-content {
44
 
        background: #fff;
45
 
        border-bottom: 0 none;
46
 
    }
47
 
 
48
 
    .notice {
49
 
        background: #faf3d1;
50
 
        border: 1px solid #eac9a9;
51
 
        -moz-border-radius: 3px;
52
 
        -webkit-border-radius: 3px;
53
 
        border-radius: px;
54
 
        padding: 0 1em;
55
 
        -moz-box-shadow: 0 0 5px #ccc8b3;
56
 
        -webkit-box-shadow: 0 0 5px #ccc8b3;
57
 
        box-shadow: 0 0 5px #ccc8b3;
58
 
        margin-bottom: 1em;
59
 
    }
60
 
    .notice h2 {
61
 
        margin-top: .6em;
62
 
    }
63
 
</style>
64
 
 
65
 
<div class="intro component">
66
 
    <p>
67
 
        The DataTable widget is responsible for rendering columnar data into a
68
 
        highly customizable and fully accessible HTML table.  The core
69
 
        functionality of DataTable is to visualize structured data as a table.
70
 
        A variety of class extensions can then be used to add features to the
71
 
        table such as sorting and scrolling.
72
 
    </p>
73
 
</div>
74
 
                                
75
 
<h2 id="getting-started">Getting Started</h2>
76
 
 
77
 
<p>
78
 
To include the source files for DataTable and its dependencies, first load
79
 
the YUI seed file if you haven't already loaded it.
80
 
</p>
81
 
 
82
 
<pre class="code prettyprint">&lt;script src=&quot;http:&#x2F;&#x2F;yui.yahooapis.com&#x2F;3.5.0&#x2F;build&#x2F;yui&#x2F;yui-min.js&quot;&gt;&lt;&#x2F;script&gt;</pre>
83
 
 
84
 
 
85
 
<p>
86
 
Next, create a new YUI instance for your application and populate it with the
87
 
modules you need by specifying them as arguments to the <code>YUI().use()</code> method.
88
 
YUI will automatically load any dependencies required by the modules you
89
 
specify.
90
 
</p>
91
 
 
92
 
<pre class="code prettyprint">&lt;script&gt;
93
 
&#x2F;&#x2F; Create a new YUI instance and populate it with the required modules.
94
 
YUI().use(&#x27;datatable&#x27;, function (Y) {
95
 
    &#x2F;&#x2F; DataTable is available and ready for use. Add implementation
96
 
    &#x2F;&#x2F; code here.
97
 
});
98
 
&lt;&#x2F;script&gt;</pre>
99
 
 
100
 
 
101
 
<p>
102
 
For more information on creating YUI instances and on the
103
 
<a href="http://yuilibrary.com/yui/docs/api/classes/YUI.html#method_use"><code>use()</code> method</a>, see the
104
 
documentation for the <a href="../yui/index.html">YUI Global Object</a>.
105
 
</p>
106
 
 
107
 
 
108
 
<div class="notice">
109
 
    <h2 id="migration-intro">Upgrading from version 3.4.1 or older?</h2>
110
 
 
111
 
    <p>
112
 
        DataTable was refactored for 3.5.0.  Some APIs were changed in backward
113
 
        incompatible ways.
114
 
    </p>
115
 
    
116
 
    <p>
117
 
        Read the <a href="migration.html">3.5.0 Migration Guide</a> for tips to
118
 
        avoid unpleasant surprises.  If you still run into issues, please
119
 
        <a href="../../../projects/yui3/newticket/">file a ticket</a>.
120
 
    </p>
121
 
 
122
 
    <p>
123
 
        If you are unable to upgrade due to unresolvable issues, you can use the
124
 
        <a href="../datatable-deprecated/index.html"><code>datatable-deprecated</code></a>
125
 
        module suite, which is equivalent to the 3.4.1 implementation.  But be
126
 
        aware that these modules will be removed in a future version of YUI.
127
 
    </p>
128
 
</div>
129
 
 
130
 
<h2 id="using">DataTable Basics</h2>
131
 
 
132
 
<p>
133
 
    A basic DataTable is made of columns and rows. Define the columns you
134
 
    want to display in your DataTable with the <code>columns</code> attribute. Rows are
135
 
    created for you based on the data you provide to the <code>data</code> attribute.
136
 
</p>
137
 
 
138
 
<p>
139
 
    Under the hood, the DataTable class uses a
140
 
    <a href="../model-list/index.html">ModelList</a> instance to manage the row
141
 
    data properties.  Read the <a href="#data">Table Data Configuration</a>
142
 
    section below for details about how to load, configure, and work with the
143
 
    table data.
144
 
</p>
145
 
 
146
 
<pre class="code prettyprint">&#x2F;&#x2F; Columns must match data object property names
147
 
var data = [
148
 
    { id: &quot;ga-3475&quot;, name: &quot;gadget&quot;,   price: &quot;$6.99&quot;, cost: &quot;$5.99&quot; },
149
 
    { id: &quot;sp-9980&quot;, name: &quot;sprocket&quot;, price: &quot;$3.75&quot;, cost: &quot;$3.25&quot; },
150
 
    { id: &quot;wi-0650&quot;, name: &quot;widget&quot;,   price: &quot;$4.25&quot;, cost: &quot;$3.75&quot; }
151
 
];
152
 
 
153
 
var table = new Y.DataTable({
154
 
    columns: [&quot;id&quot;, &quot;name&quot;, &quot;price&quot;],
155
 
    data: data,
156
 
 
157
 
    &#x2F;&#x2F; Optionally configure your table with a caption
158
 
    caption: &quot;My first DataTable!&quot;,
159
 
 
160
 
    &#x2F;&#x2F; and&#x2F;or a summary (table attribute)
161
 
    summary: &quot;Example DataTable showing basic instantiation configuration&quot;
162
 
});
163
 
 
164
 
table.render(&quot;#example&quot;);</pre>
165
 
 
166
 
 
167
 
<p>This code produces this table:</p>
168
 
 
169
 
<div id="basic-example" class="yui3-skin-sam"></div>
170
 
 
171
 
<script>
172
 
YUI({ filter: 'raw' }).use('datatable-base', function (Y) {
173
 
    // Columns must match data object property names
174
 
    var data = [
175
 
        { id: "ga-3475", name: "gadget",   price: "$6.99", cost: "$5.99" },
176
 
        { id: "sp-9980", name: "sprocket", price: "$3.75", cost: "$3.25" },
177
 
        { id: "wi-0650", name: "widget",   price: "$4.25", cost: "$3.75" }
178
 
    ];
179
 
 
180
 
    var table = new Y.DataTable({
181
 
        columns: ["id", "name", "price"],
182
 
        data: data,
183
 
        caption: "My first DataTable!",
184
 
        summary: "Example DataTable showing basic instantiation configuration"
185
 
    });
186
 
 
187
 
    table.render("#basic-example");
188
 
});
189
 
</script>
190
 
 
191
 
<h2 id="columns">Column Configuration</h2>
192
 
 
193
 
<p>
194
 
    The <code>columns</code> attribute takes an array of field names that correspond to
195
 
    property names in the <code>data</code> objects.  These field names are called "keys".
196
 
    As long as these keys exist in your data, DataTable will display the
197
 
    values in the table.  By default, the key is also used as the label of the
198
 
    column header.
199
 
</p>
200
 
 
201
 
 
202
 
<p>
203
 
    Use objects instead of key strings to customize how the cells in a column
204
 
    display.
205
 
</p>
206
 
 
207
 
<pre class="code prettyprint">&#x2F;&#x2F; Columns must match data object property names
208
 
var data = [
209
 
    { id: &quot;ga-3475&quot;, name: &quot;gadget&quot;,   price: &quot;$6.99&quot;, cost: &quot;$5.99&quot; },
210
 
    { id: &quot;sp-9980&quot;, name: &quot;sprocket&quot;, price: &quot;$3.75&quot;, cost: &quot;$3.25&quot; },
211
 
    { id: &quot;wi-0650&quot;, name: &quot;widget&quot;,   &#x2F;* missing *&#x2F;   cost: &quot;$3.75&quot; }
212
 
];
213
 
 
214
 
var table = new Y.DataTable({
215
 
    columns: [
216
 
        &quot;id&quot;,
217
 
        { key: &quot;name&quot;, label: &quot;part name&quot; },
218
 
        { key: &quot;price&quot;, allowHTML: true, emptyCellValue: &quot;&lt;em&gt;(not set)&lt;&#x2F;em&gt;&quot; },
219
 
        &quot;cost&quot;
220
 
    ],
221
 
    data: data
222
 
});
223
 
 
224
 
table.render(&quot;#example&quot;);</pre>
225
 
 
226
 
 
227
 
<p>This code produces this table:</p>
228
 
 
229
 
<div id="column-example1" class="yui3-skin-sam"></div>
230
 
 
231
 
<script>
232
 
YUI().use('datatable-base', function (Y) {
233
 
    // Columns must match data object property names
234
 
    var data = [
235
 
        { id: "ga-3475", name: "gadget",   price: "$6.99", cost: "$5.99" },
236
 
        { id: "sp-9980", name: "sprocket", price: "$3.75", cost: "$3.25" },
237
 
        { id: "wi-0650", name: "widget",                   cost: "$3.75" }
238
 
    ];
239
 
 
240
 
    var table = new Y.DataTable({
241
 
        columns: [
242
 
            "id",
243
 
            { key: "name", label: "part name" },
244
 
            { key: "price", allowHTML: true, emptyCellValue: "<em>(not set)</em>" },
245
 
            "cost"
246
 
        ],
247
 
        data: data
248
 
    });
249
 
 
250
 
    table.render("#column-example1");
251
 
});
252
 
</script>
253
 
 
254
 
<p>
255
 
    Some column configurations affect the table headers and others affect the
256
 
    data cells.
257
 
</p>
258
 
 
259
 
<p>
260
 
    Use the <code>key</code> property to reference the associated data field when
261
 
    configuring columns with objects.  Other supported configuration
262
 
    properties are listed in <a href="#column-config">Appendix A</a> below.
263
 
</p>
264
 
 
265
 
 
266
 
<h3 id="nested">Stacked Column Headers</h3>
267
 
 
268
 
<p>
269
 
    Use the <code>children</code> column configuration to create multiple rows of column
270
 
    headers.
271
 
</p>
272
 
 
273
 
<pre class="code prettyprint">var columns = [
274
 
    &#x27;username&#x27;,
275
 
    {
276
 
        &#x2F;&#x2F; Important: Parent columns do NOT get a key...
277
 
 
278
 
        &#x2F;&#x2F; but DO get a label
279
 
        label: &quot;Access&quot;,
280
 
 
281
 
        &#x2F;&#x2F; Pass an array of column configurations (strings or objects) as children
282
 
        children: [
283
 
            &#x27;read&#x27;,
284
 
            &#x27;write&#x27;,
285
 
        ]
286
 
    }
287
 
];
288
 
 
289
 
var data = [
290
 
    { username: &quot;root&quot;, read: true, write: true },
291
 
    { username: &quot;spilgrim&quot;, read: true, write: false },
292
 
    { username: &quot;fizzgig&quot;, read: false, write: false }
293
 
];
294
 
 
295
 
var table = new Y.DataTable({
296
 
    columns: columns,
297
 
    data   : data
298
 
}).render(&quot;#example&quot;);</pre>
299
 
 
300
 
 
301
 
<p>This code produces this table:</p>
302
 
 
303
 
<div id="nested-example" class="yui3-skin-sam"></div>
304
 
 
305
 
<script>
306
 
YUI().use('datatable-base', function (Y) {
307
 
var data = [
308
 
    { username: "root", read: true, write: true },
309
 
    { username: "spilgrim", read: true, write: false },
310
 
    { username: "fizzgig", read: false, write: false }
311
 
];
312
 
 
313
 
var table = new Y.DataTable({
314
 
    columns: [
315
 
        'username',
316
 
        {
317
 
            // Important: Parent columns do NOT get a key...
318
 
 
319
 
            // but DO get a label
320
 
            label: "Access",
321
 
 
322
 
            // Pass an array of column configurations (strings or objects) as children
323
 
            children: [
324
 
                'read',
325
 
                'write'
326
 
            ]
327
 
        }
328
 
    ],
329
 
    data   : data
330
 
}).render("#nested-example");
331
 
});
332
 
</script>
333
 
 
334
 
<p>
335
 
    <code>children</code> takes an array of column configurations, just like the <code>columns</code>
336
 
    attribute itself. The columns defined in the <code>children</code> property will have
337
 
    header cells rendered below the parent column's header.
338
 
</p>
339
 
 
340
 
<p>
341
 
    Columns that have <code>children</code> don't relate directly to the data cells in the
342
 
    table rows, so they <strong>should not</strong> have a <code>key</code> configured.
343
 
    They should, however, include a <code>label</code> to provide the header's content.
344
 
</p>
345
 
 
346
 
<h3 id="formatters">Formatting Cell Data</h3>
347
 
 
348
 
<p>
349
 
    To customize the display of cell data in a column, DataTable provides the
350
 
    <code>formatter</code> and <code>nodeFormatter</code> column configurations.  Both configurations
351
 
    accept functions, but <code>formatter</code> will also accept a template string.
352
 
</p>
353
 
 
354
 
<p>
355
 
    <code>formatter</code>s are expected to return the string content to populate each
356
 
    cell in that column, and <code>nodeFormatter</code>s are provided with the cell Nodes
357
 
    and expected to populate them using the Node API.
358
 
</p>
359
 
 
360
 
<p>
361
 
    For best performance, <strong><a href="#formatter-vs-nodeformatter">avoid
362
 
    <code>nodeFormatter</code>s unless absolutely necessary</a></strong>.
363
 
</p>
364
 
 
365
 
<pre class="code prettyprint">var columns = [
366
 
    &#x27;item&#x27;,
367
 
    {
368
 
        key: &#x27;cost&#x27;,
369
 
        formatter: &#x27;${value}&#x27; &#x2F;&#x2F; formatter template string
370
 
    },
371
 
    {
372
 
        key: &#x27;price&#x27;,
373
 
        formatter: function (o) {
374
 
            if (o.value &gt; 3) {
375
 
                o.className += &#x27; yellow-background&#x27;;
376
 
            }
377
 
 
378
 
            return &#x27;$&#x27; + o.value.toFixed(2);
379
 
        }
380
 
    },
381
 
    {
382
 
        label: &#x27;profit&#x27;,
383
 
        nodeFormatter: function (o) {
384
 
            var profit = o.data.price - o.data.cost,
385
 
                prefix = &#x27;$&#x27;,
386
 
                row;
387
 
 
388
 
            if (profit &lt; 0) {
389
 
                prefix = &#x27;-&#x27; + prefix;
390
 
                profit = Math.abs(profit);
391
 
                row = o.cell.ancestor();
392
 
 
393
 
                o.cell.addClass(&#x27;negative&#x27;);
394
 
 
395
 
                &#x2F;&#x2F; Assign a rowspan to the first cell and add a new row
396
 
                &#x2F;&#x2F; below this one to span the last three columns
397
 
                row.one(&#x27;td&#x27;).setAttribute(&#x27;rowspan&#x27;, 2);
398
 
 
399
 
                row.insert(
400
 
                    &#x27;&lt;tr class=&quot;auth&quot;&gt;&lt;td colspan=&quot;3&quot;&gt;&#x27; +
401
 
                        &#x27;&lt;button class=&quot;ok&quot;&gt;authorize&lt;&#x2F;button&gt;&#x27; +
402
 
                        &#x27;&lt;button class=&quot;stop&quot;&gt;discontinue&lt;&#x2F;button&gt;&#x27; +
403
 
                    &#x27;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;&#x27;,
404
 
                    &#x27;after&#x27;);
405
 
            }
406
 
 
407
 
            o.cell.set(&#x27;text&#x27;, prefix + profit.toFixed(2));
408
 
        }
409
 
    }
410
 
];</pre>
411
 
 
412
 
 
413
 
<p>This code produces this table:</p>
414
 
 
415
 
<div id="formatter-example" class="yui3-skin-sam">
416
 
    <style scoped>
417
 
        .yui3-datatable .yui3-datatable-data .expensive {
418
 
            background-color: #ffe;
419
 
        }
420
 
        .yui3-skin-sam .yui3-datatable-data .auth td {
421
 
            border-bottom: 1px dashed #cbcbcb;
422
 
        }
423
 
        .negative {
424
 
            color: #700;
425
 
            font-weight: 700;
426
 
        }
427
 
        tr.auth td {
428
 
            text-align: right;
429
 
            background-color: #fff;
430
 
            border-top: 1px dashed #cbcbcb;
431
 
            border-left: 1px solid #cbcbcb;
432
 
            padding-right: 5px;
433
 
        }
434
 
    </style>
435
 
</div>
436
 
 
437
 
<script>
438
 
YUI().use('datatable-base', function (Y) {
439
 
    var columns = [
440
 
        'item',
441
 
        {
442
 
            key: 'cost',
443
 
            formatter: '${value}' // formatter template string
444
 
        },
445
 
        {
446
 
            key: 'price',
447
 
            formatter: function (o) {
448
 
                if (o.value > 10) {
449
 
                    o.className += ' expensive';
450
 
                }
451
 
 
452
 
                return '$' + o.value.toFixed(2);
453
 
            }
454
 
        },
455
 
        {
456
 
            label: 'profit',
457
 
            nodeFormatter: function (o) {
458
 
                var profit = o.data.price - o.data.cost,
459
 
                    prefix = '$',
460
 
                    row;
461
 
 
462
 
                if (profit < 0) {
463
 
                    prefix = '-' + prefix;
464
 
                    profit = Math.abs(profit);
465
 
                    row = o.cell.ancestor();
466
 
 
467
 
                    o.cell.addClass('negative');
468
 
 
469
 
                    row.one('td').setAttribute('rowspan', 2);
470
 
 
471
 
                    row.insert(
472
 
                        '<tr class="auth"><td colspan="3">' +
473
 
                            '<button class="ok">authorize</button>' +
474
 
                            '<button class="stop">discontinue</button>' +
475
 
                        '</td></tr>',
476
 
                        'after');
477
 
                }
478
 
 
479
 
                o.cell.setContent(prefix + profit.toFixed(2));
480
 
            }
481
 
        }
482
 
    ];
483
 
 
484
 
    var data = [
485
 
        { item: "widget",   cost: 23.57, price: 47.5 },
486
 
        { item: "gadget",   cost: 0.11, price: 6.99 },
487
 
        { item: "sprocket", cost: 4.08, price: 3.75 },
488
 
        { item: "nut",      cost: 0.01, price: 0.25 }
489
 
    ];
490
 
 
491
 
    var table = new Y.DataTable({
492
 
        columns: columns,
493
 
        data   : data
494
 
    }).render("#formatter-example");
495
 
});
496
 
</script>
497
 
 
498
 
<p>
499
 
    The parameters passed to <code>formatter</code> functions and <code>nodeFormatter</code>
500
 
    functions are described in <a href="#formatter-props">Appendix B</a> and <a
501
 
    href="#nodeformatter-props">Appendix C</a>, respectively.
502
 
</p>
503
 
 
504
 
<p>
505
 
    <strong>Note</strong>: It's highly recommended to keep the data in the
506
 
    underlying <code>data</code> ModelList as pure data, free from presentational
507
 
    concerns.  For example, use real numbers, not numeric strings, and store
508
 
    link urls and labels either in separate data fields or in a single data
509
 
    field, but as separate properties of a value object.  This allows the data
510
 
    to be used for calculations such as sorting or averaging.
511
 
</p>
512
 
 
513
 
<h4 id="formatter-function">Setting content with <code>formatter</code> functions</h4>
514
 
 
515
 
<p>
516
 
    Set the cell content with column <code>formatter</code>s by returning the desired
517
 
    content string from the function.  Alternately, just update <code>o.value</code> with
518
 
    the new value in the object passed as an argument to the <code>formatter</code>.  When
519
 
    updating <code>o.value</code> <em>do not include a return statement</em>.
520
 
</p>
521
 
 
522
 
<p>
523
 
    <code>formatters</code> are very powerful because not only do they have access to the
524
 
    record's value for that column's field, but they also receive the rest of
525
 
    the record's data, the record Model instance itself, and the column
526
 
    configuration object.  This allows you to include any extra configurations
527
 
    in your column configuration that might be useful to customizing how cells
528
 
    in the column are rendered.
529
 
</p>
530
 
 
531
 
<pre class="code prettyprint">function currency(o) {
532
 
    return Y.DataType.number.format(o.value, {
533
 
        prefix            : o.column.currencySymbol     || &#x27;$&#x27;,
534
 
        decimalPlaces     : o.column.decimalPlaces      || 2,
535
 
        decimalSeparator  : o.column.decimalSeparator   || &#x27;.&#x27;,
536
 
        thousandsSeparator: o.column.thousandsSeparator || &#x27;,&#x27;
537
 
    });
538
 
}
539
 
 
540
 
var cols = [
541
 
    { key: &quot;price&quot;, formatter: currency, decimalPlaces: 3 },
542
 
    ...</pre>
543
 
 
544
 
 
545
 
<p>
546
 
    See <a href="#formatter-props">Appendix B</a> for a list of all properties
547
 
    passed to <code>formatter</code> functions.
548
 
</p>
549
 
 
550
 
<h4 id="nodeformatters">Setting content with <code>nodeFormatter</code> functions</h4>
551
 
 
552
 
<p>
553
 
    Unlike <code>formatters</code> which can effectively default to the normal rendering
554
 
    logic by leaving <code>o.value</code> unchanged, <code>nodeFormatters</code> must assign content
555
 
    to the cells themselves.  The cell's initial classes will be set up, but
556
 
    that's it.  Everything else is your responsibility.
557
 
</p>
558
 
 
559
 
<p>
560
 
    <strong><code>nodeFormatter</code>s should return <code>false</code></strong>.
561
 
    <a href="formatter-vs-nodeformatter">See below</a> for details.
562
 
</p>
563
 
 
564
 
<p>
565
 
    While there are <a href="#formatter-vs-nodeformatter">few scenarios that
566
 
    require <code>nodeFormatter</code>s</a>, they do have the benefits of having the Node
567
 
    API for constructing more complex DOM subtrees and the ability to access
568
 
    all nodes in the <code>&lt;tbody&gt;</code>. This means they can reference, and even modify,
569
 
    cells in other rows.
570
 
</p>
571
 
 
572
 
<p>
573
 
    Like <code>formatters</code>, <code>nodeFormatters</code> are provided with the data field value,
574
 
    the record data, the record Model instance, and the column configuration
575
 
    object.
576
 
</p>
577
 
    
578
 
<p>
579
 
    See <a href="#nodeformatter-props">Appendix C</a> for a list of all
580
 
    properties passed to <code>nodeFormatter</code> functions.
581
 
</p>
582
 
 
583
 
<h4 id="formatter-vs-nodeformatter">Why <code>formatter</code> and <code>nodeFormatter</code>?</h4>
584
 
 
585
 
<p>
586
 
    For good rendering performance and memory management, DataTable creates
587
 
    table content by assembling <code>innerHTML</code> strings from templates, with
588
 
    <code>{placeholder}</code> tokens replaced with your data.  However, this means that
589
 
    the Nodes don't exist yet when a column's <code>formatter</code>s are applied.
590
 
</p>
591
 
 
592
 
<p>
593
 
    To minimize the need to create Nodes for each cell, the default rendering
594
 
    logic supports the addition of cell classes as well as row classes via
595
 
    <code>formatter</code> functions.  Event subscriptions should be
596
 
    <a href="http://yuilibrary.com/yui/docs/event/delegation.html">delegated</a>
597
 
    from the DataTable instance itself using the
598
 
    <a href="http://yuilibrary.com/yui/docs/api/classes/DataTable.html#method_delegate"><code>delegate()</code> method</a>.
599
 
</p>
600
 
 
601
 
<p>
602
 
    On the rare occasion that you <em>must</em> use Nodes to supply the cell
603
 
    data, DataTable allows a second pass over the generated DOM elements once
604
 
    the initial string concatenation has been completed and the full HTML
605
 
    content created.
606
 
</p>
607
 
 
608
 
<p>
609
 
    It is important to note that <code>nodeFormatters</code> will necessarily create a
610
 
    Node instance for each cell in that column, which will increase the memory
611
 
    footprint of your application.  If the Node instance wrappers around the
612
 
    DOM elements don't need to be maintained beyond the life of the
613
 
    <code>nodeFormatter</code>, return <code>false</code> to remove them from the internal object
614
 
    cache.  <strong>This will not remove the rendered DOM, but it will remove
615
 
    event subscriptions made on those Nodes</strong>.
616
 
</p>
617
 
 
618
 
<p>
619
 
    In general, <code>nodeFormatter</code>s should only be used if absolutely necessary,
620
 
    and should <em>always return <code>false</code></em>.
621
 
</p>
622
 
 
623
 
<h4 id="formatters-vs-empty">Formatters vs. <code>emptyCellValue</code></h4>
624
 
 
625
 
<p>
626
 
    The <code>emptyCellValue</code> configuration is useful to provide fallback content in
627
 
    the case of missing or empty column data, but it interacts with each type of
628
 
    formatter differently.
629
 
</p>
630
 
 
631
 
<p>
632
 
    String formatters will only be applied if the field data for that cell is
633
 
    not <code>undefined</code>.  This allows the <code>emptyCellValue</code> to populate the cell.
634
 
</p>
635
 
 
636
 
<p>
637
 
    Function formatters are applied before the return value or (potentially
638
 
    altered) <code>o.value</code> property is tested for <code>undefined</code>, <code>null</code>, or the empty
639
 
    string.  In any of these cases, the <code>emptyCellValue</code> populates the cell.
640
 
</p>
641
 
 
642
 
<p>
643
 
    The <code>emptyCellValue</code> configuration is ignored by columns configured with
644
 
    <code>nodeFormatter</code>s.
645
 
</p>
646
 
 
647
 
 
648
 
<h2 id="data">Table Data Configuration</h2>
649
 
 
650
 
<p>
651
 
    Each record in the table is stored as a
652
 
    <a href="../model/index.html">Model</a> instance, where the
653
 
    keys of the record objects become Model attributes.  This allows you to
654
 
    interact with the models as you would any other <a
655
 
    href="../base/index.html">Base</a>-based class, with <code>get(attr)</code>,
656
 
    <code>set(attr, value)</code>, and subscribing to attribute change events.
657
 
</p>
658
 
 
659
 
<pre class="code prettyprint">var data = [
660
 
    { item: &quot;widget&quot;,   cost: 23.57, price: 47.5 },
661
 
    { item: &quot;gadget&quot;,   cost: 0.11, price: 6.99 },
662
 
    { item: &quot;sprocket&quot;, cost: 4.08, price: 3.75 },
663
 
    { item: &quot;nut&quot;,      cost: 0.01, price: 0.25 }
664
 
];
665
 
 
666
 
var table = new Y.DataTable({
667
 
    columns: [&quot;item&quot;, &quot;cost&quot;, &quot;price&quot;],
668
 
    data: data
669
 
});
670
 
 
671
 
var sprocket = table.getRecord(2);
672
 
 
673
 
&#x2F;&#x2F; Fires a costChange event, and the table is updated if rendered
674
 
sprocket.set(&#x27;cost&#x27;, 2.65);</pre>
675
 
 
676
 
 
677
 
<p>
678
 
    The Model class used to store the record data is created for you, based on
679
 
    the objects in the <code>data</code> array.  If <code>data</code> is not set, the column keys
680
 
    identified in the <code>columns</code> configuration is used.
681
 
</p>
682
 
 
683
 
<h3 id="recordtype">Specifying the Record Model</h3>
684
 
 
685
 
<p>
686
 
    To use a custom Model for your records, pass your Model subclass to the
687
 
    <code>recordType</code> attribute.
688
 
</p>
689
 
 
690
 
<pre class="code prettyprint">var pieTable = new Y.DataTable({
691
 
    recordType: Y.PieModel,
692
 
    columns: [&#x27;slices&#x27;, &#x27;type&#x27;],
693
 
    data: [
694
 
        &#x2F;&#x2F; Y.PieModel has attributes &#x27;slices&#x27;, which defaults to 6, and &#x27;type&#x27;,
695
 
        &#x2F;&#x2F; which defaults to &#x27;apple&#x27;. Records can use these defaults.
696
 
        { type: &#x27;lemon meringue&#x27; },
697
 
        { type: &#x27;chocolate creme&#x27;, slices: 8 },
698
 
        {} &#x2F;&#x2F; equivalent to { type: &#x27;apple&#x27;, slices: 6 }
699
 
    ]
700
 
});
701
 
 
702
 
&#x2F;&#x2F; Y.PieModel has its idAttribute assigned to &#x27;type&#x27;, overriding the default
703
 
&#x2F;&#x2F; of &#x27;id&#x27;.  Fetch a PieModel by its id.
704
 
var applePie = pieTable.getRecord(&#x27;apple&#x27;);
705
 
 
706
 
&#x2F;&#x2F; eatSlice is a method on the Y.PieModel prototype
707
 
applePie.eatSlice();</pre>
708
 
 
709
 
 
710
 
<p>
711
 
    Alternately, <code>recordType</code> will accept an array of attribute strings or an
712
 
    <code>ATTRS</code> configuration object to make it easier to create custom attribute
713
 
    behaviors without needing to explicitly build the Model subclass.
714
 
</p>
715
 
 
716
 
<p>
717
 
    If the <code>columns</code> configuration is omitted, but the <code>recordType</code> is set, the
718
 
    <code>columns</code> will default to the <code>recordType</code>'s attributes.
719
 
</p>
720
 
 
721
 
<pre class="code prettyprint">var data = [
722
 
    { item: &quot;widget&quot;,   cost: 23.57, price: 47.5 },
723
 
    { item: &quot;gadget&quot;,   cost: 0.11, price: 6.99 },
724
 
    { item: &quot;sprocket&quot;, cost: 4.08, price: 3.75 },
725
 
    { item: &quot;nut&quot;,      cost: 0.01, price: 0.25 }
726
 
];
727
 
 
728
 
&#x2F;&#x2F; Effectively synonymous with setting the columns attribute if no special
729
 
&#x2F;&#x2F; column configuration is needed.
730
 
var table = new Y.DataTable({
731
 
    recordType: [ &#x27;item&#x27;, &#x27;cost&#x27;, &#x27;price&#x27; ],
732
 
    data: data
733
 
});
734
 
 
735
 
&#x2F;&#x2F; Or for more control, pass an ATTRS configuration object
736
 
var table = new Y.DataTable({
737
 
    recordType: {
738
 
        item: {},
739
 
        cost: {
740
 
            value: 0,
741
 
            setter: function (val) { return +val || 0; }
742
 
        },
743
 
        price: {
744
 
            valueFn: function () { return (this.get(&#x27;cost&#x27;) + 0.1) * 10; },
745
 
            setter: function (val) { return +val || 0; }
746
 
        }
747
 
    },
748
 
    data: data
749
 
});</pre>
750
 
 
751
 
 
752
 
<p>
753
 
    When the table data is loaded asychronously, it is often a good idea to
754
 
    configure the <code>recordType</code>.  This can prevent the generation of a record
755
 
    Model that is missing fields that are omitted from the <code>columns</code>
756
 
    configuration because they aren't intended for viewing.
757
 
</p>
758
 
 
759
 
<h3 id="modellist">The <code>data</code> ModelList</h3>
760
 
 
761
 
<p>
762
 
    The record Models are stored in a
763
 
    <a href="../model-list/index.html">ModelList</a>, which is assigned to the
764
 
    <code>data</code> <em>property</em> on the instance (for easier access than going through <code>table.get(&#x27;data&#x27;)</code>).
765
 
</p>
766
 
 
767
 
<pre class="code prettyprint">var records = [
768
 
    { item: &quot;widget&quot;,   cost: 23.57, price: 47.5 },
769
 
    { item: &quot;gadget&quot;,   cost: 0.11, price: 6.99 },
770
 
    { item: &quot;sprocket&quot;, cost: 4.08, price: 3.75 }
771
 
];
772
 
 
773
 
var table = new Y.DataTable({
774
 
    columns: [&quot;item&quot;, &quot;cost&quot;, &quot;price&quot;],
775
 
    data   : records
776
 
});
777
 
 
778
 
&#x2F;&#x2F; Add a new Model using the ModelList API. This will fire
779
 
&#x2F;&#x2F; events and change the table if rendered.
780
 
table.data.add({ item: &quot;nut&quot;, cost: 0.01, price: 0.25 });</pre>
781
 
 
782
 
 
783
 
<p>
784
 
    When assigning the DataTable's <code>data</code> attribute with an array, a ModelList
785
 
    is created for you.  But you can also pass a ModelList instance if you are
786
 
    sharing a ModelList between widgets on the page, or you have created custom
787
 
    Model and ModelList classes with additional logic, such as adding a
788
 
    <a href="../model-list/#implementing-a-list-sync-layer">data sync layer</a>.
789
 
</p>
790
 
 
791
 
<pre class="code prettyprint">var table = new Y.DataTable({
792
 
    columns: [&#x27;type&#x27;, &#x27;slices&#x27;],
793
 
    data: new Y.PieList()
794
 
});
795
 
 
796
 
&#x2F;&#x2F; The Y.PieList class implements a sync layer, enabling its load() method
797
 
table.data.load(function () {
798
 
    table.render(&#x27;#pies&#x27;);
799
 
});</pre>
800
 
 
801
 
 
802
 
<h3 id="getting-data">Getting Remote Table Data</h3>
803
 
 
804
 
<p>
805
 
    To fetch remote data, you have three options:
806
 
</p>
807
 
 
808
 
<ol>
809
 
    <li>
810
 
        <p>
811
 
            <strong>For quick one-offs</strong>, you can load and parse the
812
 
            data manually, using <code>Y.io(...)</code>, <code>Y.jsonp(...)</code>, etc., then assign
813
 
            that data to the DataTable's <code>data</code> attribute.  This isn't very
814
 
            elegant or maintainable, so is best avoided for anything other than
815
 
            proofs of concept.
816
 
        </p>
817
 
    </li>
818
 
    <li>
819
 
        <p>
820
 
            <strong>For the most control</strong>, better maintainability, and
821
 
            better encapsulation of business logic, create Model and ModelList
822
 
            subclasses that
823
 
            <a href="../model-list/#implementing-a-list-sync-layer">implement a
824
 
            sync layer</a> as suggested above.
825
 
        </p>
826
 
    </li>
827
 
    <li>
828
 
        <p>
829
 
            <strong>For common read-only scenarios</strong>, use the
830
 
            <a href="http://yuilibrary.com/yui/docs/api/classes/Plugin.DataTableDataSource.html"><code>Y.Plugin.DataTableDataSource</code></a>
831
 
            plugin to bind your table to a
832
 
            <a href="../datasource/index.html"><code>DataSource</code></a> instance.  Use
833
 
            plugins to add DataSource features.
834
 
        </p>
835
 
    </li>
836
 
</ol>
837
 
 
838
 
 
839
 
<pre class="code prettyprint">&#x2F;&#x2F; Create a JSONP DataSource to query YQL
840
 
var myDataSource = new Y.DataSource.Get({
841
 
    source: &#x27;http:&#x2F;&#x2F;query.yahooapis.com&#x2F;v1&#x2F;public&#x2F;yql?format=json&amp;&#x27; +
842
 
            &#x27;env=store%3A%2F%2Fdatatables.org%2Falltableswithkeys&amp;q=&#x27;
843
 
});
844
 
 
845
 
myDataSource.plug(Y.Plugin.DataSourceJSONSchema, {
846
 
        schema: {
847
 
            resultListLocator: &#x27;query.results.Result&#x27;,
848
 
            resultFields: [
849
 
                &#x27;Title&#x27;,
850
 
                &#x27;Phone&#x27;,
851
 
                {
852
 
                    &#x2F;&#x2F; Important that record fields NOT include &quot;.&quot;, so
853
 
                    &#x2F;&#x2F; extract nested data with locators
854
 
                    key: &#x27;Rating&#x27;,
855
 
                    locator: &quot;Rating.AverageRating&quot;
856
 
                }
857
 
            ]
858
 
        }
859
 
    })
860
 
    .plug(Y.Plugin.DataSourceCache, {
861
 
        max: 3
862
 
    });
863
 
 
864
 
&#x2F;&#x2F; No data is provided at construction because it will load via the
865
 
&#x2F;&#x2F; DataTableDataSource plugin
866
 
var table = new Y.DataTable({
867
 
    columns: [&#x27;Title&#x27;, &#x27;Phone&#x27;, &#x27;Rating&#x27;],
868
 
    summary: &#x27;Pizza places near 98089&#x27;
869
 
});
870
 
 
871
 
table.plug(Y.Plugin.DataTableDataSource, {
872
 
    datasource: myDataSource
873
 
})
874
 
 
875
 
&#x2F;&#x2F; Initially render an empty table and show a loading message
876
 
table.render(&#x27;#pizza&#x27;)
877
 
     .showMessage(&#x27;loadingMessage&#x27;);
878
 
 
879
 
&#x2F;&#x2F; Load the data into the table
880
 
table.datasource.load({
881
 
    request: encodeURIComponent(
882
 
        &#x27;select *&#x27; +
883
 
        &#x27; from   local.search&#x27; +
884
 
        &#x27; where  zip=&quot;94089&quot;&#x27; +
885
 
        &#x27; and    query=&quot;pizza&quot;&#x27;);
886
 
});</pre>
887
 
 
888
 
 
889
 
<h2 id="features">DataTable Modules and Features</h2>
890
 
 
891
 
<p>
892
 
    For a basic, stripped down <code>Y.DataTable</code> class, include the <code>datatable-base</code>
893
 
    module in your <code>use()</code>.
894
 
</p>
895
 
 
896
 
<p>
897
 
    Feature modules, such as <code>datatable-sort</code>, will bring in <code>datatable-base</code>
898
 
    automatically.  By including only feature modules in your <code>use()</code>, you will
899
 
    get a <code>Y.DataTable</code> that supports specifically those features, without
900
 
    extra code for other features you won't be using.
901
 
</p>
902
 
 
903
 
<p>
904
 
    The <code>datatable</code> module is a bundle of <code>datatable-base</code> plus a set of common
905
 
    feature modules.  Other feature modules need to be included explicitly in
906
 
    <code>use()</code>.
907
 
</p>
908
 
 
909
 
<table>
910
 
<thead>
911
 
    <tr>
912
 
        <th>Module</th>
913
 
        <th>Description</th>
914
 
        <th>In <code>datatable</code>?</th>
915
 
    </tr>
916
 
</thead>
917
 
<tbody>
918
 
    <tr>
919
 
        <td><a href="http://yuilibrary.com/yui/docs/api/modules/datatable-core.html"><code>datatable-core</code></a></td>
920
 
        <td>
921
 
            The core API for DataTable, implemented as a class extension, used
922
 
            by <code>datatable-base</code> to create <code>Y.DataTable</code> and <code>Y.DataTable.Base</code>.
923
 
        </td>
924
 
        <td>yes</td>
925
 
    </tr>
926
 
    <tr>
927
 
        <td><a href="http://yuilibrary.com/yui/docs/api/modules/datatable-base.html"><code>datatable-base</code></a></td>
928
 
        <td>
929
 
            Creates the <code>Y.DataTable</code> and <code>Y.DataTable.Base</code> classes, and
930
 
            defaults the <code>headerView</code> and <code>bodyView</code> to <code>Y.DataTable.HeaderView</code>
931
 
            and <code>Y.DataTable.BodyView</code> respectively.
932
 
        </td>
933
 
        <td>yes</td>
934
 
    </tr>
935
 
    <tr>
936
 
        <td><a href="http://yuilibrary.com/yui/docs/api/modules/datatable-head.html"><code>datatable-head</code></a></td>
937
 
        <td>
938
 
            Creates the <code>Y.DataTable.HeaderView</code> class as a subclass of
939
 
            <code>Y.View</code>.  DataTable defers rendering of the <code>&lt;thead&gt;</code> content to
940
 
            this View when it is passed as the DataTable's <code>headerView</code>
941
 
            attribute (the default, as set by <code>datatable-base</code>).
942
 
        </td>
943
 
        <td>yes</td>
944
 
    </tr>
945
 
    <tr>
946
 
        <td><a href="http://yuilibrary.com/yui/docs/api/modules/datatable-body.html"><code>datatable-body</code></a></td>
947
 
        <td>
948
 
            Creates the <code>Y.DataTable.BodyView</code> class as a subclass of
949
 
            <code>Y.View</code>.  DataTable defers rendering of the <code>&lt;tbody&gt;</code> content to
950
 
            this View when it is passed as the DataTable's <code>bodyView</code>
951
 
            attribute (the default, as set by <code>datatable-base</code>).
952
 
        </td>
953
 
        <td>yes</td>
954
 
    </tr>
955
 
    <tr>
956
 
        <td><a href="http://yuilibrary.com/yui/docs/api/modules/datatable-message.html"><code>datatable-message</code></a></td>
957
 
        <td>
958
 
            Creates the <code>Y.DataTable.Message</code> class extension and adds
959
 
            <code>showMessage</code> and <code>hideMessage</code> methods to <code>Y.DataTable</code>.
960
 
        </td>
961
 
        <td>yes</td>
962
 
    </tr>
963
 
    <tr>
964
 
        <td><a href="http://yuilibrary.com/yui/docs/api/modules/datatable-column-widths.html"><code>datatable-column-widths</code></a></td>
965
 
        <td>
966
 
            Creates the <code>Y.DataTable.ColumnWidths</code> class extension, and adds 
967
 
            support for the <code>width</code> property in column configuration objects
968
 
            to <code>Y.DataTable</code>.
969
 
        </td>
970
 
        <td>yes</td>
971
 
    </tr>
972
 
    <tr>
973
 
        <td><a href="http://yuilibrary.com/yui/docs/api/modules/datatable-mutable.html"><code>datatable-mutable</code></a></td>
974
 
        <td>
975
 
            Creates the <code>Y.DataTable.Mutable</code> class extension and adds methods
976
 
            such as <code>addRow</code>, <code>removeRow</code>, and <code>moveColumn</code> to <code>Y.DataTable</code>.
977
 
        </td>
978
 
        <td>yes</td>
979
 
    </tr>
980
 
    <tr>
981
 
        <td><a href="http://yuilibrary.com/yui/docs/api/modules/datatable-sort.html"><code>datatable-sort</code></a></td>
982
 
        <td>
983
 
            Creates the <code>Y.DataTable.Sort</code> class extension and adds methods
984
 
            <code>sort</code> and <code>toggleSort</code> as well as attributes <code>sortable</code> and
985
 
            <code>sortBy</code> to <code>Y.DataTable</code>.  Enables sorting the table rows by
986
 
            clicking on column headers.
987
 
        </td>
988
 
        <td>yes</td>
989
 
    </tr>
990
 
    <tr>
991
 
        <td><a href="http://yuilibrary.com/yui/docs/api/modules/datatable-datasource.html"><code>datatable-datasource</code></a></td>
992
 
        <td>
993
 
            Creates the <code>Y.Plugin.DataTableDataSource</code> plugin for binding a
994
 
            DataSource instance to the table as its source of record data.
995
 
        </td>
996
 
        <td>yes</td>
997
 
    </tr>
998
 
    <tr>
999
 
        <td><a href="http://yuilibrary.com/yui/docs/api/modules/datatable-scroll.html"><code>datatable-scroll</code></a></td>
1000
 
        <td>
1001
 
            Creates the <code>Y.DataTable.Scroll</code> class extension and adds attribute
1002
 
            <code>scrollable</code> to <code>Y.DataTable</code>.  Adds support for vertically and/or
1003
 
            horizontally scrolling table rows within fixed table dimensions.
1004
 
        </td>
1005
 
        <td>no</td>
1006
 
    </tr>
1007
 
</tbody>
1008
 
</table>
1009
 
 
1010
 
<h3 id="base">Features in <code>DataTable.Base</code></h3>
1011
 
 
1012
 
<p>
1013
 
    By including only <code>datatable-base</code> in your <code>use()</code> line, you get both
1014
 
    <code>Y.DataTable</code> and <code>Y.DataTable.Base</code> classes.  With no other module
1015
 
    inclusion, these classes are effectively the same.  When additional
1016
 
    DataTable related modules are included, those modules' features will
1017
 
    usually be added to <code>Y.DataTable</code>, but <strong>never</strong> to
1018
 
    <code>Y.DataTable.Base</code>.
1019
 
</p>
1020
 
 
1021
 
<p>
1022
 
    Though it can be instantiated, the purpose of <code>Y.DataTable.Base</code> is
1023
 
    primarily as a superclass to a custom DataTable implementation that has a
1024
 
    locked set of features that will not be modified, as <code>Y.DataTable</code> can be,
1025
 
    by the inclusion of other modules.
1026
 
</p>
1027
 
 
1028
 
<pre class="code prettyprint">&#x2F;&#x2F; Create a custom DataTable that includes only the core set of APIs, plus
1029
 
&#x2F;&#x2F; sorting and message support.
1030
 
Y.MyDataTable = Y.Base.create(&#x27;myTable&#x27;, Y.DataTable.Base,
1031
 
    [ Y.DataTable.Sort, Y.DataTable.Message ]);
1032
 
 
1033
 
Y.use(&#x27;datatable-scroll&#x27;, function (Y) {
1034
 
    &#x2F;&#x2F; Y.DataTable now has support for scrolling
1035
 
    var table = new Y.DataTable({ scrollable: &#x27;y&#x27;, ... });
1036
 
 
1037
 
    &#x2F;&#x2F; Y.MyDataTable does not (the config does nothing)
1038
 
    var myTable = new Y.MyDataTable({ scrollable: &#x27;y&#x27;, ... });
1039
 
});</pre>
1040
 
 
1041
 
 
1042
 
<p>
1043
 
    <code>Y.DataTable.Base</code> includes the <code>columns</code>, <code>data</code>, <code>caption</code>, and other
1044
 
    basic table attributes, the underlying ModelList and View rendering
1045
 
    architecture, as well as methods to fetch rows and cells or columns and
1046
 
    records.
1047
 
</p>
1048
 
 
1049
 
<p>
1050
 
    Rendering features include most column configurations, such as <code>children</code>
1051
 
    and <code>allowHTML</code>, as well as column formatting options <code>formatter</code>,
1052
 
    <code>nodeFormatter</code>, <code>cellTemplate</code>, etc.
1053
 
</p>
1054
 
 
1055
 
<h3 id="datatable-message">Table Messages</h3>
1056
 
 
1057
 
<p>
1058
 
    The <code>datatable-message</code> module adds the ability to display a message in the
1059
 
    table body.  By default, the "emptyMessage" will display when the table's
1060
 
    ModelList has no data records.  The message will hide when data is added.
1061
 
</p>
1062
 
 
1063
 
<pre class="code prettyprint">var table = new Y.DataTable({
1064
 
    columns: [&quot;id&quot;, &quot;name&quot;, &quot;price&quot;],
1065
 
    data: []
1066
 
}).render(&#x27;#example&#x27;);</pre>
1067
 
 
1068
 
 
1069
 
<p>This code produces this table:</p>
1070
 
 
1071
 
<div id="message-example" class="yui3-skin-sam"></div>
1072
 
 
1073
 
<script>
1074
 
YUI({ filter: 'raw' }).use('datatable-message', function (Y) {
1075
 
    var table = new Y.DataTable({
1076
 
        columns: ["id", "name", "price"],
1077
 
        data: []
1078
 
    }).render('#message-example');
1079
 
});
1080
 
</script>
1081
 
 
1082
 
<p>
1083
 
    Use <code>table.showMessage(&quot;message&quot;)</code> and <code>table.hideMessage()</code> to toggle the
1084
 
    message display.
1085
 
</p>
1086
 
 
1087
 
<p>
1088
 
    <code>showMessage</code> supports internationalized strings by using a few named
1089
 
    strings, which are registered in the language packs for the
1090
 
    <code>datatable-message</code> module .  These strings are currently:
1091
 
</p>
1092
 
 
1093
 
<ul>
1094
 
    <li>
1095
 
        <code>table.showMessage(&quot;emptyMessage&quot;)</code> defaults to "No data to display".
1096
 
    </li>
1097
 
    <li>
1098
 
        <code>table.showMessage(&quot;loadingMessage&quot;)</code> defaults to "Loading...".
1099
 
    </li>
1100
 
</ul>
1101
 
 
1102
 
<p>
1103
 
    Other values passed to <code>showMessage</code> will pass that content directly
1104
 
    through to the message Node.
1105
 
</p>
1106
 
 
1107
 
<h3 id="colwidths">Column Width Configuration</h3>
1108
 
 
1109
 
<p>
1110
 
    The <code>datatable-column-widths</code> module adds basic support for specifying
1111
 
    column widths.
1112
 
</p>
1113
 
 
1114
 
<pre class="code prettyprint">var table = new Y.DataTable({
1115
 
    columns: [
1116
 
        { key: &#x27;item&#x27;, width: &#x27;125px&#x27; },
1117
 
        { key: &#x27;cost&#x27;, formatter: &#x27;${value}&#x27; },
1118
 
        ...
1119
 
    ],
1120
 
    data   : data
1121
 
}).render(&quot;#example&quot;);</pre>
1122
 
 
1123
 
 
1124
 
<p>This code produces this table:</p>
1125
 
 
1126
 
<div id="colwidths-example" class="yui3-skin-sam"></div>
1127
 
 
1128
 
<script>
1129
 
YUI({ filter: 'raw' }).use('datatable-column-widths', function (Y) {
1130
 
    var data = [
1131
 
        { item: "widget",   cost: 23.57, price: 47.5 },
1132
 
        { item: "gadget",   cost: 0.11, price: 6.99 },
1133
 
        { item: "sprocket", cost: 4.08, price: 3.75 },
1134
 
        { item: "nut",      cost: 0.01, price: 0.25 }
1135
 
    ];
1136
 
 
1137
 
    var table = new Y.DataTable({
1138
 
        columns: [
1139
 
            { key: 'item', width: '125px' },
1140
 
            { key: 'cost', formatter: '${value}' },
1141
 
            { key: 'price', formatter: '${value}' },
1142
 
            { key: 'profit', formatter: function (o) {
1143
 
                    var price = o.data.price,
1144
 
                        cost  = o.data.cost;
1145
 
 
1146
 
                    return (((price - cost) / cost) * 100).toFixed(2) + '%';
1147
 
                }
1148
 
            }
1149
 
        ],
1150
 
        data   : data
1151
 
    }).render("#colwidths-example");
1152
 
});
1153
 
</script>
1154
 
 
1155
 
<p>
1156
 
    <strong>CAVEAT</strong>: Column widths will expand beyond the configured
1157
 
    value if column cells contain data that is long and can't line-wrap.  Also,
1158
 
    column widths may be reduced below the configured value if the table width
1159
 
    (by configuring the DataTable's <code>width</code> attribute, or constrained by a
1160
 
    narrow containing element) is too narrow to fit all data at the configured
1161
 
    widths.
1162
 
</p>
1163
 
 
1164
 
<p>
1165
 
    To force column widths, including cell data truncation and allowing the
1166
 
    table to spill beyond its configured or inherited width, wrap the cell
1167
 
    content in a <code>&lt;div&gt;</code> either by configuring the column's <code>formatter</code> or
1168
 
    <code>cellTemplate</code>, then assign the <code>&lt;div&gt;</code>'s CSS style with the desired width
1169
 
    (or "inherit"), plus <code>overflow: hidden;</code>.  Then set the DataTable column's
1170
 
    <code>width</code> configuration accordingly.
1171
 
</p>
1172
 
 
1173
 
<h3 id="sorting">Column sorting</h3>
1174
 
 
1175
 
<p>
1176
 
    The <code>datatable-sort</code> module adds support for sorting the table rows either
1177
 
    through the added APIs or by clicking on the table headers.
1178
 
</p>
1179
 
 
1180
 
<p>
1181
 
    By default, when <code>datatable-sort</code> is included, DataTables will inspects
1182
 
    the <code>columns</code> objects, looking for <code>sortable: true</code> to enable table sorting
1183
 
    by those columns, triggered by clicking on their respective headers.
1184
 
</p>
1185
 
<pre class="code prettyprint">var cols = [
1186
 
    { key: &quot;Company&quot;, sortable: true },
1187
 
    { key: &quot;Phone&quot; },
1188
 
    { key: &quot;Contact&quot;, sortable: true }
1189
 
];</pre>
1190
 
 
1191
 
 
1192
 
<p>
1193
 
    For convenience, you can enable header-click sorting for all columns by
1194
 
    setting the <code>sortable</code> attribute to <code>true</code>, or pass an array of column keys
1195
 
    to enable just those column's headers.
1196
 
</p>
1197
 
 
1198
 
<pre class="code prettyprint">&#x2F;&#x2F; Set all columns to be sortable
1199
 
var table = new Y.DataTable({
1200
 
    columns: [&quot;Company&quot;, &quot;Phone&quot;, &quot;Contact&quot;],
1201
 
    data: ...
1202
 
    sortable: true
1203
 
}).render(&quot;#example&quot;);</pre>
1204
 
 
1205
 
 
1206
 
<p>This code produces this table:</p>
1207
 
 
1208
 
<div id="sort-example1" class="yui3-skin-sam"></div>
1209
 
 
1210
 
<script>
1211
 
YUI({ filter: 'raw' }).use('datatable-sort', function (Y) {
1212
 
    var table = new Y.DataTable({
1213
 
        columns: ['Company', 'Phone', 'Contact'],
1214
 
        data: [
1215
 
            { Company: "Company Bee", Phone: "415-555-1234", Contact: "Sally Spencer"},
1216
 
            { Company: "Acme Company", Phone: "650-555-4444", Contact: "John Jones"},
1217
 
            { Company: "Indutrial Industries", Phone: "408-555-5678", Contact: "Robin Smith"}
1218
 
        ],
1219
 
        sortable: true
1220
 
    }).render('#sort-example1');
1221
 
});
1222
 
</script>
1223
 
 
1224
 
<p>
1225
 
    Hold down the <code>shift</code> key while clicking on column headers to subsort by
1226
 
    that column.  Doing so repeatedly will toggle the subsort direction.
1227
 
</p>
1228
 
 
1229
 
<p>
1230
 
    As long as the <code>datatable-sort</code> module has been included, you will always
1231
 
    be able to sort the table data through the API, even by columns that aren't
1232
 
    configured to accept header-click sorting.
1233
 
</p>
1234
 
 
1235
 
<p>
1236
 
    When a table is sorted, any new records added to the DataTable's ModelList
1237
 
    will be inserted at the proper sorted index, as will the created table
1238
 
    rows.
1239
 
</p>
1240
 
 
1241
 
<p>
1242
 
    Disable header-click sorting by setting <code>sortable</code> to <code>false</code>.
1243
 
</p>
1244
 
 
1245
 
<h4 id="customsort">Custom Sorting</h4>
1246
 
 
1247
 
<p>
1248
 
    Assign a function to a column's <code>sortFn</code> to support customized sorting.  The
1249
 
    function will receive the two records being compared and a boolean flag
1250
 
    indicating a descending sort was requested.
1251
 
</p>
1252
 
 
1253
 
<pre class="code prettyprint">var columns = [
1254
 
    {
1255
 
        key: &#x27;id&#x27;,
1256
 
        label: &#x27;&amp;#9679;&#x27;, &#x2F;&#x2F; a big dot
1257
 
        formatter: function (o) {
1258
 
            return o.value ? &#x27;&#x27; : &#x27;&amp;#9679;&#x27;; &#x2F;&#x2F; only new records have a dot
1259
 
        },
1260
 
        sortable: true,
1261
 
        sortFn: function (a, b, desc) {
1262
 
            var aid   = a.get(&#x27;id&#x27;),
1263
 
                bid   = b.get(&#x27;id&#x27;),
1264
 
                acid  = a.get(&#x27;clientId&#x27;),
1265
 
                bcid  = b.get(&#x27;clientId&#x27;),
1266
 
                order = &#x2F;&#x2F; existing records are equivalent
1267
 
                        (aid &amp;&amp; bid) ? 0 :
1268
 
                        &#x2F;&#x2F; new records are grouped apart from existing records
1269
 
                        (aid &amp;&amp; -1) || (bid &amp;&amp; 1) ||
1270
 
                        &#x2F;&#x2F; new records are sorted by insertion order
1271
 
                        (acid &gt; bcid) ? 1 : -(acid &lt; bcid);
1272
 
 
1273
 
            return desc ? -order : order;
1274
 
        }
1275
 
    },
1276
 
    ...</pre>
1277
 
 
1278
 
 
1279
 
<p>
1280
 
    The function must return 1, 0, or -1.  1 specifies that the Model passed as
1281
 
    the first parameter should sort below the Model passed as the second
1282
 
    parameter.  -1 for above, and 0 if they are equivalent for the purpose of
1283
 
    this sort.
1284
 
</p>
1285
 
 
1286
 
 
1287
 
<h4 id="sortapi">Sorting Methods</h4>
1288
 
 
1289
 
<p>
1290
 
    To sort the table in the code, call <code>table.sort(NAME OR KEY)</code>.  To
1291
 
    toggle the sort direction, call <code>table.toggleSort(NAME OR KEY)</code>.
1292
 
</p>
1293
 
 
1294
 
<pre class="code prettyprint">&#x2F;&#x2F; Sorts the table by values in the price field in ascending order
1295
 
table.sort(&#x27;price&#x27;);
1296
 
 
1297
 
&#x2F;&#x2F; Flips to descending
1298
 
table.toggleSort(&#x27;price&#x27;);</pre>
1299
 
 
1300
 
 
1301
 
<p>
1302
 
    To sort by multiple columns, pass an array of column keys to <code>sort</code> or
1303
 
    <code>toggleSort</code>.
1304
 
</p>
1305
 
 
1306
 
<p>
1307
 
    Calling <code>toggleSort</code> with no arguments will reverse all current sort
1308
 
    directions.  Calling with specific column names or keys will toggle only
1309
 
    those columns.
1310
 
</p>
1311
 
 
1312
 
<pre class="code prettyprint">&#x2F;&#x2F; Sort first by author, subsort by title in ascending order
1313
 
table.sort([&#x27;author&#x27;, &#x27;title&#x27;]);
1314
 
 
1315
 
&#x2F;&#x2F; Now descending by author then title
1316
 
&#x2F;&#x2F; same as table.toggleSort([&#x27;author&#x27;, &#x27;title&#x27;]);
1317
 
table.toggleSort();
1318
 
 
1319
 
&#x2F;&#x2F; Now ascending by author, descending by title
1320
 
table.toggleSort(&#x27;author&#x27;);</pre>
1321
 
 
1322
 
 
1323
 
<p>
1324
 
    To specify a sort direction, pass an object instead of a string to <code>sort</code>.
1325
 
    The object should have the column name as the key, and sort direction as its
1326
 
    value.
1327
 
</p>
1328
 
 
1329
 
<pre class="code prettyprint">&#x2F;&#x2F; Explicitly sort by price in descending order
1330
 
table.sort({ price: &#x27;desc&#x27; });
1331
 
 
1332
 
&#x2F;&#x2F; Each column gets its own object
1333
 
table.sort([{ author: &#x27;desc&#x27; }, { title: &#x27;desc&#x27; }]);</pre>
1334
 
 
1335
 
 
1336
 
<p>
1337
 
    Acceptable values for the sort direction are "asc", "desc", 1, and -1. 1 is
1338
 
    equivalent to "asc", and -1 to "desc".
1339
 
</p>
1340
 
 
1341
 
<h4 id="sortby">The <code>sortBy</code> Attribute</h4>
1342
 
 
1343
 
<p>
1344
 
    Every sort operation updates the <code>sortBy</code> attribute.  You can also trigger
1345
 
    a sort by setting this attribute directly.  It accepts the same values as
1346
 
    the <code>sort</code> method.
1347
 
</p>
1348
 
 
1349
 
<pre class="code prettyprint">&#x2F;&#x2F; Sort by author in descending order, then by title in ascending order
1350
 
table.set(&#x27;sortBy&#x27;, [{ author: -1 }, &#x27;title&#x27;]);</pre>
1351
 
 
1352
 
 
1353
 
<p>
1354
 
    To specify an initial sort order for your table, assign this attribute
1355
 
    during instantiation.  This will sort the data as soon as it is added
1356
 
    to the table's ModelList.
1357
 
</p>
1358
 
 
1359
 
<pre class="code prettyprint">&#x2F;&#x2F; Pre-sort the data
1360
 
var table = new Y.DataTable({
1361
 
    columns: [&#x27;item&#x27;, &#x27;cost&#x27;, &#x27;price&#x27;],
1362
 
    data: [...],
1363
 
    sortBy: { price: -1 }
1364
 
});</pre>
1365
 
 
1366
 
 
1367
 
<h4 id="sortevent">The <code>sort</code> Event</h4>
1368
 
 
1369
 
<p>
1370
 
    Clicking on a column header, or calling the <code>sort</code> or <code>toggleSort</code> methods
1371
 
    will fire a <code>sort</code> method containing an <code>e.sortBy</code> property that
1372
 
    corresponds to the requested sort column and direction.  The value will be
1373
 
    in either string or object format, depending on how each method was used.
1374
 
</p>
1375
 
 
1376
 
<p>
1377
 
    Preventing the <code>sort</code> event will prevent the <code>sortBy</code> attribute from being
1378
 
    updated.  Updating the <code>sortBy</code> attribute directly will not fire the <code>sort</code>
1379
 
    event, but will still sort the data and update the table.
1380
 
</p>
1381
 
 
1382
 
<h3 id="mutation">Table Mutation APIs (<code>addRow</code>, etc)</h3>
1383
 
 
1384
 
<p>
1385
 
    The <code>datatable-mutable</code> module adds APIs for adding, removing, and
1386
 
    modifying records and columns.
1387
 
</p>
1388
 
 
1389
 
<h4 id="column-mutation">Column Mutation Methods</h4>
1390
 
 
1391
 
<p>
1392
 
    Use the methods <code>addColumn</code>, <code>removeColumn</code>, <code>modifyColumn</code>, and
1393
 
    <code>moveColumn</code> to update the table's configured <code>columns</code>.
1394
 
</p>
1395
 
 
1396
 
<pre class="code prettyprint">&#x2F;&#x2F; Insert a column for the profit field in the data records as the third column
1397
 
table.addColumn(&#x27;profit&#x27;, 2);
1398
 
 
1399
 
&#x2F;&#x2F; Actually, make that the fourth column
1400
 
table.moveColumn(&#x27;profit&#x27;, 3);
1401
 
 
1402
 
&#x2F;&#x2F; Actually, strike that.  Don&#x27;t show it after all
1403
 
table.removeColumn(&#x27;profit&#x27;);
1404
 
 
1405
 
&#x2F;&#x2F; Instead, add a formatter to the price column that includes the profit data
1406
 
table.modifyColumn(&#x27;price&#x27;, {
1407
 
    formatter: function (o) {
1408
 
        return o.value + &#x27; (&#x27; + (o.data.profit &#x2F; o.data.cost).toFixed(2) + &#x27;%)&#x27;;
1409
 
    }
1410
 
});</pre>
1411
 
 
1412
 
 
1413
 
<p>
1414
 
    Each column mutation method fires an identically named event.  See
1415
 
    <a href="http://yuilibrary.com/yui/docs/api/classes/DataTable.html">the API docs</a> for details.
1416
 
</p>
1417
 
 
1418
 
<h4 id="row-mutation">Row Mutation Methods</h4>
1419
 
 
1420
 
<p>
1421
 
    Use the methods <code>addRow</code>, <code>addRows</code>, <code>removeRow</code>, and <code>modifyRow</code> to update
1422
 
    the table's ModelList.
1423
 
</p>
1424
 
 
1425
 
<pre class="code prettyprint">table.addRow({ item: &#x27;collet&#x27;, cost: 0.42, price: 2.65 });
1426
 
 
1427
 
table.addRows([
1428
 
    { item: &#x27;nut&#x27;,    cost: 0.42, price: 2.65 },
1429
 
    { item: &#x27;washer&#x27;, cost: 0.01, price: 0.08 },
1430
 
    { item: &#x27;bit&#x27;,    cost: 0.19, price: 0.97 }
1431
 
]);
1432
 
 
1433
 
&#x2F;&#x2F; Remove table records by their Model, id, clientId, or index
1434
 
table.removeRow(0);
1435
 
 
1436
 
&#x2F;&#x2F; Modify a record by passing its id, clientId, or index, followed by an
1437
 
&#x2F;&#x2F; object with new field values
1438
 
table.modifyRow(&#x27;record_4&#x27;, { cost: 0.74 });</pre>
1439
 
 
1440
 
<p>
1441
 
    Everything that's done by these methods can be accomplished through the
1442
 
    table's ModelList instance methods, but having methods on the table itself
1443
 
    can make the code more readable.
1444
 
</p>
1445
 
 
1446
 
<pre class="code prettyprint">&#x2F;&#x2F; Same as table.addRow(...);
1447
 
table.data.add({ item: &#x27;collet&#x27;, cost: 0.42, price: 2.65 });</pre>
1448
 
 
1449
 
 
1450
 
<p>
1451
 
    By default, changes made to the table are only local, they don't update the
1452
 
    server or other data origin if the data was served remotely.  However, if
1453
 
    your table's ModelList is built with a sync layer, the mutation methods
1454
 
    can also trigger the appropriate sync behavior by passing an additional
1455
 
    argument to the methods, an object with the property <code>sync</code> set to <code>true</code>.
1456
 
</p>
1457
 
 
1458
 
<pre class="code prettyprint">&#x2F;&#x2F; Tell the server we&#x27;re down to one slice of apple pie!
1459
 
table.modifyRow(&#x27;apple&#x27;, { slices: 1 }, { sync: true });
1460
 
 
1461
 
&#x2F;&#x2F; Uh oh, make that 0.  No more apple pie :(
1462
 
table.removeRow(&#x27;apple&#x27;, { sync: true });</pre>
1463
 
 
1464
 
 
1465
 
<p>
1466
 
    If all modifications are destined for the server/origin, you can set the
1467
 
    <code>autoSync</code> attribute to <code>true</code>, and the row mutation methods will
1468
 
    automatically call into the sync layer.
1469
 
</p>
1470
 
 
1471
 
<pre class="code prettyprint">var pies = new Y.DataTable({
1472
 
    columns: [&#x27;type&#x27;, &#x27;slices&#x27;],
1473
 
    data: new Y.PieList()
1474
 
    autoSync: true
1475
 
});
1476
 
 
1477
 
pies.data.load(function () {
1478
 
 
1479
 
    pies.render(&#x27;#pie-cart&#x27;);
1480
 
 
1481
 
    &#x2F;&#x2F; The new PieModel&#x27;s save() method is called, notifying the server
1482
 
    pies.addRow({ type: &#x27;pecan&#x27;, slices: 8 });
1483
 
 
1484
 
    &#x2F;&#x2F; Let us eat some pie!
1485
 
    pies.modifyRow(&#x27;lemon meringue&#x27;, { slices: 5 });
1486
 
});</pre>
1487
 
 
1488
 
 
1489
 
<h3 id="scrolling">Scrolling</h3>
1490
 
                                
1491
 
<p>
1492
 
    <strong>Note:</strong> Scrolling is not currently supported on the Android
1493
 
    WebKit browser.
1494
 
</p>
1495
 
 
1496
 
<p>
1497
 
    Scrolling functionality can be added to <code>Y.DataTable</code> by including
1498
 
    <code>datatable-scroll</code> module in your <code>use()</code>.  <code>datatable-scroll</code> is
1499
 
    <strong>NOT</strong> included in the <code>datatable</code> rollup module, so must be
1500
 
    included separately.
1501
 
</p>
1502
 
 
1503
 
<p>
1504
 
    Enable scrolling by setting the <code>scrollable</code> attribute, which accepts values
1505
 
    "x", "y", "xy", <code>true</code> (same as "xy"), or <code>false</code> (the default).
1506
 
</p>
1507
 
 
1508
 
<p>
1509
 
    Note, vertical scrolling also requires the table's <code>height</code> attribute to be
1510
 
    set, and horizontal scrolling requires the <code>width</code> to be set.
1511
 
</p>
1512
 
 
1513
 
<pre class="code prettyprint">&#x2F;&#x2F; Data from the seafoodwatch YQL table as of 3&#x2F;16&#x2F;2012
1514
 
var data = [
1515
 
    { &quot;fish&quot;: &quot;Barramundi (Imported Farmed in Open Systems)&quot;, &quot;recommendation&quot;: &quot;avoid&quot; },
1516
 
    { &quot;fish&quot;: &quot;Caviar, Paddlefish (Wild caught from U.S.)&quot;, &quot;recommendation&quot;: &quot;avoid&quot; },
1517
 
    { &quot;fish&quot;: &quot;Caviar, Sturgeon (Imported Wild-caught)&quot;, &quot;recommendation&quot;: &quot;avoid&quot; },
1518
 
    ...
1519
 
];
1520
 
 
1521
 
&#x2F;&#x2F; Enable vertical scrolling with scrollable &quot;y&quot;. The width is also set, but
1522
 
&#x2F;&#x2F; because scrollable is not &quot;x&quot; or &quot;xy&quot;, this just sets the table width.
1523
 
var table = new Y.DataTable({
1524
 
    caption: &#x27;Seafood tips for the US West Coast&#x27;,
1525
 
    columns: [&#x27;fish&#x27;, &#x27;recommendation&#x27;],
1526
 
    data: data,
1527
 
    scrollable: &quot;y&quot;,
1528
 
    height: &quot;200px&quot;,
1529
 
    width:  &quot;400px&quot;
1530
 
}).render(&quot;#scroll&quot;);</pre>
1531
 
 
1532
 
 
1533
 
<p>This code produces this table:</p>
1534
 
 
1535
 
<div id="scroll-example" class="yui3-skin-sam"></div>
1536
 
 
1537
 
<script>
1538
 
YUI().use('datatable-scroll', function (Y) {
1539
 
// Data from the seafoodwatch YQL table as of 3/16/2012
1540
 
var data = [
1541
 
    { "fish": "Barramundi (Imported Farmed in Open Systems)", "recommendation": "avoid" },
1542
 
    { "fish": "Caviar, Paddlefish (Wild caught from U.S.)", "recommendation": "avoid" },
1543
 
    { "fish": "Caviar, Sturgeon (Imported Wild-caught)", "recommendation": "avoid" },
1544
 
    { "fish": "Chilean Seabass", "recommendation": "avoid" },
1545
 
    { "fish": "Cobia (Imported Farmed)", "recommendation": "avoid" },
1546
 
    { "fish": "Cod, Atlantic (Trawl-caught from Canadian and U.S. Atlantic)", "recommendation": "avoid" },
1547
 
    { "fish": "Cod, Pacific (Imported)", "recommendation": "avoid" },
1548
 
    { "fish": "Crab, King (Imported)", "recommendation": "avoid" },
1549
 
    { "fish": "Dab, Common (Danish Seine from Iceland)", "recommendation": "avoid" },
1550
 
    { "fish": "Flounder (Wild-caught from U.S. Atlantic, Except Summer Flounder)", "recommendation": "avoid" },
1551
 
    { "fish": "Hake, White", "recommendation": "avoid" },
1552
 
    { "fish": "Halibut, Atlantic (Wild-caught from U.S.)", "recommendation": "avoid" },
1553
 
    { "fish": "Lobster, Caribbean Spiny (Brazil)", "recommendation": "avoid" },
1554
 
    { "fish": "Mahi Mahi (Imported Longline)", "recommendation": "avoid" },
1555
 
    { "fish": "Marlin, Blue (Imported)", "recommendation": "avoid" },
1556
 
    { "fish": "Marlin, Striped", "recommendation": "avoid" },
1557
 
    { "fish": "Monkfish", "recommendation": "avoid" },
1558
 
    { "fish": "Octopus (Philippines)", "recommendation": "avoid" },
1559
 
    { "fish": "Orange Roughy", "recommendation": "avoid" },
1560
 
    { "fish": "Plaice, American (Wild-caught from U.S. Atlantic)", "recommendation": "avoid" },
1561
 
    { "fish": "Pollock, Atlantic (Danish Seine and Trawl from Iceland)", "recommendation": "avoid" },
1562
 
    { "fish": "Salmon (Farmed including Atlantic Except U.S. Farmed in Tank Systems)", "recommendation": "avoid" },
1563
 
    { "fish": "Sardines, Atlantic (Mediterranean)", "recommendation": "avoid" },
1564
 
    { "fish": "Shad, American (U.S. Atlantic Gillnet)", "recommendation": "avoid" },
1565
 
    { "fish": "Shark (Except Common Thresher and Shortfin Mako, from California and Hawaii)", "recommendation": "avoid" },
1566
 
    { "fish": "Shrimp (Imported Farmed Except Thailand Farmed in Fully Reciruclating Systems)", "recommendation": "avoid" },
1567
 
    { "fish": "Shrimp (Imported Wild-Caught Except Canadian)", "recommendation": "avoid" },
1568
 
    { "fish": "Shrimp (Mexico Farmed in Open Systems)", "recommendation": "avoid" },
1569
 
    { "fish": "Skates", "recommendation": "avoid" },
1570
 
    { "fish": "Snapper, Red (U.S. Gulf of Mexico Wild-caught)", "recommendation": "avoid" },
1571
 
    { "fish": "Snapper, Red (Imported Wild-caught)", "recommendation": "avoid" },
1572
 
    { "fish": "Sole (Wild-caught from U.S Atlantic)", "recommendation": "avoid" },
1573
 
    { "fish": "Sturgeon (Imported Wild-caught)", "recommendation": "avoid" },
1574
 
    { "fish": "Swordfish (Imported)", "recommendation": "avoid" }
1575
 
];
1576
 
 
1577
 
var table = new Y.DataTable({
1578
 
    caption: 'Seafood tips for the US West Coast',
1579
 
    columns: ['fish', 'recommendation'],
1580
 
    data: data,
1581
 
    scrollable: "y",
1582
 
    height: "200px",
1583
 
    width:  "400px" // scrollable is not set to x or xy, so no scrolling
1584
 
}).render("#scroll-example");
1585
 
});
1586
 
</script>
1587
 
 
1588
 
<h2 id="events">DataTable Events</h2>
1589
 
 
1590
 
<p>
1591
 
    DataTable is a composition of supporting class instances and extensions, so
1592
 
    to centralize event reporting, it is a bubble target for its <code>data</code>
1593
 
    ModelList as well as the View instances used for rendering.
1594
 
</p>
1595
 
 
1596
 
<p>
1597
 
    In other words, some events you may need to subscribe to using an event
1598
 
    prefix to be notified.  Often, using a wildcard prefix is the simplest
1599
 
    method to ensure your subscribers will be notified, even if classes change.
1600
 
</p>
1601
 
 
1602
 
<pre class="code prettyprint">&#x2F;&#x2F; The sort event is from an extension, so it originates from DataTable
1603
 
table.after(&#x27;sort&#x27;, function (e) { ... });
1604
 
 
1605
 
&#x2F;&#x2F; Model changes originate from the record&#x27;s Model instance, propagate to the
1606
 
&#x2F;&#x2F; table&#x27;s ModelList, then finally to the DataTable, so they must be
1607
 
&#x2F;&#x2F; subscribed with an event prefix.  In this case, we&#x27;ll use a wildcard
1608
 
&#x2F;&#x2F; prefix.
1609
 
table.after(&#x27;*:priceChange&#x27;, function (e) { ... });</pre>
1610
 
 
1611
 
 
1612
 
<p>
1613
 
    DataTable generates a custom Model class with the "record" event prefix, if
1614
 
    you want to be more specific.  Otherwise, if your table uses a custom Model
1615
 
    class for its <code>recordType</code>, you can prefix Model events with the appropriate
1616
 
    prefix.
1617
 
</p>
1618
 
 
1619
 
<pre class="code prettyprint">&#x2F;&#x2F; Allow DataTable to generate the Model class automatically
1620
 
var table = new Y.DataTable({
1621
 
    columns: [&#x27;items&#x27;, &#x27;cost&#x27;, &#x27;price&#x27;],
1622
 
    data: [
1623
 
        { item: &quot;widget&quot;, cost: 23.57, price: 47.5 },
1624
 
        { item: &quot;gadget&quot;, cost: 0.11, price: 6.99 },
1625
 
        ...
1626
 
    ]
1627
 
});
1628
 
 
1629
 
&#x2F;&#x2F; generated Model classes have prefix &quot;record&quot;
1630
 
table.after(&#x27;record:change&#x27;, function (e) { ... });
1631
 
 
1632
 
&#x2F;&#x2F; PieList uses PieModels, which have a prefix of, you guessed it, &quot;pie&quot;
1633
 
var pies = new Y.DataTable({
1634
 
    columns: [&#x27;type&#x27;, &#x27;slices&#x27;],
1635
 
    data: new Y.PieList()
1636
 
});
1637
 
 
1638
 
pies.on(&#x27;pie:slicesChange&#x27;, function (e) {
1639
 
    if (e.target.get(&#x27;type&#x27;) === &#x27;chocolate creme&#x27;) {
1640
 
        &#x2F;&#x2F; Oh no you don&#x27;t!
1641
 
        e.preventDefault();
1642
 
    }
1643
 
});</pre>
1644
 
 
1645
 
 
1646
 
<p>
1647
 
    The full list of events is included in <a href="http://yuilibrary.com/yui/docs/api/classes/DataTable.html#events">the DataTable API docs</a>.
1648
 
</p>
1649
 
 
1650
 
<h2 id="knownissues">Known Issues</h2>
1651
 
 
1652
 
<ul>
1653
 
    <li>
1654
 
        Scrolling is
1655
 
        <a href="http://yuilibrary.com/projects/yui3/ticket/2529761">not
1656
 
        currently supported on Android</a> WebKit browser.
1657
 
    </li>
1658
 
    <li>
1659
 
        Scrolling DataTable
1660
 
        <a href="http://yuilibrary.com/projects/yui3/ticket/2531047">may not
1661
 
        appear scrollable</a> on iOS browsers or OS X 10.7 depending on the
1662
 
        system preference "Show scroll bars" (General).
1663
 
    </li>
1664
 
</ul>
1665
 
 
1666
 
<h2 id="column-config">Appendix A: Column Configurations</h2>
1667
 
 
1668
 
<p>
1669
 
    The properties below are supported in the column configuration objects
1670
 
    passed in the <code>columns</code> attribute array.
1671
 
</p>
1672
 
 
1673
 
<div id="column-config-table" class="yui3-skin-sam">
1674
 
    <table>
1675
 
    <thead>
1676
 
        <tr>
1677
 
            <th scope="col">Configuration</th>
1678
 
            <th scope="col">Description</th>
1679
 
            <th scope="col">Module</th>
1680
 
        </tr>
1681
 
    </thead>
1682
 
    <tbody>
1683
 
        <tr>
1684
 
            <td>key</td>
1685
 
            <td>
1686
 
<pre class="code prettyprint">{ key: &#x27;username&#x27; }</pre>
1687
 
 
1688
 
                <p>
1689
 
                    Binds the column values to the named property in the <code>data</code>.
1690
 
                <p>
1691
 
                <p>
1692
 
                    Optional if <code>formatter</code>, <code>nodeFormatter</code>, or <code>cellTemplate</code>
1693
 
                    is used to populate the content.
1694
 
                </p>
1695
 
                <p>It should not be set if <code>children</code> is set.</p>
1696
 
                <p>
1697
 
                    The value is used for the <code>_id</code> property unless the <code>name</code>
1698
 
                    property is also set.
1699
 
                </p>
1700
 
            </td>
1701
 
            <td><code>datatable-base</code></td>
1702
 
        </tr>
1703
 
        <tr>
1704
 
            <td>name</td>
1705
 
            <td>
1706
 
<pre class="code prettyprint">{ name: &#x27;fullname&#x27;, formatter: ... }</pre>
1707
 
 
1708
 
                
1709
 
                <p>
1710
 
                    Use this to assign a name to pass to <code>table.getColumn(NAME)</code>
1711
 
                    or style columns with class "yui3-datatable-col-NAME" if a
1712
 
                    column isn't assigned a <code>key</code>.  
1713
 
                </p>
1714
 
                <p>
1715
 
                    The value is used for the <code>_id</code> property.
1716
 
                </p>
1717
 
            </td>
1718
 
            <td><code>datatable-base</code></td>
1719
 
        </tr>
1720
 
        <tr>
1721
 
            <td>field</td>
1722
 
            <td>
1723
 
<pre class="code prettyprint">{ field: &#x27;fullname&#x27;, formatter: ... }</pre>
1724
 
 
1725
 
                
1726
 
                <p>An alias for <code>name</code> for backward compatibility.</p>
1727
 
            </td>
1728
 
            <td><code>datatable-base</code></td>
1729
 
        </tr>
1730
 
        <tr>
1731
 
            <td>id</td>
1732
 
            <td>
1733
 
<pre class="code prettyprint">{
1734
 
  name: &#x27;checkAll&#x27;,
1735
 
  id: &#x27;check-all&#x27;,
1736
 
  label: ...
1737
 
  formatter: ...
1738
 
}</pre>
1739
 
 
1740
 
                <p>
1741
 
                    Overrides the default unique id assigned <code>&lt;th id=&quot;HERE&quot;&gt;</code>.
1742
 
                </p>
1743
 
                <p>
1744
 
                    <em>Use this with caution</em>, since it can result in
1745
 
                    duplicate ids in the DOM.
1746
 
                </p>
1747
 
            </td>
1748
 
            <td><code>datatable-base</code></td>
1749
 
        </tr>
1750
 
        <tr>
1751
 
            <td>label</td>
1752
 
            <td>
1753
 
<pre class="code prettyprint">{ key: &#x27;MfgPrtNum&#x27;, label: &#x27;Part Number&#x27; }</pre>
1754
 
 
1755
 
 
1756
 
                <p>HTML to populate the header <code>&lt;th&gt;</code> for the column.</p>
1757
 
            </td>
1758
 
            <td><code>datatable-base</code></td>
1759
 
        </tr>
1760
 
        <tr>
1761
 
            <td>children</td>
1762
 
            <td>
1763
 
                <p>
1764
 
                    Used to create stacked headers.
1765
 
                    <a href="#nested">See the example above</a>.
1766
 
                </p>
1767
 
 
1768
 
                <p>
1769
 
                    Child columns may also contain <code>children</code>. There is no limit
1770
 
                    to the depth of nesting.
1771
 
                </p>
1772
 
 
1773
 
                <p>
1774
 
                    Columns configured with <code>children</code> are for display only and
1775
 
                    <strong>should not</strong> be configured with a <code>key</code>.
1776
 
                    Configurations relating to the display of data, such as
1777
 
                    <code>formatter</code>, <code>nodeFormatter</code>, <code>emptyCellValue</code>, etc. are
1778
 
                    ignored.
1779
 
                </p>
1780
 
            </td>
1781
 
            <td><code>datatable-base</code></td>
1782
 
        </tr>
1783
 
        <tr>
1784
 
            <td>abbr</td>
1785
 
            <td>
1786
 
<pre class="code prettyprint">{
1787
 
  key  : &#x27;forecast&#x27;,
1788
 
  label: &#x27;1yr Target Forecast&#x27;,
1789
 
  abbr : &#x27;Forecast&#x27;
1790
 
}</pre>
1791
 
 
1792
 
 
1793
 
                <p>Assigns the value <code>&lt;th abbr=&quot;HERE&quot;&gt;</code>.</p>
1794
 
            </td>
1795
 
            <td><code>datatable-base</code></td>
1796
 
        </tr>
1797
 
        <tr>
1798
 
            <td>headerTemplate</td>
1799
 
            <td>
1800
 
<pre class="code prettyprint">{
1801
 
  headerTemplate:
1802
 
    &#x27;&lt;th id=&quot;{id}&quot; &#x27; +
1803
 
        &#x27;title=&quot;Unread&quot; &#x27; +
1804
 
        &#x27;class=&quot;{className}&quot; &#x27; +
1805
 
        &#x27;{_id}&gt;&amp;#9679;&lt;&#x2F;th&gt;&#x27;
1806
 
}</pre>
1807
 
 
1808
 
 
1809
 
                <p>
1810
 
                    Overrides the default
1811
 
                    <a href="http://yuilibrary.com/yui/docs/api/classes/DataTable.HeaderView.html#property_CELL_TEMPLATE">CELL_TEMPLATE</a>
1812
 
                    used by <code>Y.DataTable.HeaderView</code> to render the header cell
1813
 
                    for this column.  This is necessary when more control is
1814
 
                    needed over the markup for the header itself, rather than
1815
 
                    its content.
1816
 
                </p>
1817
 
 
1818
 
                <p>
1819
 
                    Use the <code>label</code> configuration if you don't need to
1820
 
                    customize the <code>&lt;th&gt;</code> iteself.
1821
 
                </p>
1822
 
 
1823
 
                <p>
1824
 
                    Implementers are strongly encouraged to preserve at least
1825
 
                    the <code>{id}</code> and <code>{_id}</code> placeholders in the custom value.
1826
 
                </p>
1827
 
            </td>
1828
 
            <td><code>datatable-base</code></td>
1829
 
        </tr>
1830
 
        <tr>
1831
 
            <td>cellTemplate</td>
1832
 
            <td>
1833
 
<pre class="code prettyprint">{
1834
 
  key: &#x27;id&#x27;,
1835
 
  cellTemplate:
1836
 
    &#x27;&lt;td class=&quot;{className}&quot;&gt;&#x27; +
1837
 
      &#x27;&lt;input type=&quot;checkbox&quot; &#x27; +
1838
 
             &#x27;id=&quot;{content}&quot;&gt;&#x27; +
1839
 
    &#x27;&lt;&#x2F;td&gt;&#x27;
1840
 
}</pre>
1841
 
 
1842
 
 
1843
 
                <p>
1844
 
                    Overrides the default
1845
 
                    <a href="http://yuilibrary.com/yui/docs/api/classes/DataTable.BodyView.html#property_CELL_TEMPLATE">CELL_TEMPLATE</a>
1846
 
                    used by <code>Y.DataTable.BodyView</code> to render the data cells 
1847
 
                    for this column.  This is necessary when more control is
1848
 
                    needed over the markup for the <code>&lt;td&gt;</code> itself, rather than
1849
 
                    its content.
1850
 
                </p>
1851
 
            </td>
1852
 
            <td><code>datatable-base</code></td>
1853
 
        </tr>
1854
 
        <tr>
1855
 
            <td>formatter</td>
1856
 
            <td>
1857
 
                <p>
1858
 
                    Used to customize the content of the data cells for this
1859
 
                    column.
1860
 
                </p>
1861
 
                
1862
 
                <p>
1863
 
                    <a href="#formatters">See the example above</a>
1864
 
                </p>
1865
 
            </td>
1866
 
            <td><code>datatable-base</code></td>
1867
 
        </tr>
1868
 
        <tr>
1869
 
            <td>nodeFormatter</td>
1870
 
            <td>
1871
 
                <p>
1872
 
                    Used to customize the content of the data cells for this
1873
 
                    column.
1874
 
                </p>
1875
 
                
1876
 
                <p>
1877
 
                    <a href="#formatters">See the example above</a>
1878
 
                </p>
1879
 
            </td>
1880
 
            <td><code>datatable-base</code></td>
1881
 
        </tr>
1882
 
        <tr>
1883
 
            <td>emptyCellValue</td>
1884
 
            <td>
1885
 
<pre class="code prettyprint">{
1886
 
  key: &#x27;price&#x27;,
1887
 
  emptyCellValue: &#x27;???&#x27;
1888
 
}</pre>
1889
 
 
1890
 
 
1891
 
                <p>
1892
 
                    Provides the default value to populate the cell if the data
1893
 
                    for that cell is <code>undefined</code>, <code>null</code>, or an empty string.
1894
 
                </p>
1895
 
            </td>
1896
 
            <td><code>datatable-base</code></td>
1897
 
        </tr>
1898
 
        <tr>
1899
 
            <td>allowHTML</td>
1900
 
            <td>
1901
 
<pre class="code prettyprint">{
1902
 
  key: &#x27;preview&#x27;,
1903
 
  allowHTML: true
1904
 
}</pre>
1905
 
 
1906
 
 
1907
 
                <p>
1908
 
                    Skips the security step of HTML escaping the value for cells
1909
 
                    in this column.  This is also necessary if <code>emptyCellValue</code>
1910
 
                    is set with an HTML string.
1911
 
                </p>
1912
 
                <p>
1913
 
                    <code>nodeFormatter</code>s ignore this configuration.  If using a
1914
 
                    <code>nodeFormatter</code>, it is recommended to use
1915
 
                    <a href="http://yuilibrary.com/yui/docs/api/classes/Escape.html#method_html">Y.Escape.html()</a>
1916
 
                    on any user supplied content that is to be displayed.
1917
 
                </p>
1918
 
            </td>
1919
 
            <td><code>datatable-base</code></td>
1920
 
        </tr>
1921
 
        <tr>
1922
 
            <td>className</td>
1923
 
            <td>
1924
 
<pre class="code prettyprint">{
1925
 
  key: &#x27;symbol&#x27;,
1926
 
  className: &#x27;no-hide&#x27;
1927
 
}</pre>
1928
 
 
1929
 
 
1930
 
                <p>
1931
 
                    A string of CSS classes that will be added to the <code>&lt;td&gt;</code>'s
1932
 
                    <code>class</code> attribute.
1933
 
                </p>
1934
 
 
1935
 
                <p>
1936
 
                    Note, all cells will automatically have a class in the
1937
 
                    form of "yui3-datatable-col-KEY" added to the <code>&lt;td&gt;</code>, where
1938
 
                    KEY is the column's configured <code>name</code>, <code>key</code>, or <code>id</code> (in
1939
 
                    that order of preference).
1940
 
                </p>
1941
 
            </td>
1942
 
            <td><code>datatable-base</code></td>
1943
 
        </tr>
1944
 
        <tr>
1945
 
            <td>width</td>
1946
 
            <td>
1947
 
<pre class="code prettyprint">{ key: &#x27;a&#x27;, width: &#x27;400px&#x27; },
1948
 
{ key: &#x27;b&#x27;, width: &#x27;10em&#x27; }</pre>
1949
 
 
1950
 
 
1951
 
                <p>
1952
 
                    Adds a style <code>width</code> setting to an associated <code>&lt;col&gt;</code>
1953
 
                    element for the column.
1954
 
                </p>
1955
 
 
1956
 
                <p>
1957
 
                    Note, the assigned width will not truncate cell content, and
1958
 
                    it will not preserve the configured width if doing so would
1959
 
                    compromise either the instance's <code>width</code> configuration or
1960
 
                    the natural width of the table's containing DOM elements.
1961
 
                </p>
1962
 
 
1963
 
                <p>
1964
 
                    If absolute widths are required, it can be accomplished with
1965
 
                    some custom CSS and the use of a <code>cellTemplate</code>, or
1966
 
                    <code>formatter</code>.  See
1967
 
                    <a href="http://yuilibrary.com/yui/docs/api/modules/datatable-column-widths.html">the
1968
 
                    description of <code>datatable-column-widths</code></a> for an example
1969
 
                    of how to do this.
1970
 
                </p>
1971
 
            </td>
1972
 
            <td><code>datatable-column-widths</code></td>
1973
 
        </tr>
1974
 
        <tr>
1975
 
            <td>sortable</td>
1976
 
            <td>
1977
 
<pre class="code prettyprint">{ key: &#x27;lastLogin&#x27;, sortable: true }</pre>
1978
 
 
1979
 
 
1980
 
                <p>
1981
 
                    Used when the instance's <code>sortable</code> attribute is set to
1982
 
                    "auto" (the default) to determine which columns will support
1983
 
                    user sorting by clicking on the header.
1984
 
                </p>
1985
 
                <p>
1986
 
                    If the instance's <code>sortable</code> attribute is set, this
1987
 
                    configuration is ignored.
1988
 
                </p>
1989
 
            </td>
1990
 
            <td><code>datatable-sort</code></td>
1991
 
        </tr>
1992
 
        <tr>
1993
 
            <td>sortFn</td>
1994
 
            <td>
1995
 
<pre class="code prettyprint">{
1996
 
  label: &#x27;Name&#x27;,
1997
 
  sortFn: function (a, b, desc) {
1998
 
    var an = a.get(&#x27;lname&#x27;) + b.get(&#x27;fname&#x27;),
1999
 
        bn = a.get(&#x27;lname&#x27;) + b.get(&#x27;fname&#x27;),
2000
 
        order = (an &gt; bn) ? 1 : -(an &lt; bn);
2001
 
 
2002
 
    return desc ? -order : order;
2003
 
  },
2004
 
  formatter: function (o) {
2005
 
    return o.data.lname + &#x27;, &#x27; + o.data.fname;
2006
 
  }
2007
 
}</pre>
2008
 
 
2009
 
 
2010
 
                <p>
2011
 
                    Allows a column to be sorted using a custom algorithm.  The
2012
 
                    function receives three parameters, the first two being the
2013
 
                    two record Models to compare, and the third being a boolean
2014
 
                    <code>true</code> if the sort order should be descending.
2015
 
                </p>
2016
 
                <p>
2017
 
                    The function should return <code>-1</code> to sort <code>a</code> above <code>b</code>, <code>-1</code>
2018
 
                    to sort <code>a</code> below <code>b</code>, and <code>0</code> if they are equal.  Keep in
2019
 
                    mind that the order should be reversed when <code>desc</code> is
2020
 
                    <code>true</code>.
2021
 
                </p>
2022
 
                <p>
2023
 
                    The <code>desc</code> parameter is provided to allow <code>sortFn</code>s to
2024
 
                    always sort certain values above or below others, such as
2025
 
                    always sorting <code>null</code>s on top.
2026
 
                </p>
2027
 
            </td>
2028
 
            <td><code>datatable-sort</code></td>
2029
 
        </tr>
2030
 
        <tr>
2031
 
            <td>sortDir</td>
2032
 
            <td>
2033
 
                <p>
2034
 
                    (<strong>read-only</strong>) If a column is sorted, this
2035
 
                    will be set to <code>1</code> for ascending order or <code>-1</code> for
2036
 
                    descending.  This configuration is public for inspection,
2037
 
                    but can't be used during DataTable instantiation to set the
2038
 
                    sort direction of the column.  Use the table's
2039
 
                    <a href="http://yuilibrary.com/yui/docs/api/classes/DataTable.html#attr_sortBy">sortBy</a>
2040
 
                    attribute for that.
2041
 
                </p>
2042
 
            </td>
2043
 
            <td><code>datatable-sort</code></td>
2044
 
        </tr>
2045
 
        <tr>
2046
 
            <td>_yuid</td>
2047
 
            <td>
2048
 
                <p>
2049
 
                    (<strong>read-only</strong>) The unique identifier assigned
2050
 
                    to each column.  This is used for the <code>id</code> if not set, and
2051
 
                    the <code>_id</code> if none of <code>name</code>, 'field<code>, </code>key<code>, or </code>id` are
2052
 
                    set.
2053
 
                </p>
2054
 
            </td>
2055
 
            <td><code>datatable-base</code></td>
2056
 
        </tr>
2057
 
        <tr>
2058
 
            <td>_id</td>
2059
 
            <td>
2060
 
                <p>
2061
 
                    (<strong>read-only</strong>) A unique-to-this-instance name
2062
 
                    used extensively in the rendering process.  It is also used
2063
 
                    to create the column's classname, as the input name
2064
 
                    <code>table.getColumn(HERE)</code>, and in the column header's
2065
 
                    <code>&lt;th data-yui3-col-id=&quot;HERE&quot;&gt;</code>.
2066
 
                </p>
2067
 
                <p>
2068
 
                    The value is populated by the first of <code>name</code>, <code>field</code>,
2069
 
                    <code>key</code>, <code>id</code>, or <code>_yuid</code> to have a value.  If that value
2070
 
                    has already been used (such as when multiple columns have
2071
 
                    the same <code>key</code>), an incrementer is added to the end.  For
2072
 
                    example, two columns with <code>key: &quot;id&quot;</code> will have <code>_id</code>s of
2073
 
                    "id" and "id2".  <code>table.getColumn(&quot;id&quot;)</code> will return the
2074
 
                    first column, and <code>table.getColumn(&quot;id2&quot;)</code> will return the
2075
 
                    second.
2076
 
                </p>
2077
 
            </td>
2078
 
            <td><code>datatable-base</code></td>
2079
 
        </tr>
2080
 
        <tr>
2081
 
            <td>_colspan</td>
2082
 
            <td>
2083
 
                <p>
2084
 
                    (<strong>read-only</strong>) Used by
2085
 
                    <code>Y.DataTable.HeaderView</code> when building stacked column
2086
 
                    headers.
2087
 
                </p>
2088
 
            </td>
2089
 
            <td><code>datatable-base</code></td>
2090
 
        </tr>
2091
 
        <tr>
2092
 
            <td>_rowspan</td>
2093
 
            <td>
2094
 
                <p>
2095
 
                    (<strong>read-only</strong>) Used by
2096
 
                    <code>Y.DataTable.HeaderView</code> when building stacked column
2097
 
                    headers.
2098
 
                </p>
2099
 
            </td>
2100
 
            <td><code>datatable-base</code></td>
2101
 
        </tr>
2102
 
        <tr>
2103
 
            <td>_parent</td>
2104
 
            <td>
2105
 
                <p>
2106
 
                    (<strong>read-only</strong>) Assigned to all columns in a
2107
 
                    column's <code>children</code> collection.  References the parent
2108
 
                    column object.
2109
 
                </p>
2110
 
            </td>
2111
 
            <td><code>datatable-base</code></td>
2112
 
        </tr>
2113
 
        <tr>
2114
 
            <td>_headers</td>
2115
 
            <td>
2116
 
                <p>
2117
 
                    (<strong>read-only</strong>) Array of the <code>id</code>s of the
2118
 
                    column and all parent columns.  Used by
2119
 
                    <code>Y.DataTable.BodyView</code> to populate <code>&lt;td headers=&quot;THIS&quot;&gt;</code>
2120
 
                    when a cell references more than one header.
2121
 
                </p>
2122
 
            </td>
2123
 
            <td><code>datatable-base</code></td>
2124
 
        </tr>
2125
 
    </tbody>
2126
 
    </table>
2127
 
</div>
2128
 
 
2129
 
<h2 id="formatter-props">Appendix B: Formatter Argument Properties</h2>
2130
 
 
2131
 
<p>
2132
 
    The properties below are found on the object passed to <code>formatter</code>
2133
 
    functions defined in a column configuration.  See
2134
 
    <a href="#nodeformatter-props">Appendix C</a> for the object properties
2135
 
    passed to <code>nodeFormatter</code>s.
2136
 
</p>
2137
 
 
2138
 
<div id="formatter-props-table" class="yui3-skin-sam">
2139
 
    <table>
2140
 
    <thead>
2141
 
        <tr>
2142
 
            <th scope="col">Property</th>
2143
 
            <th scope="col">Description</th>
2144
 
        </tr>
2145
 
    </thead>
2146
 
    <tbody>
2147
 
        <tr>
2148
 
            <td><code>value</code></td>
2149
 
            <td>
2150
 
<pre class="code prettyprint">formatter: function (o) {
2151
 
    &#x2F;&#x2F; assumes a numeric value for this column
2152
 
    return &#x27;$&#x27; + o.value.toFixed(2);
2153
 
}</pre>
2154
 
 
2155
 
 
2156
 
                <p>
2157
 
                    The raw value from the record Model to populate this cell.
2158
 
                    Equivalent to <code>o.record.get(o.column.key)</code> or
2159
 
                    <code>o.data[o.column.key]</code>.
2160
 
                </p>
2161
 
            </td>
2162
 
        </tr>
2163
 
        <tr>
2164
 
            <td><code>data</code></td>
2165
 
            <td>
2166
 
<pre class="code prettyprint">formatter: function (o) {
2167
 
    return o.data.lname + &#x27;, &#x27; + o.data.fname;
2168
 
}</pre>
2169
 
 
2170
 
                
2171
 
                <p>
2172
 
                    The Model data for this row in simple object format.
2173
 
                </p>
2174
 
            </td>
2175
 
        </tr>
2176
 
        <tr>
2177
 
            <td><code>record</code></td>
2178
 
            <td>
2179
 
<pre class="code prettyprint">formatter: function (o) {
2180
 
    return &#x27;&lt;a href=&quot;&#x2F;service&#x2F;&#x27; + o.record.get(&#x27;id&#x27;) + &#x27;&quot;&gt; +
2181
 
        o.value + &#x27;&lt;&#x2F;a&gt;&#x27;;
2182
 
}</pre>
2183
 
 
2184
 
                
2185
 
                <p>
2186
 
                    The Model for this row.
2187
 
                </p>
2188
 
            </td>
2189
 
        </tr>
2190
 
        <tr>
2191
 
            <td><code>column</code></td>
2192
 
            <td>
2193
 
<pre class="code prettyprint">formatter: function (o) {
2194
 
    &#x2F;&#x2F; Use a custom column property
2195
 
    var format = o.column.dateFormat || &#x27;%D&#x27;;
2196
 
 
2197
 
    return Y.DataType.Data.format(o.value, format);
2198
 
}</pre>
2199
 
 
2200
 
                
2201
 
                <p>
2202
 
                    The column configuration object.
2203
 
                </p>
2204
 
            </td>
2205
 
        </tr>
2206
 
        <tr>
2207
 
            <td><code>className</code></td>
2208
 
            <td>
2209
 
<pre class="code prettyprint">formatter: function (o) {
2210
 
    if (o.value &lt; 0) {
2211
 
        o.className += &#x27;loss&#x27;;
2212
 
    }
2213
 
}</pre>
2214
 
 
2215
 
                
2216
 
                <p>
2217
 
                    A string of class names to add <code>&lt;td class=&quot;HERE&quot;&gt;</code> in
2218
 
                    addition to the column class and any classes in the
2219
 
                    column's <code>className</code> configuration.
2220
 
                </p>
2221
 
            </td>
2222
 
        </tr>
2223
 
        <tr>
2224
 
            <td><code>rowIndex</code></td>
2225
 
            <td>
2226
 
<pre class="code prettyprint">formatter: function (o) {
2227
 
    return (o.rowIndex + 1) + &#x27; - &#x27; + o.value;
2228
 
}</pre>
2229
 
 
2230
 
                
2231
 
                <p>
2232
 
                    The index of the current Model in the ModelList.
2233
 
                    <em>Typically</em> correlates to the row index as well.
2234
 
                </p>
2235
 
            </td>
2236
 
        </tr>
2237
 
        <tr>
2238
 
            <td><code>rowClass</code></td>
2239
 
            <td>
2240
 
<pre class="code prettyprint">formatter: function (o) {
2241
 
    if (o.value &lt; 0) {
2242
 
        o.rowClass += &#x27;loss&#x27;;
2243
 
    }
2244
 
}</pre>
2245
 
 
2246
 
                
2247
 
                <p>
2248
 
                    A string of css classes to add <code>&lt;tr class=&quot;HERE&quot;&gt;&lt;td...</code>.
2249
 
                </p>
2250
 
 
2251
 
                <p>
2252
 
                    This is useful to avoid the need for <code>nodeFormatter</code>s to add
2253
 
                    classes to the containing row.
2254
 
                </p>
2255
 
            </td>
2256
 
        </tr>
2257
 
    </tbody>
2258
 
    </table>
2259
 
</div>
2260
 
 
2261
 
<h2 id="nodeformatter-props">Appendix C: nodeFormatter Argument Properties</h2>
2262
 
 
2263
 
<p>
2264
 
    The properties below are found on the object passed to <code>nodeFormatter</code>
2265
 
    functions defined in a column configuration.  See
2266
 
    <a href="#formatter-props">Appendix B</a> for the object properties
2267
 
    passed to <code>formatter</code>s.
2268
 
</p>
2269
 
 
2270
 
<pre class="code prettyprint">&#x2F;&#x2F; Reference nodeFormatter
2271
 
nodeFormatter: function (o) {
2272
 
    if (o.value &lt; o.data.quota) {
2273
 
        o.td.setAttribute(&#x27;rowspan&#x27;, 2);
2274
 
        o.td.setAttribute(&#x27;data-term-id&#x27;, this.record.get(&#x27;id&#x27;));
2275
 
 
2276
 
        o.td.ancestor().insert(
2277
 
            &#x27;&lt;tr&gt;&lt;td colspan&quot;3&quot;&gt;&#x27; +
2278
 
                &#x27;&lt;button class=&quot;term&quot;&gt;terminate&lt;&#x2F;button&gt;&#x27; +
2279
 
            &#x27;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;&#x27;,
2280
 
            &#x27;after&#x27;);
2281
 
    }
2282
 
 
2283
 
    o.cell.setContent(o.value);
2284
 
}</pre>
2285
 
 
2286
 
 
2287
 
<div id="nodeformatter-props-table" class="yui3-skin-sam">
2288
 
    <table>
2289
 
    <thead>
2290
 
        <tr>
2291
 
            <th scope="col">Property</th>
2292
 
            <th scope="col">Description</th>
2293
 
        </tr>
2294
 
    </thead>
2295
 
    <tbody>
2296
 
        <tr>
2297
 
            <td><code>td</code></td>
2298
 
            <td>The <code>&lt;td&gt;</code> Node for this cell.</td>
2299
 
        </tr>
2300
 
        <tr>
2301
 
            <td><code>cell</code></td>
2302
 
            <td>
2303
 
                <p>
2304
 
                    If the cell <code>&lt;td&gt;</code> contains an element with class
2305
 
                    "yui3-datatable-liner", this will refer to that Node.
2306
 
                    Otherwise, it is equivalent to <code>o.td</code> (default behavior).
2307
 
                </p>
2308
 
 
2309
 
                <p>
2310
 
                    By default, liner elements aren't rendered into cells, but
2311
 
                    to implement absolute column widths, some cell liner
2312
 
                    element with <code>width</code> and <code>overflow</code> style is required
2313
 
                    (barring a table style of <code>table-layout: fixed</code>).  This may
2314
 
                    be applied to the columns <code>cellTemplate</code> configuration or
2315
 
                    to the <code>bodyView</code> instance's <code>CELL_TEMPLATE</code> for all
2316
 
                    columns.
2317
 
                </p>
2318
 
 
2319
 
                <p>
2320
 
                    Generally, the liner, if present, corresponds to where the
2321
 
                    content should go, so use <code>o.cell</code> to add content and
2322
 
                    <code>o.td</code> to specifically work with the <code>&lt;td&gt;</code> Node.
2323
 
                </p>
2324
 
            </td>
2325
 
        </tr>
2326
 
        <tr>
2327
 
            <td><code>value</code></td>
2328
 
            <td>
2329
 
                The raw value from the record Model to populate this cell.
2330
 
                Equivalent to <code>o.record.get(o.column.key)</code> or
2331
 
                <code>o.data[o.column.key]</code>.
2332
 
            </td>
2333
 
        </tr>
2334
 
        <tr>
2335
 
            <td><code>data</code></td>
2336
 
            <td>The Model data for this row in simple object format.</td>
2337
 
        </tr>
2338
 
        <tr>
2339
 
            <td><code>record</code></td>
2340
 
            <td>The Model for this row.</td>
2341
 
        </tr>
2342
 
        <tr>
2343
 
            <td><code>column</code></td>
2344
 
            <td>The column configuration object.</td>
2345
 
        </tr>
2346
 
        <tr>
2347
 
            <td><code>rowIndex</code></td>
2348
 
            <td>
2349
 
                The index of the current Model in the ModelList.
2350
 
                <em>Typically</em> correlates to the row index as well.
2351
 
            </td>
2352
 
        </tr>
2353
 
    </tbody>
2354
 
    </table>
2355
 
</div>
2356
 
<script>
2357
 
YUI.add('datatable-node', function (Y) {
2358
 
    Y.Plugin.DataTable = Y.Base.create('datatable', Y.DataTable, [], {
2359
 
        initializer: function (config) {
2360
 
            var columns = config.host.all('thead th').get('text'),
2361
 
                count   = columns.length,
2362
 
                data    = [],
2363
 
                i;
2364
 
                
2365
 
            config.host.all('tbody td').each(function (node, i) {
2366
 
                var record = (i % count) ?
2367
 
                        data[data.length - 1] :
2368
 
                        (data[data.length] = {});
2369
 
                record[columns[i % count]] = node.getContent();
2370
 
            });
2371
 
 
2372
 
            for (i = columns.length - 1; i >= 0; --i) {
2373
 
                columns[i] = { key: columns[i], allowHTML: true }
2374
 
            }
2375
 
 
2376
 
            this.setAttrs({
2377
 
                columns    : columns,
2378
 
                data       : data
2379
 
            });
2380
 
 
2381
 
            this.render();
2382
 
 
2383
 
            config.host.replace(this.get('boundingBox'));
2384
 
        }
2385
 
    }, {
2386
 
        NS: 'table'
2387
 
    });
2388
 
 
2389
 
    Y.Node.ATTRS.datatable = {
2390
 
        setter: function (val) {
2391
 
            if (val === true) {
2392
 
                val = {};
2393
 
            }
2394
 
 
2395
 
            this.plug(Y.Plugin.DataTable, val);
2396
 
        }
2397
 
    };
2398
 
}, '0.1', { requires: ['datatable-base', 'node-pluginhost'] });
2399
 
YUI({ filter: 'raw' }).use('datatable-node', 'datatable-sort', function (Y) {
2400
 
    Y.one('#column-config-table table').set('datatable', {
2401
 
        sortable: ['Configuration', 'Module']
2402
 
    });
2403
 
    Y.one('#formatter-props-table table').set('datatable', true);
2404
 
    Y.one('#nodeformatter-props-table table').set('datatable', true);
2405
 
});
2406
 
</script>
2407
 
</div>
2408
 
            </div>
2409
 
        </div>
2410
 
 
2411
 
        <div class="yui3-u-1-4">
2412
 
            <div class="sidebar">
2413
 
                
2414
 
                    <div id="toc" class="sidebox">
2415
 
                        <div class="hd">
2416
 
                            <h2 class="no-toc">Table of Contents</h2>
2417
 
                        </div>
2418
 
 
2419
 
                        <div class="bd">
2420
 
                            <ul class="toc">
2421
 
<li>
2422
 
<a href="#getting-started">Getting Started</a>
2423
 
</li>
2424
 
<li>
2425
 
<a href="#migration-intro">Upgrading from version 3.4.1 or older?</a>
2426
 
</li>
2427
 
<li>
2428
 
<a href="#using">DataTable Basics</a>
2429
 
</li>
2430
 
<li>
2431
 
<a href="#columns">Column Configuration</a>
2432
 
<ul class="toc">
2433
 
<li>
2434
 
<a href="#nested">Stacked Column Headers</a>
2435
 
</li>
2436
 
<li>
2437
 
<a href="#formatters">Formatting Cell Data</a>
2438
 
<ul class="toc">
2439
 
<li>
2440
 
<a href="#formatter-function">Setting content with <code>formatter</code> functions</a>
2441
 
</li>
2442
 
<li>
2443
 
<a href="#nodeformatters">Setting content with <code>nodeFormatter</code> functions</a>
2444
 
</li>
2445
 
<li>
2446
 
<a href="#formatter-vs-nodeformatter">Why <code>formatter</code> and <code>nodeFormatter</code>?</a>
2447
 
</li>
2448
 
<li>
2449
 
<a href="#formatters-vs-empty">Formatters vs. <code>emptyCellValue</code></a>
2450
 
</li>
2451
 
</ul>
2452
 
</li>
2453
 
</ul>
2454
 
</li>
2455
 
<li>
2456
 
<a href="#data">Table Data Configuration</a>
2457
 
<ul class="toc">
2458
 
<li>
2459
 
<a href="#recordtype">Specifying the Record Model</a>
2460
 
</li>
2461
 
<li>
2462
 
<a href="#modellist">The <code>data</code> ModelList</a>
2463
 
</li>
2464
 
<li>
2465
 
<a href="#getting-data">Getting Remote Table Data</a>
2466
 
</li>
2467
 
</ul>
2468
 
</li>
2469
 
<li>
2470
 
<a href="#features">DataTable Modules and Features</a>
2471
 
<ul class="toc">
2472
 
<li>
2473
 
<a href="#base">Features in <code>DataTable.Base</code></a>
2474
 
</li>
2475
 
<li>
2476
 
<a href="#datatable-message">Table Messages</a>
2477
 
</li>
2478
 
<li>
2479
 
<a href="#colwidths">Column Width Configuration</a>
2480
 
</li>
2481
 
<li>
2482
 
<a href="#sorting">Column sorting</a>
2483
 
<ul class="toc">
2484
 
<li>
2485
 
<a href="#customsort">Custom Sorting</a>
2486
 
</li>
2487
 
<li>
2488
 
<a href="#sortapi">Sorting Methods</a>
2489
 
</li>
2490
 
<li>
2491
 
<a href="#sortby">The <code>sortBy</code> Attribute</a>
2492
 
</li>
2493
 
<li>
2494
 
<a href="#sortevent">The <code>sort</code> Event</a>
2495
 
</li>
2496
 
</ul>
2497
 
</li>
2498
 
<li>
2499
 
<a href="#mutation">Table Mutation APIs (<code>addRow</code>, etc)</a>
2500
 
<ul class="toc">
2501
 
<li>
2502
 
<a href="#column-mutation">Column Mutation Methods</a>
2503
 
</li>
2504
 
<li>
2505
 
<a href="#row-mutation">Row Mutation Methods</a>
2506
 
</li>
2507
 
</ul>
2508
 
</li>
2509
 
<li>
2510
 
<a href="#scrolling">Scrolling</a>
2511
 
</li>
2512
 
</ul>
2513
 
</li>
2514
 
<li>
2515
 
<a href="#events">DataTable Events</a>
2516
 
</li>
2517
 
<li>
2518
 
<a href="#knownissues">Known Issues</a>
2519
 
</li>
2520
 
<li>
2521
 
<a href="#column-config">Appendix A: Column Configurations</a>
2522
 
</li>
2523
 
<li>
2524
 
<a href="#formatter-props">Appendix B: Formatter Argument Properties</a>
2525
 
</li>
2526
 
<li>
2527
 
<a href="#nodeformatter-props">Appendix C: nodeFormatter Argument Properties</a>
2528
 
</li>
2529
 
</ul>
2530
 
                        </div>
2531
 
                    </div>
2532
 
                
2533
 
 
2534
 
                
2535
 
                    <div class="sidebox">
2536
 
                        <div class="hd">
2537
 
                            <h2 class="no-toc">Examples</h2>
2538
 
                        </div>
2539
 
 
2540
 
                        <div class="bd">
2541
 
                            <ul class="examples">
2542
 
                                
2543
 
                                    
2544
 
                                        <li data-description="This example illustrates simple DataTable use cases.">
2545
 
                                            <a href="datatable-basic.html">Basic DataTable</a>
2546
 
                                        </li>
2547
 
                                    
2548
 
                                
2549
 
                                    
2550
 
                                        <li data-description="DataTable loaded with JSON data from a remote webservice via DataSource.Get">
2551
 
                                            <a href="datatable-dsget.html">DataTable + DataSource.Get + JSON Data</a>
2552
 
                                        </li>
2553
 
                                    
2554
 
                                
2555
 
                                    
2556
 
                                        <li data-description="DataTable loaded with XML data from a remote webservice via DataSource.IO.">
2557
 
                                            <a href="datatable-dsio.html">DataTable + DataSource.IO + XML Data</a>
2558
 
                                        </li>
2559
 
                                    
2560
 
                                
2561
 
                                    
2562
 
                                        <li data-description="Custom format data for display.">
2563
 
                                            <a href="datatable-formatting.html">Formatting Row Data for Display</a>
2564
 
                                        </li>
2565
 
                                    
2566
 
                                
2567
 
                                    
2568
 
                                        <li data-description="DataTable with nested column headers.">
2569
 
                                            <a href="datatable-nestedcols.html">Nested Column Headers</a>
2570
 
                                        </li>
2571
 
                                    
2572
 
                                
2573
 
                                    
2574
 
                                        <li data-description="DataTable with column sorting.">
2575
 
                                            <a href="datatable-sort.html">Column Sorting</a>
2576
 
                                        </li>
2577
 
                                    
2578
 
                                
2579
 
                                    
2580
 
                                        <li data-description="DataTable with vertical and/or horizontal scrolling rows.">
2581
 
                                            <a href="datatable-scroll.html">Scrolling DataTable</a>
2582
 
                                        </li>
2583
 
                                    
2584
 
                                
2585
 
                                    
2586
 
                                
2587
 
                            </ul>
2588
 
                        </div>
2589
 
                    </div>
2590
 
                
2591
 
 
2592
 
                
2593
 
                    <div class="sidebox">
2594
 
                        <div class="hd">
2595
 
                            <h2 class="no-toc">Examples That Use This Component</h2>
2596
 
                        </div>
2597
 
 
2598
 
                        <div class="bd">
2599
 
                            <ul class="examples">
2600
 
                                
2601
 
                                    
2602
 
                                
2603
 
                                    
2604
 
                                
2605
 
                                    
2606
 
                                
2607
 
                                    
2608
 
                                
2609
 
                                    
2610
 
                                
2611
 
                                    
2612
 
                                
2613
 
                                    
2614
 
                                
2615
 
                                    
2616
 
                                        <li data-description="Shows how to instantiate multiple Panel instances, and use nested modality to interact with a Datatable.">
2617
 
                                            <a href="../panel/panel-form.html">Creating a Modal Form</a>
2618
 
                                        </li>
2619
 
                                    
2620
 
                                
2621
 
                            </ul>
2622
 
                        </div>
2623
 
                    </div>
2624
 
                
2625
 
            </div>
2626
 
        </div>
2627
 
    </div>
2628
 
</div>
2629
 
 
2630
 
<script src="../assets/vendor/prettify/prettify-min.js"></script>
2631
 
<script>prettyPrint();</script>
2632
 
 
2633
 
</body>
2634
 
</html>