index.mustache revision 1f0b5989221c9f985c461d18e10067e38d55c470
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
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');
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
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
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith<h4 id="multisort">Multi-Column Sorting</h4>
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smithshift-click, or by API
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith<h4 id="multisort">Sorting APIs</h4>
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smithsort, toggleSort, sortBy
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smith Disable header-click sorting by setting `sortable` to `false`.
1f0b5989221c9f985c461d18e10067e38d55c470Luke Smithnote sort event, point to events section.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h3 id="scrolling">Scrolling</h3>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <strong>Note:</strong> Scrolling is not currently supported on the Android
5992781dfab2b64f79fee03abd15d9a91e2f5b77Luke Smith WebKit browser.
9563d8a01a40e508f7697d9c674c164512940371Luke Smith Scrolling functionality can be added with the `datatable-scroll` module
9563d8a01a40e508f7697d9c674c164512940371Luke Smith (included in the `datatable` rollup module). Scrolling is enabled by the
9563d8a01a40e508f7697d9c674c164512940371Luke Smith `scrollable` attribute, which accepts values "x", "y", "xy", `true` (same
9563d8a01a40e508f7697d9c674c164512940371Luke Smith 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.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { key: "Company" },
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { key: "Phone" },
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { key: "Contact" }
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { Company: "Company Bee", Phone: "415-555-1234", Contact: "Sally Spencer"},
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { Company: "Acme Company", Phone: "650-555-4444", Contact: "John Jones"},
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { Company: "Indutrial Industries", Phone: "408-555-5678", Contact: "Robin Smith"}
9563d8a01a40e508f7697d9c674c164512940371Luke Smithvar table = new Y.DataTable({
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith columns: cols,
9563d8a01a40e508f7697d9c674c164512940371Luke Smith scrollable: "y",
9563d8a01a40e508f7697d9c674c164512940371Luke Smith height: "300px"
9563d8a01a40e508f7697d9c674c164512940371Luke Smith}).render("#scroll");
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);