A Widget for displaying tabular data. The base implementation of DataTable provides the ability to dynamically generate an HTML table from a set of column configurations and row data.

Two classes are included in the datatable-base module:

1. Y.DataTable - Main instantiable class, has all loaded features available
2. Y.DataTable.Base - Featureless version for use primarily as a superclass.

Example usage might look like this:

// Featureless table, usually used as a subclass, but can be instantiated
var table = new Y.DataTable.Base({
    columns: ['firstName', 'lastName', 'age'],
    data: [
        { firstName: 'Frank', lastName: 'Zappa', age: 71 },
        { firstName: 'Frank', lastName: 'Lloyd Wright', age: 144 },
        { firstName: 'Albert', lastName: 'Einstein', age: 132 },
        ...
    ]
});

table.render('#in-here');

// Table with all loaded features available (not .Base)
// The functionality of this table would require additional modules be use()d,
// but the feature APIs are aggregated onto Y.DataTable.
// (Snippet is for illustration. Not all features are available today.)
var table = new Y.DataTable({
    columns: [
        { type: 'checkbox', defaultChecked: true },
        { key: 'firstName', sortable: true, resizable: true },
        { key: 'lastName', sortable: true },
        { key: 'role', formatter: toRoleName }
    ],
    data: {
        source: 'http://myserver.com/service/json',
        type: 'json',
        schema: {
            resultListLocator: 'results.users',
            fields: [
                'username',
                'firstName',
                'lastName',
                { key: 'role', type: 'number' }
            ]
        }
    },
    recordType: UserModel,
    pagedData: {
        location: 'footer',
        pageSizes: [20, 50, 'all'],
        rowsPerPage: 20,
        pageLinks: 5
    },
    editable: true,
    filterable: true
});

Column Configuration

The column configurations are set in the form of an array of objects, where each object corresponds to a column. For columns populated directly from the row data, a 'key' property is required to bind the column to that property or attribute in the row data.

Not all columns need to relate to row data, nor do all properties or attributes of the row data need to have a corresponding column. However, only those columns included in the columns configuration attribute will be rendered.

Other column configuration properties are supported by the configured headerView, bodyView, footerView classes as well as any features added by plugins or class extensions. See the description of DataTable.HeaderView, DataTable.BodyView, and other DataTable feature classes to see what column properties they support.

Some examples of column configurations would be:

// Basic
var columns = [{ key: 'firstName' }, { key: 'lastName' }, { key: 'age' }];

// For columns without any additional configuration, strings can be used
var columns = ['firstName', 'lastName', 'age'];

// Multi-row column headers (see DataTable.HeaderView for details)
var columns = [
    {
        label: 'Name',
        children: [
            { key: 'firstName' },
            { key: 'lastName' }
        ]
    },
    'age' // mixing and matching objects and strings is ok
];

// Including columns that are not related 1:1 to row data fields/attributes
// (See DataTable.BodyView for details)
var columns = [
    {
        label: 'Name', // Needed for the column header
        formatter: function (o) {
            // Fill the column cells with data from firstName and lastName
            if (o.data.age > 55) {
                o.classnames += ' senior';
            }
            return o.data.lastName + ', ' + o.data.firstName;
        }
    },
    'age'
];

// Columns that include feature configurations (for illustration; not all
// features are available today).
var columns = [
    { type: 'checkbox', defaultChecked: true },
    { key: 'firstName', sortable: true, resizable: true, min-width: '300px' },
    { key: 'lastName', sortable: true, resizable: true, min-width: '300px' },
    { key: 'age', emptyCellValue: 'unknown' }
];

Row Data Configuration

The data configuration attribute is responsible for housing the data objects that will be rendered as rows. You can provide this information in two ways by default:

1. An array of simple objects with key:value pairs
2. A ModelList of Base-based class instances (presumably Model subclass instances)

If an array of objects is passed, it will be translated into a ModelList filled with instances of the class provided to the recordType attribute. This attribute can also create a custom Model subclass from an array of field names or an object of attribute configurations. If no recordType is provided, one will be created for you from available information (see _initRecordType). Providing either your own ModelList instance for data, or at least Model class for recordType, is the best way to control client-server synchronization when modifying data on the client side.

The ModelList instance that manages the table's data is available in the data property on the DataTable instance.

Rendering

Table rendering is a collaborative process between the DataTable and its configured headerView, bodyView, and footerView. The DataTable renders the <table> and <caption>, but the contents of the table are delegated to instances of the classes provided to the headerView, bodyView, and footerView attributes. If any of these attributes is unset, that portion of the table won't be rendered.

DataTable.Base assigns the default headerView to Y.DataTable.HeaderView and the default bodyView to Y.DataTable.BodyView, though either can be overridden for custom rendering. No default footerView is assigned. See those classes for more details about how they operate.