3.5.0+ Migration Guide

DataTable and supporting modules were rebuilt in version 3.5.0. The new architecture is not fully backward compatible with versions 3.4.1 and prior. This guide is to help answer questions that may come up when upgrading to the latest version.

This guide focuses on 3.4.1 API compatibility. It does not describe new features added in 3.5.0 (there were a lot). Refer to the updated DataTable user guide for that.

If you are unable to upgrade due to unresolvable issues, you can use the datatable-deprecated module suite, which is equivalent to the 3.4.1 implementation. But be aware that these modules will be removed in a future version of YUI.

Overview of API changes from 3.4.1

The architectural change resulted in the deprecation, replacement, or removal of nearly all attributes and properties from the version 3.4.1 implementation. Here is a quick list of the changes most likely to affect your upgrade:

new Y.DataTable.Base(...) → new Y.DataTable({ ... })

new Y.DataTable.Base({
    columnset: [ ... ],
    recordset: [ ... ]
});

→

new Y.DataTable({
    columns: [ ... ],
    data   : [ ... ]
});

(cells rendered as HTML by default) → columns: [ { key: 'email', allowHTML: true }, ... ]
table.plug(Y.Plugin.DataTableSort) → (plugin not needed) See below or read the user guide
table.plug(Y.Plugin.DataTableScroll, ...) → (plugin not needed) See below or read the user guide
columnset: [ { formatter: function (o) { ... } } ] → (formatter changes) See below or read the user guide
record.getValue(fieldName) → record.get(fieldName)

Instantiation and Instance Configuration Changes

As of 3.5.0, Y.DataTable is no longer just a namespace, but is now the preferred constructor for DataTable instances.

