index.mustache revision 5f99c9b24c89427b620c7379c7e2febe9ad5491f
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith<style type="text/css">
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;
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.
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith Under the hood, the DataTable class uses a ModelList instance to manage the
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith row data properties.
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>
9563d8a01a40e508f7697d9c674c164512940371Luke Smith<!-- TODO: describe data as array, data as ModelList instance, assigned and dynamic recordTypes -->
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Integrate with the <a href="../datasource/">DataSource</a> data abstraction
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith utility to easily load data from remote sources and implement features such
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith as caching and polling.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithvar myDataSource = new Y.DataSource.Get({
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith source: "http://query.yahooapis.com/v1/public/yql?&format=json&env=store%3A%2F%2Fdatatables.org%2Falltableswithkeys"
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke SmithmyDataSource.plug(Y.Plugin.DataSourceJSONSchema, {
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith resultListLocator: "query.results.Result",
9563d8a01a40e508f7697d9c674c164512940371Luke Smith resultFields: [
9563d8a01a40e508f7697d9c674c164512940371Luke Smith key: "Rating",
9563d8a01a40e508f7697d9c674c164512940371Luke Smithvar table = new Y.DataTable({
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith columns: cols,
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith summary: "Pizza places near 98089"
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith datasource: myDataSource
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith// Load the data into the table
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith request: "&q=select%20*%20from%20local.search%20where%20zip%3D%2794089%27%20and%20query%3D%27pizza%27"
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith// Make another request later
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith request: "&q=select%20*%20from%20local.search%20where%20zip%3D%2794089%27%20and%20query%3D%27chinese%27"
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Enable DataSource caching.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { key: "Rating.AverageRating", label: "Rating" }
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithvar myDataSource = new Y.DataSource.Get({
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith source: "http://query.yahooapis.com/v1/public/yql?format=json&env=store%3A%2F%2Fdatatables.org%2Falltableswithkeys"
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith resultListLocator: "query.results.Result",
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith resultFields: ["Title", "Phone", "Rating.AverageRating"]
9563d8a01a40e508f7697d9c674c164512940371Luke Smithvar table = new Y.DataTable({
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith columns: cols,
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith summary: "Pizza places near 98089",
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith caption: "Table with JSON data from YQL"
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith datasource: myDataSource
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith .render("#pizza");
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith request: "&q=select%20*%20from%20local.search%20where%20zip%3D%2794089%27%20and%20query%3D%27chinese%27"
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Enable DataSource polling.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithvar cols = ["Title", "Phone", "Rating"];
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithvar myDataSource = new Y.DataSource.IO({
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith resultListLocator: "Result",
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith resultFields: [
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { key: "Title", locator: "*[local-name() ='Title']" },
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { key: "Phone", locator: "*[local-name() ='Phone']" },
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { key: "Rating", locator: "*[local-name()='Rating']/*[local-name()='AverageRating']" }
9563d8a01a40e508f7697d9c674c164512940371Luke Smithvar table = new Y.DataTable({
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith columns: cols,
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith summary: "Chinese restaurants near 98089",
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith caption: "Table with XML data from same-domain script"
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith datasource: myDataSource,
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith initialRequest: "zip=94089&query=chinese"
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith .render("#chinese");
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith request: "zip=94089&query=chinese",
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith success: Y.bind(table.datasource.onDataReturnInitializeTable, table.datasource),
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith failure: Y.bind(table.datasource.onDataReturnInitializeTable, table.datasource)
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h3 id="sorting">Column sorting</h3>
9563d8a01a40e508f7697d9c674c164512940371Luke Smith Column sorting functionality can be added with the `datatable-sort` module
9563d8a01a40e508f7697d9c674c164512940371Luke Smith (included in the `datatable` rollup module).
9563d8a01a40e508f7697d9c674c164512940371Luke Smith Enable sorting for all columns by setting `sortable` to true during
9563d8a01a40e508f7697d9c674c164512940371Luke Smith instantiation. Alternately, pass `sortable` an array of column keys to
9563d8a01a40e508f7697d9c674c164512940371Luke Smith enable sortability of those specific columns, `false` to disable sorting,
9563d8a01a40e508f7697d9c674c164512940371Luke Smith or the string "auto" (the default) to determine which columns to make
9563d8a01a40e508f7697d9c674c164512940371Luke Smith sortable by reading the `sortable` property from the column configurations.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { key: "Company", sortable: true },
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { key: "Phone" },
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { key: "Contact", sortable: true }
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 Smith// Alternately, include sortable: true or sortable: ["Company", "Contact"]
9563d8a01a40e508f7697d9c674c164512940371Luke Smith// in the DataTable configuration
9563d8a01a40e508f7697d9c674c164512940371Luke Smithvar table = new Y.DataTable({
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith columns: cols,
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith summary: "Contacts list",
9563d8a01a40e508f7697d9c674c164512940371Luke Smith caption: "Table with simple column sorting"
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith}).render("#sort");
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);