0N/A white-space: nowrap;
0N/A background: #fcfbfa;
0N/A border: 1px solid #d0d5ec;
0N/A border-color: #efeeed;
0N/A.yui3-skin-sam table {
0N/A.demo { width: 40%; }
0N/A.details { width: 60%; }
0N/A.before, .after { width: 47%; }
0N/A#quickref code strong {
0N/A DataTable and supporting modules were rebuilt in version 3.5.0. The
0N/A new architecture is <strong>not fully backward compatible</strong> with
0N/A versions 3.4.1 and prior. This guide is to help answer questions that
0N/A may come up when upgrading to the lastest version.
0N/A This guide focuses on 3.4.1 API compatibility. It <strong>does not
0N/A describe new features added in 3.5.0</strong> (there were a lot).
0N/A Refer to the updated <a href="
index.html">DataTable user guide</a> for
0N/A If you are unable to upgrade due to unresolvable issues, you can use the
0N/A module suite, which is equivalent to the 3.4.1 implementation. But be
0N/A aware that these modules will be removed in a future version of YUI.
0N/A<h2 id="overview">Overview of API changes from 3.4.1</h2>
0N/A The architectural change resulted in the deprecation, replacement, or
0N/A removal of nearly all attributes and properties from the version 3.4.1
0N/A implementation. Here is a quick list of the changes most likely to affect
0N/A <div class="yui3-g">
0N/A <div class="yui3-u">
0N/A <p class="yui3-u" style="line-height: 72px; margin: 0 1em;">→</p>
0N/A <div class="yui3-u">
(cells rendered as HTML by default) →
<code>columns: [ { key: 'email', <strong>allowHTML: true</strong> }, ... ]</code>
<a href="#features">See below</a> or read
<em>(plugin not needed)</em>
<a href="#features">See below</a> or read
<code>columnset: [ { <em>formatter: function (o) { ... }</em> } ]</code>
<a href="#formatters">See below</a> or read
<code>record.<em>getValue(fieldName)</em></code> →
<code>record.<strong>get(fieldName)</strong></code>
<h2 id="instantiation">Instantiation and Instance Configuration Changes</h2>
As of 3.5.0, `
Y.DataTable` is no longer just a namespace, but is now the
preferred constructor for DataTable instances.
// Column configuration looks much the same except the attribute name
{ key: 'name', label: 'Name', sortable: true, width: '200px' },
formatter: function (o) {
// Passing in row data looks much the same except the attribute name
{ name: 'Tom Brokaw', birthdate: new Date(1940, 1, 6) },
{ name: 'Peter Jennings', birthdate: new Date(1938, 6, 29) },
{ name: 'Katie Couric', birthdate: new Date(1957, 1, 7) },
{ name: 'Brian Williams', birthdate: new Date(1958, 4, 5) },
{ name: 'Matt Lauer', birthdate: new Date(1957, 11, 30) }
}).render('#over-there');
same as those of `
Y.DataTable`, less any attributes added by class
extensions (<a href="#features">see below</a>).
Configuration attributes that have changed from 3.4.1 are:
<strong>Deprecated</strong>. Use `columns`. `columnset` will
behave as an alias for `columns` for a short time, but will be
removed in future versions. <a href="#columns">See below</a>.
<strong>Deprecated</strong>. Use `data`. `recordset` will
behave as an alias for `data` for a short time, but will be
removed in future versions. <a href="#data">See below</a>.
<td>`tdValueTemplate`</td>
<strong>Removed</strong>. Use column `formatter`, `cellTemplate`,
<td>`thValueTemplate`</td>
<strong>Removed</strong>. Use column `label`, `headerTemplate`,
<strong>Removed</strong>. Use column `nodeFormatter` or override
<h2 id="formatters">Table and Cell Formatting Changes</h2>
The following changes apply to table and column cell formatting:
If cell values include HTML, add `allowHTML: true` to the column
configuration. HTML is escaped by default for security.
`
o.column` in the formatter parameter is now <a href="#columns">the
plain JavaScript object</a> containing the column configurations rather
`
o.record` in the formatter parameter is now <a href="#data">a Model
instance</a> instead of a `
Y.Record` instance.
the parameter passed to `formatter` functions. Use
<a href="
index.html#nodeformatter">`nodeFormatter`</a>s.
`formatter` functions. If you need to change the cell's headers
attribute, add a {placeholder} for them to a custom `cellTemplate` for
the column, or use a `nodeFormatter`.
The table's `tdValueTemplate`, `thValueTemplate`, and `trTemplate` no
longer exist, nor do the DataTable instance properties `tdTemplate` and
`thTemplate`. Use `formatter` strings or functions to customize the
content of data cells in a column and `label` strings to customize the
content of header cells. To modify the `<td>` or `<th>` entirely, set
the column configuration `cellTemplate` or `headerTemplate`.
<div class="yui3-u before">
<h4 class="no-toc">3.4.1</h4>
emptyCellValue: "<em>new</em>" },
{ key: "price", formatter: "${value}" },
formatter: function (o) {
formatter: function (o) {
{ id: 1, name: "Bread", price: 3.45 },
{ id: 2, name: "Milk", price: 4.99 },
{ id: 3, name: "Eggs", price: 2.75 }
}).render("#over-there");
<div class="yui3-u after">
<h4 class="no-toc">3.5.0</h4>
emptyCellValue: "<em>new</em>",
{ key: "price", formatter: "${value}" },
formatter: function (o) {
nodeFormatter: function (o) {
{ id: 1, name: "Bread", price: 3.45 },
{ id: 2, name: "Milk", price: 4.99 },
{ id: 3, name: "Eggs", price: 2.75 }
}).render("#over-there");
Read the <a href="
index.html#formatters">Formatting Cell Data</a> section in
the DataTable user guide for more details.
<h2 id="columns">Column Configuration Changes</h2>
The DataTable configuration attribute `columnset` has been deprecated in
favor of the `columns` attribute. The `columnset` attribute has been
retained for <em>partial</em> backward compatibility. Columns are now
stored as an array of simple JavaScript objects rather than class instances.
columnset: [ 'name', 'age' ],
// columnset passes through to columns
var columns =
table.get('columns'); // => Array, not Columnset instance
table.set('columnset', [ ... (new column configurations) ... ]);
// backward compatibility stops here
var columnset =
table.get('columnset'); // => Array, not Columnset instance
Strings passed into the column configuration will become objects with those
strings as the value of the `key` property.
See the <a href="
index.html#columns">Column configuration</a> section in
the user guide for more details.
<h2 id="data">Row Data Configuration Changes</h2>
future. The `recordset` attribute has been retained for <em>partial</em>
backward compatibility. The `data` ModelList can be assigned to, but
retrieving the value of the attribute will return the ModelList, <em>not
{ name: 'Tom Brokaw', birthdate: new Date(1940, 1, 6) },
{ name: 'Peter Jennings', birthdate: new Date(1938, 6, 29) },
{ name: 'Katie Couric', birthdate: new Date(1957, 1, 7) },
// recordset passes through to data.
var data =
table.get('data'); // => ModelList instance
table.set('recordset', [ ... (new data records) ... ]);
// backward compatibility stops here
var recordset =
table.get('recordset'); // => ModelList, not Recordset
`
Y.Record` stores all values in a single attribute named `data`, where `
Y.Model` uses individual attributes for each value.
<div class="yui3-u before">
<h4 class="no-toc">3.4.1</h4>
<div class="yui3-u after">
<h4 class="no-toc">3.5.0</h4>
model.get('birthdate'); // => Date(1940, 1, 6)
<strong>This change breaks
column/record keys that contain periods</strong>.
Attribute treats periods as subproperty indicators, so periods are no
longer allowed; use an alternate character. In the case of remote data
configuration for fields to extract subproperty values. A benefit to doing
this is that you may not need to specify a column `label`.
<div class="yui3-u before">
<h4 class="no-toc">3.4.1</h4>
resultListLocator: "items",
<div class="yui3-u after">
<h4 class="no-toc">3.5.0</h4>
columns: [ "id", "Product", "Price" ],
resultListLocator: "items",
If you are using any Recordset plugins, your code will need to be modified.
Some loss of functionality may result.
to the DataTable's Recordset instance. Sorting is now enabled
<a href="#features">through a class extension</a>.
The default ModelList implementation only supports a `filter(function)`
method. If you were relying on this plugin's `grep` or `reject`
methods or the `filter(key, value)` functionality, you will need to
replace that functionality through custom code.
The default ModelList implementation does not support multiple custom
indexes, though it does maintain an index for `id` (or another,
assigned primary key attribute) and `clientId`. See
information on customizing the primary index. If multiple custom
indexes are required, DataTable supports the use of
<a href="#recordtype">custom Model subclasses</a> to store the record
See the <a href="#data">Data Configuration section</a> of the DataTable
user guide for more information.
<h2 id="features">Feature Configuration Changes</h2>
The two optional features available for DataTable in 3.4.1 were sorting and
scrolling. Both features exist in 3.5.0, but are implemented as class
extensions for `
Y.DataTable`. Simply including the `datatable-sort` or
`datatable-scroll` module in your `use(...)` will enable the feature for
YUI().use('datatable-sort', 'datatable-scroll', function (Y) {
// Create a DataTable that is sortable by the "name" column, and is
// configured to scroll vertically within 300px. Because scrollable is
// set to "y", not "x" or "xy", it will not attempt to scroll horizontally.
// Instead the table width will be set to 100%.
columns : [ { key: 'name', sortable: true }, ... ],
<h3 id="sorting">Column Sorting Changes</h3>
Configuring sortable columns may be done as it was in 3.4.1, by setting the
column configuration property `sortable: true`, but may also be done by
setting the DataTable's `sortable` configuration to `true` or an array of
<div class="yui3-u before">
<h4 class="no-toc">3.4.1</h4>
// Assumes use('datatable-sort') or use('datatable')
{ key: "name", sortable: true },
{ key: "price", sortable: true }
{ id: 1, name: "Bread", price: 3.45 },
{ id: 2, name: "Milk", price: 4.99 },
{ id: 3, name: "Eggs", price: 2.75 },
// Sorting API is on the Recordset's plugin
<div class="yui3-u after">
<h4 class="no-toc">3.5.0</h4>
// Assumes use('datatable-sort') or use('datatable')
columns: [ "id", "name", "price" ],
{ id: 1, name: "Bread", price: 3.45 },
{ id: 2, name: "Milk", price: 4.99 },
{ id: 3, name: "Eggs", price: 2.75 },
sortable: [ "name", "price" ]
// Sort method is on the instance
//-------------------------------------------------
//-------------------------------------------------
columns: [ "id", "name", "price" ],
sortable: true // makes all columns sortable
// OR the old way works, too
{ key: "name", sortable: true },
{ key: "price", sortable: true }
Since there is no plugin, the `sort` method is now on the DataTable instance
itself, as are the related attributes. In particular, the `lastSortedBy`
attribute from the plugin implementation has been replaced by the `sortBy`
attribute added by the class extension.
As of 3.5.0, DataTables configured with `sortBy` will have their rows
sorted automatically upon inserting into the table. You do not need to
presort data for the initial render.
<strong>The `trigger` attribute of the sorting plugin was not retained in
the 3.5.0 class extension</strong>. If you require an alternate triggering
event, detach and replace the table's `_sortHandle` property after
var table = new
Y.DataTable({ ... }).render("#over-there");
table._onUITriggerSort, ".yui3-datatable-sortable-column", table);
See the <a href="
index.html#sorting">Column Sorting section</a> of the
user guide for details about the APIs and attributes.
<h3 id="scrolling">Scrollable Table Changes</h3>
Like sorting, the scrolling functionality has been moved to a class
extension, making it unnecessary to plug the DataTable instance with the
<strong>`datatable-scroll` is no longer included in the `datatable`
rollup</strong>, and must be explicitly included in your `use()` statement.
To enable scrolling in 3.5.0, set the table's `scrollable` attribute to "x",
"y", or "xy". The configured `height` and `width` for the DataTable are
used to bound the overall widget dimesions. Scrolling will only be applied
on the axis or axes specified in `scrollable`. However, if `scrollable` is
set to "y", but the `height` isn't set, it will not be made scrollable.
Likewise for "x" and `width`.
<div class="yui3-u before">
<h4 class="no-toc">3.4.1</h4>
// Assumes use("datatable-scroll") or use("datatable")
columnset: ["id", "name", "price"],
{ id: 1, name: "Bread", price: 3.45 },
{ id: 2, name: "Milk", price: 4.99 },
{ id: 3, name: "Eggs", price: 2.75 },
<div class="yui3-u after">
<h4 class="no-toc">3.5.0</h4>
// Assumes use("datatable-scroll")
columns: ["id", "name", "price"],
{ id: 1, name: "Bread", price: 3.45 },
{ id: 2, name: "Milk", price: 4.99 },
{ id: 3, name: "Eggs", price: 2.75 },
}).render("#over-there");
<h2 id="markup">Markup and CSS Changes</h2>
DataTable in 3.5.0 applies more CSS classes to Nodes, stamps fewer nodes
with guid ids, and does not render header and cell liner `<div>`s.
Below are examples of the same table rendered in 3.4.1 and 3.5.0. The 3.5.0
table has comments indicating markup added by feature modules.
<h4 class="no-toc">3.4.1</h4>
<div id="(guid)" class="yui3-widget yui3-datatable">
<div id="(guid)" class="yui3-datatable-content">
Example table with simple columns
<thead class="yui3-datatable-columns">
<tr id="" class="yui3-datatable-first yui3-datatable-last">
<th id="(guid)" rowspan="1" colspan="1" class="yui3-column-id" abbr="">
<div class="yui3-datatable-liner">
<th id="(guid)" rowspan="1" colspan="1" class="yui3-column-name" abbr="">
<div class="yui3-datatable-liner">
<th id="(guid)" rowspan="1" colspan="1" class="yui3-column-price" abbr="">
<div class="yui3-datatable-liner">
<tbody class="yui3-datatable-msg">
<tbody class="yui3-datatable-data" id="(guid)">
<tr id="(guid)" class="yui3-datatable-even">
<td headers="(guid)" class="yui3-column-id">
<div class="yui3-datatable-liner">
<td headers="(guid)" class="yui3-column-name">
<div class="yui3-datatable-liner">
<td headers="(guid)" class="yui3-column-price">
<div class="yui3-datatable-liner">
<tr id="(guid)" class="yui3-datatable-odd">
<td headers="(guid)" class="yui3-column-id">
<div class="yui3-datatable-liner">
<td headers="(guid)" class="yui3-column-name">
<div class="yui3-datatable-liner">
<td headers="(guid)" class="yui3-column-price">
<div class="yui3-datatable-liner">
<tr id="(guid)" class="yui3-datatable-even">
<td headers="(guid)" class="yui3-column-id">
<div class="yui3-datatable-liner">
<td headers="(guid)" class="yui3-column-name">
<div class="yui3-datatable-liner">
<td headers="(guid)" class="yui3-column-price">
<div class="yui3-datatable-liner">
<h4 class="no-toc">3.5.0</h4>
<div id="(guid)" class="yui3-widget yui3-datatable">
<div id="(guid)" class="yui3-datatable-content">
<table cellspacing="0" class="yui3-datatable-table" id="(guid)">
<caption class="yui3-datatable-caption">
<!-- colgroup only renders if datatable-column-widths is use()d.
Note, datatable-column-widths is included in the datatable rollup -->
<thead class="yui3-datatable-columns" id="(guid)">
<th id="(guid)" colspan="1" rowspan="1" class="yui3-datatable-header yui3-datatable-first-header yui3-datatable-col-id" scope="col" data-yui3-col-id="id">
<th id="(guid)" colspan="1" rowspan="1" class="yui3-datatable-header yui3-datatable-col-name" scope="col" data-yui3-col-id="name">
<th id="(guid)" colspan="1" rowspan="1" class="yui3-datatable-header yui3-datatable-col-price" scope="col" data-yui3-col-id="price">
<!-- The message tbody only renders if datatable-message is use()d.
Note, datatable-message is included in the datatable rollup -->
<tbody class="yui3-datatable-message" id="(guid)">
<td class="yui3-datatable-message-content" colspan="3">
<tbody class="yui3-datatable-data">
<tr id="(guid)" data-yui3-record="record_1" class="yui3-datatable-even">
<td class="yui3-datatable-col-id yui3-datatable-cell">
<td class="yui3-datatable-col-name yui3-datatable-cell">
<td class="yui3-datatable-col-price yui3-datatable-cell">
<tr id="(guid)" data-yui3-record="record_2" class="yui3-datatable-odd">
<td class="yui3-datatable-col-id yui3-datatable-cell">
<td class="yui3-datatable-col-name yui3-datatable-cell">
<td class="yui3-datatable-col-price yui3-datatable-cell">
<tr id="(guid)" data-yui3-record="record_3" class="yui3-datatable-even">
<td class="yui3-datatable-col-id yui3-datatable-cell">
<td class="yui3-datatable-col-name yui3-datatable-cell">
<td class="yui3-datatable-col-price yui3-datatable-cell">
<h2 id="help-me">What Did I Miss?</h2>
Obviously, there were a lot of changes to DataTable from 3.4.1 to 3.5.0.
It's entirely likely that I have missed something here. If you experience
trouble with your upgrade and find this migration guide is missing
ticket</a> and I'll update it as soon as possible.
Additional resources to help with the upgrade include the
<a href="/forum">forums</a>, and the #yui IRC channel on
freenode.net.