9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith<style type="text/css">
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith white-space: nowrap;
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith background: #fcfbfa;
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith border: 1px solid #d0d5ec;
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith padding: 0 3px;
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith .yui3-datatable table {
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith width: auto;
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith .yui3-datatable td, .yui3-datatable th {
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith border: 0 none;
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith .yui3-datatable-col-Module {
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith white-space: nowrap;
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith .yui3-skin-sam .yui3-datatable-message-content {
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith background: #fff;
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith border-bottom: 0 none;
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith background: #faf3d1;
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith border: 1px solid #eac9a9;
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith -moz-border-radius: 3px;
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith -webkit-border-radius: 3px;
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith border-radius: px;
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith padding: 0 1em;
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith -moz-box-shadow: 0 0 5px #ccc8b3;
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith -webkit-box-shadow: 0 0 5px #ccc8b3;
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith box-shadow: 0 0 5px #ccc8b3;
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith margin-bottom: 1em;
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith .notice h2 {
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith margin-top: .6em;
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<div class="intro component">
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith The DataTable widget is responsible for rendering columnar data into a
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith highly customizable and fully accessible HTML table. The core
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith functionality of DataTable is to visualize structured data as a table.
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith A variety of class extensions can then be used to add features to the
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith table such as sorting and scrolling.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith{{>getting-started}}
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith<div class="notice">
e8d16592842bdb884e0e4d938f334b6ac5b7cad0Luke Smith <h2 id="migration-intro">Upgrading from version 3.4.1 or older?</h2>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith DataTable was refactored for 3.5.0. Some APIs were changed in backward
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith incompatible ways.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith Read the <a href="migration.html">3.5.0 Migration Guide</a> for tips to
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith avoid unpleasant surprises. If you still run into issues, please
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith <a href="../../../projects/yui3/newticket/">file a ticket</a>.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith If you are unable to upgrade due to unresolvable issues, you can use the
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith <a href="../datatable-deprecated/index.html">`datatable-deprecated`</a>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith module suite, which is equivalent to the 3.4.1 implementation. But be
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith aware that these modules will be removed in a future version of YUI.
9563d8a01a40e508f7697d9c674c164512940371Luke Smith<h2 id="using">DataTable Basics</h2>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith A basic DataTable is made of columns and rows. Define the columns you
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith want to display in your DataTable with the `columns` attribute. Rows are
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith created for you based on the data you provide to the `data` attribute.
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith Under the hood, the DataTable class uses a
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith <a href="../model-list/index.html">ModelList</a> instance to manage the row
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith data properties. Read the <a href="#data">Table Data Configuration</a>
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith section below for details about how to load, configure, and work with the
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith// Columns must match data object property names
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith { id: "ga-3475", name: "gadget", price: "$6.99", cost: "$5.99" },
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith { id: "sp-9980", name: "sprocket", price: "$3.75", cost: "$3.25" },
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith { id: "wi-0650", name: "widget", price: "$4.25", cost: "$3.75" }
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smithvar table = new Y.DataTable({
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith columns: ["id", "name", "price"],
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith // Optionally configure your table with a caption
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith caption: "My first DataTable!",
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith // and/or a summary (table attribute)
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith summary: "Example DataTable showing basic instantiation configuration"
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith<p>This code produces this table:</p>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith<div id="basic-example" class="yui3-skin-sam"></div>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke SmithYUI({ filter: 'raw' }).use('datatable-base', function (Y) {
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith // Columns must match data object property names
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith var data = [
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith { id: "ga-3475", name: "gadget", price: "$6.99", cost: "$5.99" },
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith { id: "sp-9980", name: "sprocket", price: "$3.75", cost: "$3.25" },
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith { id: "wi-0650", name: "widget", price: "$4.25", cost: "$3.75" }
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith var table = new Y.DataTable({
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith columns: ["id", "name", "price"],
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith caption: "My first DataTable!",
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith summary: "Example DataTable showing basic instantiation configuration"
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith table.render("#basic-example");
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith<h2 id="columns">Column Configuration</h2>
9563d8a01a40e508f7697d9c674c164512940371Luke Smith The `columns` attribute takes an array of field names that correspond to
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith property names in the `data` objects. These field names are called "keys".
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith As long as these keys exist in your data, DataTable will display the
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith values in the table. By default, the key is also used as the label of the
9563d8a01a40e508f7697d9c674c164512940371Luke Smith column header.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith Use objects instead of key strings to customize how the cells in a column
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith// Columns must match data object property names
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith { id: "ga-3475", name: "gadget", price: "$6.99", cost: "$5.99" },
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith { id: "sp-9980", name: "sprocket", price: "$3.75", cost: "$3.25" },
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith { id: "wi-0650", name: "widget", /* missing */ cost: "$3.75" }
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smithvar table = new Y.DataTable({
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith { key: "name", label: "part name" },
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith { key: "price", allowHTML: true, emptyCellValue: "<em>(not set)</em>" },
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith<p>This code produces this table:</p>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith<div id="column-example1" class="yui3-skin-sam"></div>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke SmithYUI().use('datatable-base', function (Y) {
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith // Columns must match data object property names
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith var data = [
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith { id: "ga-3475", name: "gadget", price: "$6.99", cost: "$5.99" },
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith { id: "sp-9980", name: "sprocket", price: "$3.75", cost: "$3.25" },
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith { id: "wi-0650", name: "widget", cost: "$3.75" }
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith var table = new Y.DataTable({
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith { key: "name", label: "part name" },
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith { key: "price", allowHTML: true, emptyCellValue: "<em>(not set)</em>" },
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith table.render("#column-example1");
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith Some column configurations affect the table headers and others affect the
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith Use the `key` property to reference the associated data field when
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith configuring columns with objects. Other supported configuration
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith properties are listed in <a href="#column-config">Appendix A</a> below.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith<h3 id="nested">Stacked Column Headers</h3>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith Use the `children` column configuration to create multiple rows of column
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smithvar columns = [
9563d8a01a40e508f7697d9c674c164512940371Luke Smith // Important: Parent columns do NOT get a key...
9563d8a01a40e508f7697d9c674c164512940371Luke Smith // but DO get a label
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith label: "Access",
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith // Pass an array of column configurations (strings or objects) as children
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith { username: "root", read: true, write: true },
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith { username: "spilgrim", read: true, write: false },
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith { username: "fizzgig", read: false, write: false }
9563d8a01a40e508f7697d9c674c164512940371Luke Smithvar table = new Y.DataTable({
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith columns: columns,
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith}).render("#example");
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith<p>This code produces this table:</p>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith<div id="nested-example" class="yui3-skin-sam"></div>
9533104fb7447a0765dc2aafec105c729d2c1be7Luke SmithYUI().use('datatable-base', function (Y) {
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith { username: "root", read: true, write: true },
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith { username: "spilgrim", read: true, write: false },
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith { username: "fizzgig", read: false, write: false }
9563d8a01a40e508f7697d9c674c164512940371Luke Smithvar table = new Y.DataTable({
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith // Important: Parent columns do NOT get a key...
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith // but DO get a label
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith label: "Access",
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith // Pass an array of column configurations (strings or objects) as children
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith}).render("#nested-example");
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith `children` takes an array of column configurations, just like the `columns`
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith attribute itself. The columns defined in the `children` property will have
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith header cells rendered below the parent column's header.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith Columns that have `children` don't relate directly to the data cells in the
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith table rows, so they <strong>should not</strong> have a `key` configured.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith They should, however, include a `label` to provide the header's content.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith<h3 id="formatters">Formatting Cell Data</h3>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith To customize the display of cell data in a column, DataTable provides the
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith `formatter` and `nodeFormatter` column configurations. Both configurations
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith accept functions, but `formatter` will also accept a template string.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith `formatter`s are expected to return the string content to populate each
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith cell in that column, and `nodeFormatter`s are provided with the cell Nodes
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith and expected to populate them using the Node API.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith For best performance, <strong><a href="#formatter-vs-nodeformatter">avoid
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith `nodeFormatter`s unless absolutely necessary</a></strong>.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smithvar columns = [
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith key: 'cost',
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith formatter: '${value}' // formatter template string
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith key: 'price',
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith formatter: function (o) {
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith o.className += ' yellow-background';
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith return '$' + o.value.toFixed(2);
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith label: 'profit',
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith nodeFormatter: function (o) {
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith prefix = '$',
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith if (profit < 0) {
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith prefix = '-' + prefix;
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith profit = Math.abs(profit);
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith // Assign a rowspan to the first cell and add a new row
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith // below this one to span the last three columns
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith row.one('td').setAttribute('rowspan', 2);
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith '<tr class="auth"><td colspan="3">' +
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith '<button class="ok">authorize</button>' +
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith '<button class="stop">discontinue</button>' +
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith '</td></tr>',
9563d8a01a40e508f7697d9c674c164512940371Luke Smith<p>This code produces this table:</p>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith<div id="formatter-example" class="yui3-skin-sam">
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith <style scoped>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith .yui3-datatable .yui3-datatable-data .expensive {
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith background-color: #ffe;
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith .yui3-skin-sam .yui3-datatable-data .auth td {
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith border-bottom: 1px dashed #cbcbcb;
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith color: #700;
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith font-weight: 700;
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith text-align: right;
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith background-color: #fff;
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith border-top: 1px dashed #cbcbcb;
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith border-left: 1px solid #cbcbcb;
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith padding-right: 5px;
9563d8a01a40e508f7697d9c674c164512940371Luke SmithYUI().use('datatable-base', function (Y) {
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith var columns = [
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith key: 'cost',
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith formatter: '${value}' // formatter template string
9563d8a01a40e508f7697d9c674c164512940371Luke Smith key: 'price',
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith formatter: function (o) {
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith o.className += ' expensive';
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith return '$' + o.value.toFixed(2);
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith label: 'profit',
9563d8a01a40e508f7697d9c674c164512940371Luke Smith nodeFormatter: function (o) {
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith prefix = '$',
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith if (profit < 0) {
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith prefix = '-' + prefix;
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith profit = Math.abs(profit);
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith row.one('td').setAttribute('rowspan', 2);
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith '<tr class="auth"><td colspan="3">' +
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith '<button class="ok">authorize</button>' +
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith '<button class="stop">discontinue</button>' +
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith '</td></tr>',
9563d8a01a40e508f7697d9c674c164512940371Luke Smith var data = [
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith { item: "widget", cost: 23.57, price: 47.5 },
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith { item: "gadget", cost: 0.11, price: 6.99 },
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith { item: "sprocket", cost: 4.08, price: 3.75 },
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith { item: "nut", cost: 0.01, price: 0.25 }
9563d8a01a40e508f7697d9c674c164512940371Luke Smith var table = new Y.DataTable({
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith columns: columns,
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith }).render("#formatter-example");
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith The parameters passed to `formatter` functions and `nodeFormatter`
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith functions are described in <a href="#formatter-props">Appendix B</a> and <a
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith href="#nodeformatter-props">Appendix C</a>, respectively.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith <strong>Note</strong>: It's highly recommended to keep the data in the
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith underlying `data` ModelList as pure data, free from presentational
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith concerns. For example, use real numbers, not numeric strings, and store
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith link urls and labels either in separate data fields or in a single data
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith field, but as separate properties of a value object. This allows the data
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith to be used for calculations such as sorting or averaging.
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith<h4 id="formatter-function">Setting content with `formatter` functions</h4>
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith Set the cell content with column `formatter`s by returning the desired
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith content string from the function. Alternately, just update `o.value` with
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith the new value in the object passed as an argument to the `formatter`. When
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith updating `o.value` <em>do not include a return statement</em>.
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith `formatters` are very powerful because not only do they have access to the
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith record's value for that column's field, but they also receive the rest of
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith the record's data, the record Model instance itself, and the column
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith configuration object. This allows you to include any extra configurations
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith in your column configuration that might be useful to customizing how cells
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith in the column are rendered.
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smithfunction currency(o) {
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith decimalPlaces : o.column.decimalPlaces || 2,
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith decimalSeparator : o.column.decimalSeparator || '.',
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith thousandsSeparator: o.column.thousandsSeparator || ','
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith { key: "price", formatter: currency, decimalPlaces: 3 },
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith See <a href="#formatter-props">Appendix B</a> for a list of all properties
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith passed to `formatter` functions.
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith<h4 id="nodeformatters">Setting content with `nodeFormatter` functions</h4>
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith Unlike `formatters` which can effectively default to the normal rendering
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith logic by leaving `o.value` unchanged, `nodeFormatters` must assign content
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith to the cells themselves. The cell's initial classes will be set up, but
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith that's it. Everything else is your responsibility.
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <strong>`nodeFormatter`s should return `false`</strong>.
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <a href="formatter-vs-nodeformatter">See below</a> for details.
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith While there are <a href="#formatter-vs-nodeformatter">few scenarios that
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith require `nodeFormatter`s</a>, they do have the benefits of having the Node
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith API for constructing more complex DOM subtrees and the ability to access
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith all nodes in the `<tbody>`. This means they can reference, and even modify,
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith cells in other rows.
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith Like `formatters`, `nodeFormatters` are provided with the data field value,
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith the record data, the record Model instance, and the column configuration
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith See <a href="#nodeformatter-props">Appendix C</a> for a list of all
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith properties passed to `nodeFormatter` functions.
9563d8a01a40e508f7697d9c674c164512940371Luke Smith<h4 id="formatter-vs-nodeformatter">Why `formatter` and `nodeFormatter`?</h4>
9563d8a01a40e508f7697d9c674c164512940371Luke Smith For good rendering performance and memory management, DataTable creates
9563d8a01a40e508f7697d9c674c164512940371Luke Smith table content by assembling `innerHTML` strings from templates, with
9563d8a01a40e508f7697d9c674c164512940371Luke Smith `{placeholder}` tokens replaced with your data. However, this means that
9563d8a01a40e508f7697d9c674c164512940371Luke Smith the Nodes don't exist yet when a column's `formatter`s are applied.
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith To minimize the need to create Nodes for each cell, the default rendering
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith logic supports the addition of cell classes as well as row classes via
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith `formatter` functions. Event subscriptions should be
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith <a href="http://yuilibrary.com/yui/docs/event/delegation.html">delegated</a>
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith from the DataTable instance itself using the
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith <a href="http://yuilibrary.com/yui/docs/api/classes/DataTable.html#method_delegate">`delegate()` method</a>.
9563d8a01a40e508f7697d9c674c164512940371Luke Smith On the rare occasion that you <em>must</em> use Nodes to supply the cell
9563d8a01a40e508f7697d9c674c164512940371Luke Smith data, DataTable allows a second pass over the generated DOM elements once
9563d8a01a40e508f7697d9c674c164512940371Luke Smith the initial string concatenation has been completed and the full HTML
9563d8a01a40e508f7697d9c674c164512940371Luke Smith content created.
9563d8a01a40e508f7697d9c674c164512940371Luke Smith It is important to note that `nodeFormatters` will necessarily create a
9563d8a01a40e508f7697d9c674c164512940371Luke Smith Node instance for each cell in that column, which will increase the memory
9563d8a01a40e508f7697d9c674c164512940371Luke Smith footprint of your application. If the Node instance wrappers around the
9563d8a01a40e508f7697d9c674c164512940371Luke Smith DOM elements don't need to be maintained beyond the life of the
9563d8a01a40e508f7697d9c674c164512940371Luke Smith `nodeFormatter`, return `false` to remove them from the internal object
9563d8a01a40e508f7697d9c674c164512940371Luke Smith cache. <strong>This will not remove the rendered DOM, but it will remove
9563d8a01a40e508f7697d9c674c164512940371Luke Smith event subscriptions made on those Nodes</strong>.
9563d8a01a40e508f7697d9c674c164512940371Luke Smith In general, `nodeFormatter`s should only be used if absolutely necessary,
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith and should <em>always return `false`</em>.
9563d8a01a40e508f7697d9c674c164512940371Luke Smith<h4 id="formatters-vs-empty">Formatters vs. `emptyCellValue`</h4>
9563d8a01a40e508f7697d9c674c164512940371Luke Smith The `emptyCellValue` configuration is useful to provide fallback content in
9563d8a01a40e508f7697d9c674c164512940371Luke Smith the case of missing or empty column data, but it interacts with each type of
9563d8a01a40e508f7697d9c674c164512940371Luke Smith formatter differently.
9563d8a01a40e508f7697d9c674c164512940371Luke Smith String formatters will only be applied if the field data for that cell is
9563d8a01a40e508f7697d9c674c164512940371Luke Smith not `undefined`. This allows the `emptyCellValue` to populate the cell.
9563d8a01a40e508f7697d9c674c164512940371Luke Smith Function formatters are applied before the return value or (potentially
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith altered) `o.value` property is tested for `undefined`, `null`, or the empty
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith string. In any of these cases, the `emptyCellValue` populates the cell.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith The `emptyCellValue` configuration is ignored by columns configured with
4e67a495f88a68220462c5e1149e16824b566cc1Luke Smith `nodeFormatter`s.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith<h2 id="data">Table Data Configuration</h2>
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith Each record in the table is stored as a
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith <a href="../model/index.html">Model</a> instance, where the
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith keys of the record objects become Model attributes. This allows you to
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith interact with the models as you would any other <a
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith href="../base/index.html">Base</a>-based class, with `get(attr)`,
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith `set(attr, value)`, and subscribing to attribute change events.
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith { item: "widget", cost: 23.57, price: 47.5 },
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith { item: "gadget", cost: 0.11, price: 6.99 },
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith { item: "sprocket", cost: 4.08, price: 3.75 },
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith { item: "nut", cost: 0.01, price: 0.25 }
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smithvar table = new Y.DataTable({
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith columns: ["item", "cost", "price"],
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smithvar sprocket = table.getRecord(2);
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith// Fires a costChange event, and the table is updated if rendered
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith The Model class used to store the record data is created for you, based on
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith the objects in the `data` array. If `data` is not set, the column keys
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith identified in the `columns` configuration is used.
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith<h3 id="recordtype">Specifying the Record Model</h3>
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith To use a custom Model for your records, pass your Model subclass to the
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith `recordType` attribute.
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smithvar pieTable = new Y.DataTable({
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith columns: ['slices', 'type'],
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith // Y.PieModel has attributes 'slices', which defaults to 6, and 'type',
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith // which defaults to 'apple'. Records can use these defaults.
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith { type: 'lemon meringue' },
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith { type: 'chocolate creme', slices: 8 },
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith {} // equivalent to { type: 'apple', slices: 6 }
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith// Y.PieModel has its idAttribute assigned to 'type', overriding the default
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith// of 'id'. Fetch a PieModel by its id.
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smithvar applePie = pieTable.getRecord('apple');
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith// eatSlice is a method on the Y.PieModel prototype
7259228103d208da99917c38078645574f3dac7fLuke Smith Alternately, `recordType` will accept an array of attribute strings or an
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith `ATTRS` configuration object to make it easier to create custom attribute
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith behaviors without needing to explicitly build the Model subclass.
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith If the `columns` configuration is omitted, but the `recordType` is set, the
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith `columns` will default to the `recordType`'s attributes.
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith { item: "widget", cost: 23.57, price: 47.5 },
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith { item: "gadget", cost: 0.11, price: 6.99 },
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith { item: "sprocket", cost: 4.08, price: 3.75 },
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith { item: "nut", cost: 0.01, price: 0.25 }
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith// Effectively synonymous with setting the columns attribute if no special
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith// column configuration is needed.
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smithvar table = new Y.DataTable({
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith recordType: [ 'item', 'cost', 'price' ],
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith// Or for more control, pass an ATTRS configuration object
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smithvar table = new Y.DataTable({
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith recordType: {
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith setter: function (val) { return +val || 0; }
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith valueFn: function () { return (this.get('cost') + 0.1) * 10; },
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith setter: function (val) { return +val || 0; }
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith When the table data is loaded asychronously, it is often a good idea to
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith configure the `recordType`. This can prevent the generation of a record
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith Model that is missing fields that are omitted from the `columns`
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith configuration because they aren't intended for viewing.
acf1a78b9c946fbd3560053c3390089b37ce6072Luke Smith<h3 id="modellist">The `data` ModelList</h3>
7259228103d208da99917c38078645574f3dac7fLuke Smith The record Models are stored in a
7259228103d208da99917c38078645574f3dac7fLuke Smith <a href="../model-list/index.html">ModelList</a>, which is assigned to the
7259228103d208da99917c38078645574f3dac7fLuke Smith `data` <em>property</em> on the instance (for easier access than going through `table.get('data')`).
7259228103d208da99917c38078645574f3dac7fLuke Smithvar records = [
7259228103d208da99917c38078645574f3dac7fLuke Smith { item: "widget", cost: 23.57, price: 47.5 },
7259228103d208da99917c38078645574f3dac7fLuke Smith { item: "gadget", cost: 0.11, price: 6.99 },
7259228103d208da99917c38078645574f3dac7fLuke Smith { item: "sprocket", cost: 4.08, price: 3.75 }
9563d8a01a40e508f7697d9c674c164512940371Luke Smithvar table = new Y.DataTable({
7259228103d208da99917c38078645574f3dac7fLuke Smith columns: ["item", "cost", "price"],
7259228103d208da99917c38078645574f3dac7fLuke Smith data : records
7259228103d208da99917c38078645574f3dac7fLuke Smith// Add a new Model using the ModelList API. This will fire
7259228103d208da99917c38078645574f3dac7fLuke Smith// events and change the table if rendered.
7259228103d208da99917c38078645574f3dac7fLuke Smithtable.data.add({ item: "nut", cost: 0.01, price: 0.25 });
7259228103d208da99917c38078645574f3dac7fLuke Smith When assigning the DataTable's `data` attribute with an array, a ModelList
7259228103d208da99917c38078645574f3dac7fLuke Smith is created for you. But you can also pass a ModelList instance if you are
7259228103d208da99917c38078645574f3dac7fLuke Smith sharing a ModelList between widgets on the page, or you have created custom
7259228103d208da99917c38078645574f3dac7fLuke Smith Model and ModelList classes with additional logic, such as adding a
7259228103d208da99917c38078645574f3dac7fLuke Smith <a href="../model-list/#implementing-a-list-sync-layer">data sync layer</a>.
7259228103d208da99917c38078645574f3dac7fLuke Smithvar table = new Y.DataTable({
7259228103d208da99917c38078645574f3dac7fLuke Smith columns: ['type', 'slices'],
7259228103d208da99917c38078645574f3dac7fLuke Smith// The Y.PieList class implements a sync layer, enabling its load() method
7259228103d208da99917c38078645574f3dac7fLuke Smith<h3 id="getting-data">Getting Remote Table Data</h3>
7259228103d208da99917c38078645574f3dac7fLuke Smith To fetch remote data, you have three options:
7259228103d208da99917c38078645574f3dac7fLuke Smith <strong>For quick one-offs</strong>, you can load and parse the
7259228103d208da99917c38078645574f3dac7fLuke Smith data manually, using `Y.io(...)`, `Y.jsonp(...)`, etc., then assign
7259228103d208da99917c38078645574f3dac7fLuke Smith that data to the DataTable's `data` attribute. This isn't very
7259228103d208da99917c38078645574f3dac7fLuke Smith elegant or maintainable, so is best avoided for anything other than
7259228103d208da99917c38078645574f3dac7fLuke Smith proofs of concept.
7259228103d208da99917c38078645574f3dac7fLuke Smith <strong>For the most control</strong>, better maintainability, and
7259228103d208da99917c38078645574f3dac7fLuke Smith better encapsulation of business logic, create Model and ModelList
7259228103d208da99917c38078645574f3dac7fLuke Smith subclasses that
7259228103d208da99917c38078645574f3dac7fLuke Smith <a href="../model-list/#implementing-a-list-sync-layer">implement a
7259228103d208da99917c38078645574f3dac7fLuke Smith sync layer</a> as suggested above.
7259228103d208da99917c38078645574f3dac7fLuke Smith <strong>For common read-only scenarios</strong>, use the
7259228103d208da99917c38078645574f3dac7fLuke Smith <a href="{{apiDocs}}/classes/Plugin.DataTableDataSource.html">`Y.Plugin.DataTableDataSource`</a>
7259228103d208da99917c38078645574f3dac7fLuke Smith plugin to bind your table to a
7259228103d208da99917c38078645574f3dac7fLuke Smith <a href="../datasource/index.html">`DataSource`</a> instance. Use
7259228103d208da99917c38078645574f3dac7fLuke Smith plugins to add DataSource features.
7259228103d208da99917c38078645574f3dac7fLuke Smith// Create a JSONP DataSource to query YQL
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithvar myDataSource = new Y.DataSource.Get({
7259228103d208da99917c38078645574f3dac7fLuke Smith source: 'http://query.yahooapis.com/v1/public/yql?format=json&' +
7259228103d208da99917c38078645574f3dac7fLuke Smith 'env=store%3A%2F%2Fdatatables.org%2Falltableswithkeys&q='
7259228103d208da99917c38078645574f3dac7fLuke SmithmyDataSource.plug(Y.Plugin.DataSourceJSONSchema, {
7259228103d208da99917c38078645574f3dac7fLuke Smith resultListLocator: 'query.results.Result',
7259228103d208da99917c38078645574f3dac7fLuke Smith resultFields: [
7259228103d208da99917c38078645574f3dac7fLuke Smith // Important that record fields NOT include ".", so
7259228103d208da99917c38078645574f3dac7fLuke Smith // extract nested data with locators
7259228103d208da99917c38078645574f3dac7fLuke Smith key: 'Rating',
7259228103d208da99917c38078645574f3dac7fLuke Smith// No data is provided at construction because it will load via the
7259228103d208da99917c38078645574f3dac7fLuke Smith// DataTableDataSource plugin
9563d8a01a40e508f7697d9c674c164512940371Luke Smithvar table = new Y.DataTable({
7259228103d208da99917c38078645574f3dac7fLuke Smith columns: ['Title', 'Phone', 'Rating'],
7259228103d208da99917c38078645574f3dac7fLuke Smith summary: 'Pizza places near 98089'
7259228103d208da99917c38078645574f3dac7fLuke Smith datasource: myDataSource
7259228103d208da99917c38078645574f3dac7fLuke Smith// Initially render an empty table and show a loading message
7259228103d208da99917c38078645574f3dac7fLuke Smith .showMessage('loadingMessage');
7259228103d208da99917c38078645574f3dac7fLuke Smith// Load the data into the table
7259228103d208da99917c38078645574f3dac7fLuke Smith request: encodeURIComponent(
7259228103d208da99917c38078645574f3dac7fLuke Smith 'select *' +
7259228103d208da99917c38078645574f3dac7fLuke Smith ' where zip="94089"' +
7259228103d208da99917c38078645574f3dac7fLuke Smith ' and query="pizza"');
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith<h2 id="features">DataTable Modules and Features</h2>
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith For a basic, stripped down `Y.DataTable` class, include the `datatable-base`
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith module in your `use()`.
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith Feature modules, such as `datatable-sort`, will bring in `datatable-base`
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith automatically. By including only feature modules in your `use()`, you will
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith get a `Y.DataTable` that supports specifically those features, without
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith extra code for other features you won't be using.
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith The `datatable` module is a bundle of `datatable-base` plus a set of common
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith feature modules. Other feature modules need to be included explicitly in
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith <th>Module</th>
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith <th>Description</th>
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith <th>In `datatable`?</th>
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith <td><a href="{{apiDocs}}/modules/datatable-core.html">`datatable-core`</a></td>
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith The core API for DataTable, implemented as a class extension, used
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith by `datatable-base` to create `Y.DataTable` and `Y.DataTable.Base`.
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith <td>yes</td>
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith <td><a href="{{apiDocs}}/modules/datatable-base.html">`datatable-base`</a></td>
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith Creates the `Y.DataTable` and `Y.DataTable.Base` classes, and
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith defaults the `headerView` and `bodyView` to `Y.DataTable.HeaderView`
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith and `Y.DataTable.BodyView` respectively.
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith <td>yes</td>
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith <td><a href="{{apiDocs}}/modules/datatable-head.html">`datatable-head`</a></td>
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith Creates the `Y.DataTable.HeaderView` class as a subclass of
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith `Y.View`. DataTable defers rendering of the `<thead>` content to
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith this View when it is passed as the DataTable's `headerView`
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith attribute (the default, as set by `datatable-base`).
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith <td>yes</td>
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith <td><a href="{{apiDocs}}/modules/datatable-body.html">`datatable-body`</a></td>
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith Creates the `Y.DataTable.BodyView` class as a subclass of
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith `Y.View`. DataTable defers rendering of the `<tbody>` content to
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith this View when it is passed as the DataTable's `bodyView`
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith attribute (the default, as set by `datatable-base`).
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith <td>yes</td>
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith <td><a href="{{apiDocs}}/modules/datatable-message.html">`datatable-message`</a></td>
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith Creates the `Y.DataTable.Message` class extension and adds
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith `showMessage` and `hideMessage` methods to `Y.DataTable`.
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith <td>yes</td>
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith <td><a href="{{apiDocs}}/modules/datatable-column-widths.html">`datatable-column-widths`</a></td>
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith Creates the `Y.DataTable.ColumnWidths` class extension, and adds
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith support for the `width` property in column configuration objects
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith <td>yes</td>
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith <td><a href="{{apiDocs}}/modules/datatable-mutable.html">`datatable-mutable`</a></td>
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith Creates the `Y.DataTable.Mutable` class extension and adds methods
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith such as `addRow`, `removeRow`, and `moveColumn` to `Y.DataTable`.
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith <td>yes</td>
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith <td><a href="{{apiDocs}}/modules/datatable-sort.html">`datatable-sort`</a></td>
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith Creates the `Y.DataTable.Sort` class extension and adds methods
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith `sort` and `toggleSort` as well as attributes `sortable` and
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith `sortBy` to `Y.DataTable`. Enables sorting the table rows by
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith clicking on column headers.
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith <td>yes</td>
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith <td><a href="{{apiDocs}}/modules/datatable-datasource.html">`datatable-datasource`</a></td>
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith Creates the `Y.Plugin.DataTableDataSource` plugin for binding a
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith DataSource instance to the table as its source of record data.
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith <td>yes</td>
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith <td><a href="{{apiDocs}}/modules/datatable-scroll.html">`datatable-scroll`</a></td>
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith Creates the `Y.DataTable.Scroll` class extension and adds attribute
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith `scrollable` to `Y.DataTable`. Adds support for vertically and/or
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith horizontally scrolling table rows within fixed table dimensions.
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith<h3 id="base">Features in `DataTable.Base`</h3>
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith By including only `datatable-base` in your `use()` line, you get both
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith `Y.DataTable` and `Y.DataTable.Base` classes. With no other module
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith inclusion, these classes are effectively the same. When additional
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith DataTable related modules are included, those modules' features will
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith usually be added to `Y.DataTable`, but <strong>never</strong> to
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith Though it can be instantiated, the purpose of `Y.DataTable.Base` is
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith primarily as a superclass to a custom DataTable implementation that has a
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith locked set of features that will not be modified, as `Y.DataTable` can be,
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith by the inclusion of other modules.
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith// Create a custom DataTable that includes only the core set of APIs, plus
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith// sorting and message support.
1f0b5989221c9f985c461d18e10067e38d55c470Luke SmithY.MyDataTable = Y.Base.create('myTable', Y.DataTable.Base,
1f0b5989221c9f985c461d18e10067e38d55c470Luke SmithY.use('datatable-scroll', function (Y) {
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith // Y.DataTable now has support for scrolling
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith var table = new Y.DataTable({ scrollable: 'y', ... });
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith // Y.MyDataTable does not (the config does nothing)
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith var myTable = new Y.MyDataTable({ scrollable: 'y', ... });
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith `Y.DataTable.Base` includes the `columns`, `data`, `caption`, and other
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith basic table attributes, the underlying ModelList and View rendering
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith architecture, as well as methods to fetch rows and cells or columns and
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith Rendering features include most column configurations, such as `children`
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith and `allowHTML`, as well as column formatting options `formatter`,
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith `nodeFormatter`, `cellTemplate`, etc.
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith<h3 id="datatable-message">Table Messages</h3>
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith The `datatable-message` module adds the ability to display a message in the
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith table body. By default, the "emptyMessage" will display when the table's
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith ModelList has no data records. The message will hide when data is added.
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smithvar table = new Y.DataTable({
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith columns: ["id", "name", "price"],
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith}).render('#example');
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith<p>This code produces this table:</p>
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith<div id="message-example" class="yui3-skin-sam"></div>
1f0b5989221c9f985c461d18e10067e38d55c470Luke SmithYUI({ filter: 'raw' }).use('datatable-message', function (Y) {
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith var table = new Y.DataTable({
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith columns: ["id", "name", "price"],
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith }).render('#message-example');
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith Use `table.showMessage("message")` and `table.hideMessage()` to toggle the
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith message display.
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith `showMessage` supports internationalized strings by using a few named
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith strings, which are registered in the language packs for the
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith `datatable-message` module . These strings are currently:
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith `table.showMessage("emptyMessage")` defaults to "No data to display".
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith `table.showMessage("loadingMessage")` defaults to "Loading...".
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith Other values passed to `showMessage` will pass that content directly
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith through to the message Node.
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith<h3 id="colwidths">Column Width Configuration</h3>
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith The `datatable-column-widths` module adds basic support for specifying
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith column widths.
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smithvar table = new Y.DataTable({
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith { key: 'item', width: '125px' },
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith { key: 'cost', formatter: '${value}' },
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith}).render("#example");
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith<p>This code produces this table:</p>
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith<div id="colwidths-example" class="yui3-skin-sam"></div>
1f0b5989221c9f985c461d18e10067e38d55c470Luke SmithYUI({ filter: 'raw' }).use('datatable-column-widths', function (Y) {
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith var data = [
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith { item: "widget", cost: 23.57, price: 47.5 },
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith { item: "gadget", cost: 0.11, price: 6.99 },
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith { item: "sprocket", cost: 4.08, price: 3.75 },
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith { item: "nut", cost: 0.01, price: 0.25 }
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith var table = new Y.DataTable({
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith { key: 'item', width: '125px' },
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith { key: 'cost', formatter: '${value}' },
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith { key: 'price', formatter: '${value}' },
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith { key: 'profit', formatter: function (o) {
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith return (((price - cost) / cost) * 100).toFixed(2) + '%';
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith }).render("#colwidths-example");
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith <strong>CAVEAT</strong>: Column widths will expand beyond the configured
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith value if column cells contain data that is long and can't line-wrap. Also,
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith column widths may be reduced below the configured value if the table width
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith (by configuring the DataTable's `width` attribute, or constrained by a
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith narrow containing element) is too narrow to fit all data at the configured
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith To force column widths, including cell data truncation and allowing the
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith table to spill beyond its configured or inherited width, wrap the cell
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith content in a `<div>` either by configuring the column's `formatter` or
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith `cellTemplate`, then assign the `<div>`'s CSS style with the desired width
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith (or "inherit"), plus `overflow: hidden;`. Then set the DataTable column's
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith `width` configuration accordingly.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h3 id="sorting">Column sorting</h3>
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith The `datatable-sort` module adds support for sorting the table rows either
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith through the added APIs or by clicking on the table headers.
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith By default, when `datatable-sort` is included, DataTables will inspects
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith the `columns` objects, looking for `sortable: true` to enable table sorting
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith by those columns, triggered by clicking on their respective headers.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { key: "Company", sortable: true },
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { key: "Phone" },
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { key: "Contact", sortable: true }
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith For convenience, you can enable header-click sorting for all columns by
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith setting the `sortable` attribute to `true`, or pass an array of column keys
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith to enable just those column's headers.
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith// Set all columns to be sortable
9563d8a01a40e508f7697d9c674c164512940371Luke Smithvar table = new Y.DataTable({
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith columns: ["Company", "Phone", "Contact"],
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith sortable: true
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith}).render("#example");
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith<p>This code produces this table:</p>
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith<div id="sort-example1" class="yui3-skin-sam"></div>
1f0b5989221c9f985c461d18e10067e38d55c470Luke SmithYUI({ filter: 'raw' }).use('datatable-sort', function (Y) {
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith var table = new Y.DataTable({
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith columns: ['Company', 'Phone', 'Contact'],
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith { Company: "Company Bee", Phone: "415-555-1234", Contact: "Sally Spencer"},
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith { Company: "Acme Company", Phone: "650-555-4444", Contact: "John Jones"},
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith { Company: "Indutrial Industries", Phone: "408-555-5678", Contact: "Robin Smith"}
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith sortable: true
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith }).render('#sort-example1');
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith Hold down the `shift` key while clicking on column headers to subsort by
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith that column. Doing so repeatedly will toggle the subsort direction.
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith As long as the `datatable-sort` module has been included, you will always
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith be able to sort the table data through the API, even by columns that aren't
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith configured to accept header-click sorting.
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith When a table is sorted, any new records added to the DataTable's ModelList
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith will be inserted at the proper sorted index, as will the created table
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith Disable header-click sorting by setting `sortable` to `false`.
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith<h4 id="customsort">Custom Sorting</h4>
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith Assign a function to a column's `sortFn` to support customized sorting. The
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith function will receive the two records being compared and a boolean flag
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith indicating a descending sort was requested.
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smithvar columns = [
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith label: '●', // a big dot
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith formatter: function (o) {
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith return o.value ? '' : '●'; // only new records have a dot
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith sortable: true,
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith sortFn: function (a, b, desc) {
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith var aid = a.get('id'),
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith bid = b.get('id'),
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith acid = a.get('clientId'),
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith bcid = b.get('clientId'),
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith order = // existing records are equivalent
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith (aid && bid) ? 0 :
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith // new records are grouped apart from existing records
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith (aid && -1) || (bid && 1) ||
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith // new records are sorted by insertion order
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith (acid > bcid) ? 1 : -(acid < bcid);
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith return desc ? -order : order;
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith The function must return 1, 0, or -1. 1 specifies that the Model passed as
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith the first parameter should sort below the Model passed as the second
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith parameter. -1 for above, and 0 if they are equivalent for the purpose of
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith<h4 id="sortapi">Sorting Methods</h4>
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith To sort the table in the code, call `table.sort(NAME OR KEY)`. To
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith toggle the sort direction, call `table.toggleSort(NAME OR KEY)`.
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith// Sorts the table by values in the price field in ascending order
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith// Flips to descending
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith To sort by multiple columns, pass an array of column keys to `sort` or
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith `toggleSort`.
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith Calling `toggleSort` with no arguments will reverse all current sort
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith directions. Calling with specific column names or keys will toggle only
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith those columns.
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith// Sort first by author, subsort by title in ascending order
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smithtable.sort(['author', 'title']);
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith// Now descending by author then title
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith// same as table.toggleSort(['author', 'title']);
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith// Now ascending by author, descending by title
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith To specify a sort direction, pass an object instead of a string to `sort`.
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith The object should have the column name as the key, and sort direction as its
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith// Explicitly sort by price in descending order
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smithtable.sort({ price: 'desc' });
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith// Each column gets its own object
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smithtable.sort([{ author: 'desc' }, { title: 'desc' }]);
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith Acceptable values for the sort direction are "asc", "desc", 1, and -1. 1 is
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith equivalent to "asc", and -1 to "desc".
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith<h4 id="sortby">The `sortBy` Attribute</h4>
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith Every sort operation updates the `sortBy` attribute. You can also trigger
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith a sort by setting this attribute directly. It accepts the same values as
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith the `sort` method.
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith// Sort by author in descending order, then by title in ascending order
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smithtable.set('sortBy', [{ author: -1 }, 'title']);
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith To specify an initial sort order for your table, assign this attribute
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith during instantiation. This will sort the data as soon as it is added
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith to the table's ModelList.
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith// Pre-sort the data
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smithvar table = new Y.DataTable({
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith columns: ['item', 'cost', 'price'],
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith data: [...],
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith sortBy: { price: -1 }
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith<h4 id="sortevent">The `sort` Event</h4>
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith Clicking on a column header, or calling the `sort` or `toggleSort` methods
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith will fire a `sort` method containing an `e.sortBy` property that
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith corresponds to the requested sort column and direction. The value will be
8bd9b02c76091e87124abd4afa3d798e637abb3cLuke Smith in either string or object format, depending on how each method was used.
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith Preventing the `sort` event will prevent the `sortBy` attribute from being
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith updated. Updating the `sortBy` attribute directly will not fire the `sort`
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith event, but will still sort the data and update the table.
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith<h3 id="mutation">Table Mutation APIs (`addRow`, etc)</h3>
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith The `datatable-mutable` module adds APIs for adding, removing, and
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith modifying records and columns.
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith<h4 id="column-mutation">Column Mutation Methods</h4>
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith Use the methods `addColumn`, `removeColumn`, `modifyColumn`, and
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith `moveColumn` to update the table's configured `columns`.
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith// Insert a column for the profit field in the data records as the third column
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith// Actually, make that the fourth column
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith// Actually, strike that. Don't show it after all
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith// Instead, add a formatter to the price column that includes the profit data
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith formatter: function (o) {
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith return o.value + ' (' + (o.data.profit / o.data.cost).toFixed(2) + '%)';
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith Each column mutation method fires an identically named event. See
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith <a href="{{apiDocs}}/classes/DataTable.html">the API docs</a> for details.
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith<h4 id="row-mutation">Row Mutation Methods</h4>
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith Use the methods `addRow`, `addRows`, `removeRow`, and `modifyRow` to update
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith the table's ModelList.
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smithtable.addRow({ item: 'collet', cost: 0.42, price: 2.65 });
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { item: 'nut', cost: 0.42, price: 2.65 },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { item: 'washer', cost: 0.01, price: 0.08 },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { item: 'bit', cost: 0.19, price: 0.97 }
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith// Remove table records by their Model, id, clientId, or index
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith// Modify a record by passing its id, clientId, or index, followed by an
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith// object with new field values
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smithtable.modifyRow('record_4', { cost: 0.74 });
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith Everything that's done by these methods can be accomplished through the
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith table's ModelList instance methods, but having methods on the table itself
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith can make the code more readable.
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith// Same as table.addRow(...);
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smithtable.data.add({ item: 'collet', cost: 0.42, price: 2.65 });
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith By default, changes made to the table are only local, they don't update the
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith server or other data origin if the data was served remotely. However, if
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith your table's ModelList is built with a sync layer, the mutation methods
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith can also trigger the appropriate sync behavior by passing an additional
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith argument to the methods, an object with the property `sync` set to `true`.
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith// Tell the server we're down to one slice of apple pie!
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smithtable.modifyRow('apple', { slices: 1 }, { sync: true });
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith// Uh oh, make that 0. No more apple pie :(
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smithtable.removeRow('apple', { sync: true });
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith If all modifications are destined for the server/origin, you can set the
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith `autoSync` attribute to `true`, and the row mutation methods will
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith automatically call into the sync layer.
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smithvar pies = new Y.DataTable({
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith columns: ['type', 'slices'],
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith autoSync: true
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith // The new PieModel's save() method is called, notifying the server
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith pies.addRow({ type: 'pecan', slices: 8 });
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith // Let us eat some pie!
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith pies.modifyRow('lemon meringue', { slices: 5 });
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h3 id="scrolling">Scrolling</h3>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <strong>Note:</strong> Scrolling is not currently supported on the Android
5992781dfab2b64f79fee03abd15d9a91e2f5b77Luke Smith WebKit browser.
91fbdecc877af568d808d97489239c2ab08a249eLuke Smith Scrolling functionality can be added to `Y.DataTable` by including
91fbdecc877af568d808d97489239c2ab08a249eLuke Smith `datatable-scroll` module in your `use()`. `datatable-scroll` is
91fbdecc877af568d808d97489239c2ab08a249eLuke Smith <strong>NOT</strong> included in the `datatable` rollup module, so must be
91fbdecc877af568d808d97489239c2ab08a249eLuke Smith included separately.
91fbdecc877af568d808d97489239c2ab08a249eLuke Smith Enable scrolling by setting the `scrollable` attribute, which accepts values
91fbdecc877af568d808d97489239c2ab08a249eLuke Smith "x", "y", "xy", `true` (same as "xy"), or `false` (the default).
9563d8a01a40e508f7697d9c674c164512940371Luke Smith Note, vertical scrolling also requires the table's `height` attribute to be
9563d8a01a40e508f7697d9c674c164512940371Luke Smith set, and horizontal scrolling requires the `width` to be set.
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith// Data from the seafoodwatch YQL table as of 3/16/2012
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Barramundi (Imported Farmed in Open Systems)", "recommendation": "avoid" },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Caviar, Paddlefish (Wild caught from U.S.)", "recommendation": "avoid" },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Caviar, Sturgeon (Imported Wild-caught)", "recommendation": "avoid" },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith// Enable vertical scrolling with scrollable "y". The width is also set, but
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith// because scrollable is not "x" or "xy", this just sets the table width.
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smithvar table = new Y.DataTable({
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith caption: 'Seafood tips for the US West Coast',
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith columns: ['fish', 'recommendation'],
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith scrollable: "y",
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith height: "200px",
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith width: "400px"
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith}).render("#scroll");
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith<p>This code produces this table:</p>
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith<div id="scroll-example" class="yui3-skin-sam"></div>
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke SmithYUI().use('datatable-scroll', function (Y) {
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith// Data from the seafoodwatch YQL table as of 3/16/2012
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Barramundi (Imported Farmed in Open Systems)", "recommendation": "avoid" },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Caviar, Paddlefish (Wild caught from U.S.)", "recommendation": "avoid" },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Caviar, Sturgeon (Imported Wild-caught)", "recommendation": "avoid" },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Chilean Seabass", "recommendation": "avoid" },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Cobia (Imported Farmed)", "recommendation": "avoid" },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Cod, Atlantic (Trawl-caught from Canadian and U.S. Atlantic)", "recommendation": "avoid" },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Cod, Pacific (Imported)", "recommendation": "avoid" },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Crab, King (Imported)", "recommendation": "avoid" },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Dab, Common (Danish Seine from Iceland)", "recommendation": "avoid" },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Flounder (Wild-caught from U.S. Atlantic, Except Summer Flounder)", "recommendation": "avoid" },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Hake, White", "recommendation": "avoid" },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Halibut, Atlantic (Wild-caught from U.S.)", "recommendation": "avoid" },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Lobster, Caribbean Spiny (Brazil)", "recommendation": "avoid" },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Mahi Mahi (Imported Longline)", "recommendation": "avoid" },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Marlin, Blue (Imported)", "recommendation": "avoid" },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Marlin, Striped", "recommendation": "avoid" },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Monkfish", "recommendation": "avoid" },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Octopus (Philippines)", "recommendation": "avoid" },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Orange Roughy", "recommendation": "avoid" },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Plaice, American (Wild-caught from U.S. Atlantic)", "recommendation": "avoid" },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Pollock, Atlantic (Danish Seine and Trawl from Iceland)", "recommendation": "avoid" },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Salmon (Farmed including Atlantic Except U.S. Farmed in Tank Systems)", "recommendation": "avoid" },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Sardines, Atlantic (Mediterranean)", "recommendation": "avoid" },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Shad, American (U.S. Atlantic Gillnet)", "recommendation": "avoid" },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Shark (Except Common Thresher and Shortfin Mako, from California and Hawaii)", "recommendation": "avoid" },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Shrimp (Imported Farmed Except Thailand Farmed in Fully Reciruclating Systems)", "recommendation": "avoid" },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Shrimp (Imported Wild-Caught Except Canadian)", "recommendation": "avoid" },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Shrimp (Mexico Farmed in Open Systems)", "recommendation": "avoid" },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Skates", "recommendation": "avoid" },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Snapper, Red (U.S. Gulf of Mexico Wild-caught)", "recommendation": "avoid" },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Snapper, Red (Imported Wild-caught)", "recommendation": "avoid" },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Sole (Wild-caught from U.S Atlantic)", "recommendation": "avoid" },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Sturgeon (Imported Wild-caught)", "recommendation": "avoid" },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith { "fish": "Swordfish (Imported)", "recommendation": "avoid" }
9563d8a01a40e508f7697d9c674c164512940371Luke Smithvar table = new Y.DataTable({
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith caption: 'Seafood tips for the US West Coast',
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith columns: ['fish', 'recommendation'],
9563d8a01a40e508f7697d9c674c164512940371Luke Smith scrollable: "y",
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith height: "200px",
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith width: "400px" // scrollable is not set to x or xy, so no scrolling
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith}).render("#scroll-example");
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith<h2 id="events">DataTable Events</h2>
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith DataTable is a composition of supporting class instances and extensions, so
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith to centralize event reporting, it is a bubble target for its `data`
8bd9b02c76091e87124abd4afa3d798e637abb3cLuke Smith ModelList as well as the View instances used for rendering.
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith In other words, some events you may need to subscribe to using an event
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith prefix to be notified. Often, using a wildcard prefix is the simplest
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith method to ensure your subscribers will be notified, even if classes change.
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith// The sort event is from an extension, so it originates from DataTable
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smithtable.after('sort', function (e) { ... });
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith// Model changes originate from the record's Model instance, propagate to the
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith// table's ModelList, then finally to the DataTable, so they must be
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith// subscribed with an event prefix. In this case, we'll use a wildcard
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smithtable.after('*:priceChange', function (e) { ... });
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith DataTable generates a custom Model class with the "record" event prefix, if
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith you want to be more specific. Otherwise, if your table uses a custom Model
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith class for its `recordType`, you can prefix Model events with the appropriate
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith// Allow DataTable to generate the Model class automatically
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smithvar table = new Y.DataTable({
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith columns: ['items', 'cost', 'price'],
8bd9b02c76091e87124abd4afa3d798e637abb3cLuke Smith { item: "widget", cost: 23.57, price: 47.5 },
8bd9b02c76091e87124abd4afa3d798e637abb3cLuke Smith { item: "gadget", cost: 0.11, price: 6.99 },
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith// generated Model classes have prefix "record"
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smithtable.after('record:change', function (e) { ... });
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith// PieList uses PieModels, which have a prefix of, you guessed it, "pie"
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smithvar pies = new Y.DataTable({
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith columns: ['type', 'slices'],
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smithpies.on('pie:slicesChange', function (e) {
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith if (e.target.get('type') === 'chocolate creme') {
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith // Oh no you don't!
8c70b4a0ea2b6a9387e2f68c4cfa758e72a431d0Luke Smith The full list of events is included in <a href="{{apiDocs}}/classes/DataTable.html#events">the DataTable API docs</a>.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h2 id="knownissues">Known Issues</h2>
f85539ee51e30adb584249d2c134280e8191447dLuke Smith Scrolling is
f85539ee51e30adb584249d2c134280e8191447dLuke Smith <a href="http://yuilibrary.com/projects/yui3/ticket/2529761">not
f85539ee51e30adb584249d2c134280e8191447dLuke Smith currently supported on Android</a> WebKit browser.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith Scrolling DataTable
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith <a href="http://yuilibrary.com/projects/yui3/ticket/2531047">may not
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith appear scrollable</a> on iOS browsers or OS X 10.7 depending on the
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith system preference "Show scroll bars" (General).
9563d8a01a40e508f7697d9c674c164512940371Luke Smith<h2 id="column-config">Appendix A: Column Configurations</h2>
9563d8a01a40e508f7697d9c674c164512940371Luke Smith The properties below are supported in the column configuration objects
9563d8a01a40e508f7697d9c674c164512940371Luke Smith passed in the `columns` attribute array.
9563d8a01a40e508f7697d9c674c164512940371Luke Smith<div id="column-config-table" class="yui3-skin-sam">
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <th scope="col">Configuration</th>
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <th scope="col">Description</th>
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <th scope="col">Module</th>
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>key</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith { key: 'username' }
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith Binds the column values to the named property in the `data`.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith Optional if `formatter`, `nodeFormatter`, or `cellTemplate`
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith is used to populate the content.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith <p>It should not be set if `children` is set.</p>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith The value is used for the `_id` property unless the `name`
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith property is also set.
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>`datatable-base`</td>
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>name</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith { name: 'fullname', formatter: ... }
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith Use this to assign a name to pass to `table.getColumn(NAME)`
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith or style columns with class "yui3-datatable-col-NAME" if a
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith column isn't assigned a `key`.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith The value is used for the `_id` property.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith <td>`datatable-base`</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith <td>field</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith { field: 'fullname', formatter: ... }
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith <p>An alias for `name` for backward compatibility.</p>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith <td>`datatable-base`</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith name: 'checkAll',
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith id: 'check-all',
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith formatter: ...
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith Overrides the default unique id assigned `<th id="HERE">`.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith <em>Use this with caution</em>, since it can result in
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith duplicate ids in the DOM.
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>`datatable-base`</td>
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>label</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith { key: 'MfgPrtNum', label: 'Part Number' }
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith <p>HTML to populate the header `<th>` for the column.</p>
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>`datatable-base`</td>
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>children</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith Used to create stacked headers.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith <a href="#nested">See the example above</a>.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith Child columns may also contain `children`. There is no limit
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith to the depth of nesting.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith Columns configured with `children` are for display only and
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith <strong>should not</strong> be configured with a `key`.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith Configurations relating to the display of data, such as
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith `formatter`, `nodeFormatter`, `emptyCellValue`, etc. are
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>`datatable-base`</td>
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>abbr</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith key : 'forecast',
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith label: '1yr Target Forecast',
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith abbr : 'Forecast'
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith <p>Assigns the value `<th abbr="HERE">`.</p>
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>`datatable-base`</td>
05d797ae3a8a2995f99fe108f20b1630e3a2d423Luke Smith <td>headerTemplate</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith headerTemplate:
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith '<th id="{id}" ' +
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith 'title="Unread" ' +
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith 'class="{className}" ' +
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith '{_id}>●</th>'
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith Overrides the default
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith <a href="{{apiDocs}}/classes/DataTable.HeaderView.html#property_CELL_TEMPLATE">CELL_TEMPLATE</a>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith used by `Y.DataTable.HeaderView` to render the header cell
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith for this column. This is necessary when more control is
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith needed over the markup for the header itself, rather than
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith its content.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith Use the `label` configuration if you don't need to
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith customize the `<th>` iteself.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith Implementers are strongly encouraged to preserve at least
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith the `{id}` and `{_id}` placeholders in the custom value.
05d797ae3a8a2995f99fe108f20b1630e3a2d423Luke Smith <td>`datatable-base`</td>
05d797ae3a8a2995f99fe108f20b1630e3a2d423Luke Smith <td>cellTemplate</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith cellTemplate:
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith '<td class="{className}">' +
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith '<input type="checkbox" ' +
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith 'id="{content}">' +
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith Overrides the default
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith <a href="{{apiDocs}}/classes/DataTable.BodyView.html#property_CELL_TEMPLATE">CELL_TEMPLATE</a>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith used by `Y.DataTable.BodyView` to render the data cells
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith for this column. This is necessary when more control is
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith needed over the markup for the `<td>` itself, rather than
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith its content.
05d797ae3a8a2995f99fe108f20b1630e3a2d423Luke Smith <td>`datatable-base`</td>
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>formatter</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith Used to customize the content of the data cells for this
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith <a href="#formatters">See the example above</a>
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>`datatable-base`</td>
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>nodeFormatter</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith Used to customize the content of the data cells for this
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith <a href="#formatters">See the example above</a>
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>`datatable-base`</td>
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>emptyCellValue</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith key: 'price',
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith emptyCellValue: '???'
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith Provides the default value to populate the cell if the data
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith for that cell is `undefined`, `null`, or an empty string.
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>`datatable-base`</td>
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>allowHTML</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith key: 'preview',
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith allowHTML: true
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith Skips the security step of HTML escaping the value for cells
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith in this column. This is also necessary if `emptyCellValue`
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith is set with an HTML string.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith `nodeFormatter`s ignore this configuration. If using a
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith `nodeFormatter`, it is recommended to use
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith <a href="{{apiDocs}}/classes/Escape.html#method_html">Y.Escape.html()</a>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith on any user supplied content that is to be displayed.
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>`datatable-base`</td>
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>className</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith key: 'symbol',
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith className: 'no-hide'
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith A string of CSS classes that will be added to the `<td>`'s
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith `class` attribute.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith Note, all cells will automatically have a class in the
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith form of "yui3-datatable-col-KEY" added to the `<td>`, where
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith KEY is the column's configured `name`, `key`, or `id` (in
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith that order of preference).
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>`datatable-base`</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith <td>width</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith { key: 'a', width: '400px' },
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith { key: 'b', width: '10em' }
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith Adds a style `width` setting to an associated `<col>`
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith element for the column.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith Note, the assigned width will not truncate cell content, and
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith it will not preserve the configured width if doing so would
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith compromise either the instance's `width` configuration or
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith the natural width of the table's containing DOM elements.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith If absolute widths are required, it can be accomplished with
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith some custom CSS and the use of a `cellTemplate`, or
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith `formatter`. See
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith <a href="{{apiDocs}}/modules/datatable-column-widths.html">the
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith description of `datatable-column-widths`</a> for an example
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith of how to do this.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith <td>`datatable-column-widths`</td>
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>sortable</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith { key: 'lastLogin', sortable: true }
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith Used when the instance's `sortable` attribute is set to
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith "auto" (the default) to determine which columns will support
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith user sorting by clicking on the header.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith If the instance's `sortable` attribute is set, this
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith configuration is ignored.
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>`datatable-sort`</td>
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>sortFn</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith label: 'Name',
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith sortFn: function (a, b, desc) {
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith order = (an > bn) ? 1 : -(an < bn);
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith return desc ? -order : order;
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith formatter: function (o) {
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith Allows a column to be sorted using a custom algorithm. The
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith function receives three parameters, the first two being the
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith two record Models to compare, and the third being a boolean
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith `true` if the sort order should be descending.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith The function should return `-1` to sort `a` above `b`, `-1`
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith to sort `a` below `b`, and `0` if they are equal. Keep in
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith mind that the order should be reversed when `desc` is
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith The `desc` parameter is provided to allow `sortFn`s to
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith always sort certain values above or below others, such as
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith always sorting `null`s on top.
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>`datatable-sort`</td>
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>sortDir</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith (<strong>read-only</strong>) If a column is sorted, this
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith will be set to `1` for ascending order or `-1` for
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith descending. This configuration is public for inspection,
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith but can't be used during DataTable instantiation to set the
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith sort direction of the column. Use the table's
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith <a href="{{apiDocs}}/classes/DataTable.html#attr_sortBy">sortBy</a>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith attribute for that.
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>`datatable-sort`</td>
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>_yuid</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith (<strong>read-only</strong>) The unique identifier assigned
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith to each column. This is used for the `id` if not set, and
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith the `_id` if none of `name`, 'field`, `key`, or `id` are
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>`datatable-base`</td>
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>_id</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith (<strong>read-only</strong>) A unique-to-this-instance name
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith used extensively in the rendering process. It is also used
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith to create the column's classname, as the input name
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith `table.getColumn(HERE)`, and in the column header's
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith `<th data-yui3-col-id="HERE">`.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith The value is populated by the first of `name`, `field`,
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith `key`, `id`, or `_yuid` to have a value. If that value
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith has already been used (such as when multiple columns have
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith the same `key`), an incrementer is added to the end. For
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith example, two columns with `key: "id"` will have `_id`s of
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith "id" and "id2". `table.getColumn("id")` will return the
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith first column, and `table.getColumn("id2")` will return the
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>`datatable-base`</td>
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>_colspan</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith (<strong>read-only</strong>) Used by
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith `Y.DataTable.HeaderView` when building stacked column
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>`datatable-base`</td>
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>_rowspan</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith (<strong>read-only</strong>) Used by
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith `Y.DataTable.HeaderView` when building stacked column
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>`datatable-base`</td>
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>_parent</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith (<strong>read-only</strong>) Assigned to all columns in a
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith column's `children` collection. References the parent
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith column object.
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>`datatable-base`</td>
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>_headers</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith (<strong>read-only</strong>) Array of the `id`s of the
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith column and all parent columns. Used by
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith `Y.DataTable.BodyView` to populate `<td headers="THIS">`
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith when a cell references more than one header.
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <td>`datatable-base`</td>
9563d8a01a40e508f7697d9c674c164512940371Luke Smith<h2 id="formatter-props">Appendix B: Formatter Argument Properties</h2>
9563d8a01a40e508f7697d9c674c164512940371Luke Smith The properties below are found on the object passed to `formatter`
9563d8a01a40e508f7697d9c674c164512940371Luke Smith functions defined in a column configuration. See
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <a href="#nodeformatter-props">Appendix C</a> for the object properties
9563d8a01a40e508f7697d9c674c164512940371Luke Smith passed to `nodeFormatter`s.
9563d8a01a40e508f7697d9c674c164512940371Luke Smith<div id="formatter-props-table" class="yui3-skin-sam">
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <th scope="col">Property</th>
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <th scope="col">Description</th>
05d797ae3a8a2995f99fe108f20b1630e3a2d423Luke Smith <td>`value`</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith formatter: function (o) {
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith // assumes a numeric value for this column
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith return '$' + o.value.toFixed(2);
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith The raw value from the record Model to populate this cell.
05d797ae3a8a2995f99fe108f20b1630e3a2d423Luke Smith <td>`data`</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith formatter: function (o) {
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith The Model data for this row in simple object format.
05d797ae3a8a2995f99fe108f20b1630e3a2d423Luke Smith <td>`record`</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith formatter: function (o) {
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith return '<a href="/service/' + o.record.get('id') + '"> +
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith The Model for this row.
05d797ae3a8a2995f99fe108f20b1630e3a2d423Luke Smith <td>`column`</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith formatter: function (o) {
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith // Use a custom column property
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith var format = o.column.dateFormat || '%D';
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith The column configuration object.
05d797ae3a8a2995f99fe108f20b1630e3a2d423Luke Smith <td>`className`</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith formatter: function (o) {
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith A string of class names to add `<td class="HERE">` in
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith addition to the column class and any classes in the
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith column's `className` configuration.
05d797ae3a8a2995f99fe108f20b1630e3a2d423Luke Smith <td>`rowIndex`</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith formatter: function (o) {
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith The index of the current Model in the ModelList.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith <em>Typically</em> correlates to the row index as well.
05d797ae3a8a2995f99fe108f20b1630e3a2d423Luke Smith <td>`rowClass`</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith formatter: function (o) {
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith A string of css classes to add `<tr class="HERE"><td...`.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith This is useful to avoid the need for `nodeFormatter`s to add
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith classes to the containing row.
9563d8a01a40e508f7697d9c674c164512940371Luke Smith<h2 id="nodeformatter-props">Appendix C: nodeFormatter Argument Properties</h2>
9563d8a01a40e508f7697d9c674c164512940371Luke Smith The properties below are found on the object passed to `nodeFormatter`
9563d8a01a40e508f7697d9c674c164512940371Luke Smith functions defined in a column configuration. See
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <a href="#formatter-props">Appendix B</a> for the object properties
9563d8a01a40e508f7697d9c674c164512940371Luke Smith passed to `formatter`s.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith// Reference nodeFormatter
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke SmithnodeFormatter: function (o) {
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith o.td.setAttribute('data-term-id', this.record.get('id'));
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith '<tr><td colspan"3">' +
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith '<button class="term">terminate</button>' +
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith '</td></tr>',
9563d8a01a40e508f7697d9c674c164512940371Luke Smith<div id="nodeformatter-props-table" class="yui3-skin-sam">
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <th scope="col">Property</th>
9563d8a01a40e508f7697d9c674c164512940371Luke Smith <th scope="col">Description</th>
05d797ae3a8a2995f99fe108f20b1630e3a2d423Luke Smith <td>`td`</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith <td>The `<td>` Node for this cell.</td>
05d797ae3a8a2995f99fe108f20b1630e3a2d423Luke Smith <td>`cell`</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith If the cell `<td>` contains an element with class
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith "yui3-datatable-liner", this will refer to that Node.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith Otherwise, it is equivalent to `o.td` (default behavior).
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith By default, liner elements aren't rendered into cells, but
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith to implement absolute column widths, some cell liner
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith element with `width` and `overflow` style is required
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith (barring a table style of `table-layout: fixed`). This may
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith be applied to the columns `cellTemplate` configuration or
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith to the `bodyView` instance's `CELL_TEMPLATE` for all
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith Generally, the liner, if present, corresponds to where the
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith content should go, so use `o.cell` to add content and
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith `o.td` to specifically work with the `<td>` Node.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith <td>`value`</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith The raw value from the record Model to populate this cell.
05d797ae3a8a2995f99fe108f20b1630e3a2d423Luke Smith <td>`data`</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith <td>The Model data for this row in simple object format.</td>
05d797ae3a8a2995f99fe108f20b1630e3a2d423Luke Smith <td>`record`</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith <td>The Model for this row.</td>
05d797ae3a8a2995f99fe108f20b1630e3a2d423Luke Smith <td>`column`</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith <td>The column configuration object.</td>
05d797ae3a8a2995f99fe108f20b1630e3a2d423Luke Smith <td>`rowIndex`</td>
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith The index of the current Model in the ModelList.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith <em>Typically</em> correlates to the row index as well.
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke SmithYUI.add('datatable-node', function (Y) {
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith Y.Plugin.DataTable = Y.Base.create('datatable', Y.DataTable, [], {
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith initializer: function (config) {
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith var columns = config.host.all('thead th').get('text'),
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith config.host.all('tbody td').each(function (node, i) {
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith var record = (i % count) ?
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith record[columns[i % count]] = node.getContent();
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith for (i = columns.length - 1; i >= 0; --i) {
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith columns[i] = { key: columns[i], allowHTML: true }
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith columns : columns,
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith setter: function (val) {
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith if (val === true) {
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith}, '0.1', { requires: ['datatable-base', 'node-pluginhost'] });
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke SmithYUI({ filter: 'raw' }).use('datatable-node', 'datatable-sort', function (Y) {
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith Y.one('#column-config-table table').set('datatable', {
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith sortable: ['Configuration', 'Module']
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith Y.one('#formatter-props-table table').set('datatable', true);
5f99c9b24c89427b620c7379c7e2febe9ad5491fLuke Smith Y.one('#nodeformatter-props-table table').set('datatable', true);