var table = new Y.DataTable({
    // Column configuration looks much the same except the attribute name
    columns: [
        { key: 'name', label: 'Name', sortable: true, width: '200px' },
        {
            key: 'birthdate',
            label: 'Age',
            sortable: true,
            formatter: function (o) {
                var now = new Date(),
                    years = now.getYear() - o.value.getYear();

                now.setYear(o.value.getYear());

                return years - (o.value < now);
            }
        }
    ],
    // Passing in row data looks much the same except the attribute name
    data: [
        { 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');

The Y.DataTable.Base class still exists, but is useful primarily as a superclass for extension. The attributes of Y.DataTable.Base are the same as those of Y.DataTable, less any attributes added by class extensions (see below).

Configuration attributes that have changed from 3.4.1 are:

Attribute	Change
`columnset`	Deprecated. Use `columns`. `columnset` will behave as an alias for `columns` for a short time, but will be removed in future versions. See below.
`recordset`	Deprecated. Use `data`. `recordset` will behave as an alias for `data` for a short time, but will be removed in future versions. See below.
`tdValueTemplate`	Removed. Use column `formatter`, `cellTemplate`, or override the `Y.DataTable.BodyView` instance's `CELL_TEMPLATE`.
`thValueTemplate`	Removed. Use column `label`, `headerTemplate`, or override the `Y.DataTable.HeaderView` instance's `CELL_TEMPLATE`.
`trTemplate`	Removed. Use column `nodeFormatter` or override the `Y.DataTable.BodyView` instance's `ROW_TEMPLATE`.

Table and Cell Formatting Changes

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.classnames in the formatter parameter is now o.className.
o.column in the formatter parameter is now the plain JavaScript object containing the column configurations rather than a Y.Column instance.
o.record in the formatter parameter is now a Model instance instead of a Y.Record instance.
this.createCell(o), o.td, o.tr, and o.tbody no longer exist on the parameter passed to formatter functions. Use nodeFormatters.
o.headers is now at o.column._headers, but is read-only for 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.

3.4.1

var table = new Y.DataTable.Base({
    columnset: [
        { key: "id",
          emptyCellValue: "<em>new</em>" },
        { key: "name" },
        { key: "price", formatter: "${value}" },
        { key: "price",
          formatter: function (o) {
            if (o.value > 4) {
                o.classnames += "spendy";
            }
            return '$' + o.value.toFixed(2);
          }
        },
        { key: "price",
          formatter: function (o) {
            var cell = this.createCell(o);

            if (o.value > 4) {
                cell.addClass('spendy');
            }

            cell.setHTML('$' + o.value);
          }
        }
    ],
    data: [
        { id: 1, name: "Bread", price: 3.45 },
        { id: 2, name: "Milk",  price: 4.99 },
        { id: 3, name: "Eggs",  price: 2.75 }
    ]
}).render("#over-there");

3.5.0

var table = new Y.DataTable({
    columns: [
        { key: "id",
          emptyCellValue: "<em>new</em>",
          allowHTML: true },
        { key: "name" },
        { key: "price", formatter: "${value}" },
        { key: "price",
          formatter: function (o) {
            if (o.value > 4) {
                o.className += "spendy";
            }
            return '$' + o.value.toFixed(2);
          }
        },
        { key: "price",
          nodeFormatter: function (o) {
            if (o.value > 4) {
                o.cell.addClass('spendy');
            }

            o.cell.setHTML('$' + o.value);

            return false;
          }
        }
    ],
    data: [
        { 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 Formatting Cell Data section in the DataTable user guide for more details.

Column Configuration Changes

As of 3.5.0, the Y.Columnset and Y.Column classes have been deprecated. The DataTable configuration attribute columnset has been deprecated in favor of the columns attribute. The columnset attribute has been retained for partial backward compatibility. Columns are now stored as an array of simple JavaScript objects rather than class instances.

var table = new Y.DataTable({
    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 Column configuration section in the user guide for more details.

Row Data Configuration Changes

As of 3.5.0, DataTable uses Y.Model and Y.ModelList to store row data. Y.Recordset and Y.Record haven't been deprecated, but may be in the future. The recordset attribute has been retained for partial backward compatibility. The data ModelList can be assigned to, but retrieving the value of the attribute will return the ModelList, not a Y.Recordset instance.

var table = new Y.DataTable({
    columnset: [ ... ],
    recordset: [
        { 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.

3.4.1

// Y.Record
var record = oldTable.get('recordset').item(0);

record.getValue('birthdate'); // => Date(1940, 1, 6)
record.get('data').birthdate; // => same

3.5.0

// Y.Model
var model = newTable.getRecord(0);

model.get('birthdate'); // => Date(1940, 1, 6)

This change breaks column/record keys that contain periods. Attribute treats periods as subproperty indicators, so periods are no longer allowed; use an alternate character. In the case of remote data that is parsed by Y.Plugin.DataSourceJSONSchema, use the locator configuration for fields to extract subproperty values. A benefit to doing this is that you may not need to specify a column label.

3.4.1

var table = new Y.DataTable.Base({
    columnset: [
        { key: "id" },
        { key: "Product.Name",  label: "Product" },
        { key: "Product.Price", label: "Price" }
    ],
    caption: "Price List"
}).plug(Y.Plugin.DataTableDataSource, {
    datasource: new Y.DataSource.IO({
        source: "/service/price-list"
    }).plug(Y.Plugin.DataSourceJSONSchema, {
        schema: {
            resultListLocator: "items",
            resultFields: [
                { key: "id" },
                { key: "Product.Name" },
                { key: "Product.Price" }
            ]
        }
    })
});

table.datasource.load(...);

3.5.0

var table = new Y.DataTable({
    columns: [ "id", "Product", "Price" ],
    caption: "Price List"
}).plug(Y.Plugin.DataTableDataSource, {
    datasource: new Y.DataSource.IO({
        source: "/service/price-list"
    }).plug(Y.Plugin.DataSourceJSONSchema, {
        schema: {
            resultListLocator: "items",
            resultFields: [
                { key: "id" },
                { key: "Product",
                  locator: "Product.Name" },
                { key: "Price",
                  locator: "Product.Price" }
            ]
        }
    })
});

table.datasource.load(...);

If you are using any Recordset plugins, your code will need to be modified. Some loss of functionality may result.

Y.Plugin.RecordsetSort: This plugin was formerly applied by the Y.Plugin.DataTableSort plugin to the DataTable's Recordset instance. Sorting is now enabled through a class extension.
Y.Plugin.RecordsetFilter: 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.
Y.Plugin.RecordsetIndexer: 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 the Model user guide for more information on customizing the primary index. If multiple custom indexes are required, DataTable supports the use of custom Model subclasses to store the record data.

3.5.0+ Migration Guide

Overview of API changes from 3.4.1

Instantiation and Instance Configuration Changes

Table and Cell Formatting Changes

3.4.1

3.5.0

Column Configuration Changes

Row Data Configuration Changes

3.4.1

3.5.0

3.4.1

3.5.0

Feature Configuration Changes

Column Sorting Changes

3.4.1

3.5.0

Scrollable Table Changes

3.4.1

3.5.0

Markup and CSS Changes

3.4.1

3.5.0

What Did I Miss?

Table of Contents

Examples

Examples That Use This Component