Upgrade Notes

Overview

Users new to DataTable can skip this section and proceed directly to the Getting Started section. Implementers who are upgrading from previous versions of DataTable should note that the 2.5.1 release of DataTable introduces significant changes to the underlying architecture of the widget, including

• considerable changes to generated markup,
• improvements to performance via a new rendering scheme,
• stabilization of the fixed-header vertical scrolling feature,
• built-in support for horizontal scrolling,
• the introduction of a versatile Paginator class,
• more consistent and robust integration with the DataSource utility,
• bug fixes and code refactoring to make customizations to inline editing and the selection model easier,
• and the introduction of Column show/hide/remove/insert APIs and DragDrop integration with Column reordering.

The following important changes have also been made to the DataSource Utility:

• usage of a callback object literal rather than a callback function and caller reference,
• access to the entire data response after it as been type-converted but before it has been schema-parsed,
• consistency to the oParsedResponse object's members returned by the DataSource to the callback.

Please read the DataSource Upgrade Notes section for further details.

While much care has been taken to support backward compatibility whenever possible, implementers are advised to read through this user guide carefully, and upgrade their implementation code at their earliest convenience.

Markup Changes

The underlying DOM structure of the DataTable has been dramatically revamped in order to better support dynamic column resizing and xy-scrolling, all while maintaining screenreader accessibility. Please refer to the Object Model Overview diagram in the Getting Started section for details on the markup that is generated.

Fixed headers for scrolling tables

The more substantial change is for the creation of fixed headers for xy-scrolling tables. When you enable the scrollable configuration for your DataTable, a separate <table> element is used to display the column headers, allowing the rows of data to be scrolled independently.

Cell liners for dynamic column widths

Each <th> and <td> element now contains a liner <div> to prevent browsers from limiting column widths to the width of the column's widest content.

API changes

As a result of these changes to the generated markup, the following APIs were completely removed:

• CLASS_SCROLLBODY
• CLASS_TABLE
• getTableEl()

The following APIs were added:

• YAHOO.widget.DataTable.CLASS_LINER
• getContainerEl()
• getTheadEl()
• getTbodyEl()
• getThLinerEl()
• getTdLinerEl()

And the following API signatures were changed:

• formatCell(elCell, oRecord, oColumn) - The first argument elCell is now a reference to the <div> liner element rather than the <td> itself.

In an effort to disambiguate DOM elements from JavaScript objects, the following APIs have been renamed:

• headerCellClickEvent - Use theadCellClickEvent.
• headerCellDblclickEvent - Use theadCellDblclickEvent.
• headerCellMousedownEvent - Use theadCellMousedownEvent.
• headerCellMouseoutEvent - Use theadCellMouseoutEvent.
• headerCellMouseoverEvent - Use theadCellMouseoverEvent.
• headerLabelClickEvent - Use theadLabelClickEvent.
• headerLabelDblclickEvent - Use theadLabelDblclickEvent.
• headerLabelMousedownEvent - Use theadLabelMousedownEvent.
• headerLabelMouseoutEvent - Use theadLabelMouseoutEvent.
• headerLabelMouseoverEvent - Use theadLabelMouseoverEvent.
• headerRowClickEvent - Use theadRowClickEvent.
• headerRowDblclickEvent - Use theadRowDblclickEvent.
• headerRowMousedownEvent - Use theadRowMousedownEvent.
• headerRowMouseoutEvent - Use theadRowMouseoutEvent.
• headerRowMouseoverEvent - Use theadRowMouseoverEvent.

New Progressive Rendering Scheme

In order to improve performance, a new rendering scheme has been implemented that can use a timeout queue to draw DOM elements without blocking the browser's UI thread. You can activate progressive rendering of your records via the renderLoopSize configuration.

To account for this change, the following APIs have been deprecated:

• refreshView() - Use render().
• refreshEvent - Use renderEvent.

New Scrolling Architecture

DataTable now supports three types of scrolling:

• x-scrolling: horizontal scrolling where Column headers track with the body
• y-scrolling: vertical scrolling where Column headers are fixed while the body scrolls
• xy-scrolling: combined horizontal and vertical scrolling where Column headers are fixed vertically but track horizontally

Implementers who were previously using CSS to achieve scrolling are now required to remove those styles and set heights and widths via DataTable constructor configs as described in the Scrolling section below.

New Paginator Class

We are pleased to introduce the new Paginator class to manage and render pagination states for the DataTable widget. The value for the config paginator should now be an instance of YAHOO.widget.Paginator rather than an object literal of values. As a result of the new pagination model, the following APIs have been deprecated:

• formatPaginatorDropdown() - Use new Paginator class.
• formatPaginatorLinks() - Use new Paginator class.
• formatPaginators() - Use new Paginator class.
• updatePaginator() - Use new Paginator class.
• paginated - No longer used.

Please refer to the Pagination section below for implementation details.

DataSource Integration Changes

For more detail on changes to the DataSource API, please refer to the DataSource Upgrade Notes section.

As a result of the change to the DataSource's callback value, the following DataTable APIs have been changed:

• doBeforeLoadData(sRequest, oResponse, oPayload)
onDataReturnAppendRows(sRequest, oResponse, oPayload)
onDataReturnInitializeTable(sRequest, oResponse, oPayload)
onDataReturnInsertRows(sRequest, oResponse, oPayload) - In each of these methods, oPayload is now an optional data payload the implementer can pass in to DataSource.sendRequest() via the callback object literal's argument member.

As a result of DataSource's new access to the oFullResponse object, the following APIs have been changed in the DataTable class:

• doBeforeLoadData(sRequest, oResponse, oPayload)
onDataReturnAppendRows(sRequest, oResponse, oPayload)
onDataReturnInitializeTable(sRequest, oResponse, oPayload)
onDataReturnInsertRows(sRequest, oResponse, oPayload) - oResponse is now the full response typed appropriately to JSON, XML, etc. Implementers no longer need to convert this data.

With the introduction of the metaFields collection in the DataSource responseSchema, the DataTable supports some "magic" meta fields, usable to control pagination and sorting states. See the DataSource magic meta section for more details.

Other API Changes

DataTable Class

• sortedBy.dir - When setting the sorted state on your DataTable, use the class constants YAHOO.widget.DataTable.CLASS_ASC or YAHOO.widget.DataTable.CLASS_DESC instead of the strings "asc" and "desc".

RecordSet Class

• updateKey() - Use updateRecordValue().
• keyUpdateEvent - Use recordValueUpdateEvent.

Column Class

• sortOptions.defaultOrder - When setting the default sort direction on a Column, use the property sortOptions.defaultDir, instead of sortOptions.defaultOrder, and use class constants YAHOO.widget.DataTable.CLASS_ASC or YAHOO.widget.DataTable.CLASS_DESC instead of the strings "asc" and "desc".

Getting Started

To use the DataTable control, include the following source files in your web page. Please note that the Element utility is a new dependency as of the 2.3.0 release.

<!--CSS file (default YUI Sam Skin) --> <link type="text/css" rel="stylesheet" href="http://yui.yahooapis.com/2.5.2/build/datatable/assets/skins/sam/datatable.css"> <!-- Dependencies --> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.2/build/yahoo-dom-event/yahoo-dom-event.js"></script> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.2/build/element/element-beta-min.js"></script> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.2/build/datasource/datasource-beta-min.js"></script> <!-- OPTIONAL: JSON Utility --> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.2/build/json/json-min.js"></script> <!-- OPTIONAL: Connection (enables XHR) --> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.2/build/connection/connection-min.js"></script> <!-- OPTIONAL: Drag Drop (enables resizeable or reorderable columns) --> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.2/build/dragdrop/dragdrop-min.js"></script> <!-- OPTIONAL: Calendar (enables calendar editors) --> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.2/build/calendar/calendar-min.js"></script> <!-- Source files --> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.2/build/datatable/datatable-beta-min.js"></script>

Object Model Overview

DataTable creates an internal ColumnSet object to define the header cells for the <thead> and an internal RecordSet object to locally hold data for the rows of the table. The ColumnSet is created using the Column definitions passed in via the constructor, and the RecordSet is created using the ColumnSet object and populated with data provided by the DataSource.

The markup for a DataTable instance starts with the implementer-defined outer container, into which two <table> elements are created. Each <table> is housed in its own container, identified as either the "header container" or the "body container".

The <table> in the header container consists only of a single <thead> element of Column header <th>s. The <table> in the body container consists of a similar <thead> as well as a primary <tbody> element to display cells of data and a secondary <tbody> element to display stateful messages such as "Loading data..." or "No data found".

When the scrollable configuration is set to true, the header container table is displayed and the body container's thead is hidden (but accessible to screen readers). Otherwise, the header container is hidden.

The following diagram describes the DOM elements that are generated in the outer container. Note that the assigned CSS class names should be used as hooks to skin or customize the UI.

Defining Column Headers

After the container element, the next argument in the DataTable constructor is an array of Column definitions that represent each <th> element that will adorn the top of your DataTable. In the simple example below, each Column object literal maps to a data field we will define in the DataSource (see "Instantiating a DataSource" below) and uses the following properties:

• The key is the name assigned to each Column. Columns with keys that map to a data field will automatically populate with that data. Columns with unknown keys will require you to populate the field manually, through the use of a custom formatter. If a key is not defined here, one will be auto-generated.
• The label is the string or HTML value displayed in each <th> element. If the label is null or undefined, the Column header will display the key value as a default.

var myColumnDefs = [ {key:"name", label:"Dog's Name"}, {key:"breed", label:"Dog's Breed"}, {key:"age", label:"Dog's Age (in Weeks)"} ];

The following Column properties are also supported:

• abbr
• children
• className
• editor
• editorOptions
• formatter
• minWidth (default value is 10)
• resizeable (requires the Drag & Drop Utility)
• sortable
• sortOptions
• width (must be a Number)

Note that you may define more Columns than fields and use a custom formatter to populate these cells with data from the RecordSet or any other custom value.

Supplying a custom class name via the className property will assign that value to all cell liners of that Column. Additionally, the Column's key is used to assign a generated class name for all liners of a Column:

"yui-dt-col-" + key

Note that any special characters other than "A-Z", "a-z", "0-9", "_", "-", ".", or ":" will get stripped from this generated class name. Please refer to the Object Model Overview diagram in the Getting Started Section for details on other class names that are applied by the DataTable widget.

Instantiating a DataSource

The last argument for your DataTable constructor is a DataSource instance that defines where the data for the DataTable lives. In this example, the data for this DataTable lives in a local JavaScript array assigned to the variable YAHOO.example.puppies:

YAHOO.example.puppies = [ {name:"Ashley",breed:"German Shepherd",age:12}, {name:"Dirty Harry",breed:"Norwich Terrier",age:5}, {name:"Abby",breed:"Labrador Retriever",age:9}, {name:"Oscar",breed:"Yorkshire Terrier",age:6}, {name:"Riley",breed:"Golden Retriever",age:6}, {name:"Bob",breed:"Miniature Schnauzer",age:8}, {name:"Shannon",breed:"Greyhound",age:12}, {name:"Brandy",breed:"Boxer",age:8}, {name:"Zoe",breed:"Labrador Retriever",age:3} ];

To create a DataSource, pass the array to the DataSource constructor. Then set the responseType to the class constant YAHOO.util.DataSource.TYPE_JSARRAY, and set which fields the DataTable will use -- these fields should map to the Column keys that you defined earlier.

Defining a field in your DataSource causes that data to get copied from the original array into the DataTable's local RecordSet. In the simple case, fields will correlate one-to-one to Columns in your DataTable, but note that you may have fields that are not meant for display to the user. Every field you define in your DataSource will be available in the DataTable's RecordSet, regardless of whether or not they are actually displayed in the UI. To withhold data from the UI, be sure not to define a Column for that field.

// Only display 2 Columns var myColumnDefs = [ {key:"name", label:"Dog's Name"}, {key:"breed", label:"Dog's Breed"} ]; // 3 fields of data are available in the RecordSet var myDataSource = new YAHOO.util.DataSource(YAHOO.example.puppies); myDataSource.responseType = YAHOO.util.DataSource.TYPE_JSARRAY; myDataSource.responseSchema = { fields: ["name","breed","age"] };

Supported responseType values are:

• YAHOO.util.DataSource.TYPE_JSARRAY
• YAHOO.util.DataSource.TYPE_JSON
• YAHOO.util.DataSource.TYPE_HTMLTABLE
• YAHOO.util.DataSource.TYPE_XML
• YAHOO.util.DataSource.TYPE_TEXT

Instantiating a DataTable

Now you are ready to instantiate your DataTable by passing in

1. the ID string or element reference of a container DIV element;
2. your Column definitions; and
3. your DataSource instance.

Make sure the container element is available in the DOM before instantiating your DataTable, either by placing your script in the HTML body after the markup has been rendered, waiting until the window load DOM event fires, or by using the Event Utility's onAvailable method to programmatically create your DataTable as soon as the container element is available.

// Instantiate right away... var myDataTable = new YAHOO.widget.DataTable("myContainer", myColumnDefs, myDataSource); // ... or defer instantiation YAHOO.util.Event.addListener(window, "load", function() { var myDataTableDeferred = new YAHOO.widget.DataTable("myContainer", myColumnDefs, myDataSource); });

Understanding Records, Rows, and DOM Elements

A DataTable instance is made up of a Columnset, a Recordset, and DOM elements:

• ColumnSet The ColumnSet is a set of Column instances. Each Column represents a field of data. Each Column is assigned a unique key index, which represents its order within the ColumnSet. Each Column is also assigned an ID, which is globally unique across all ColumnSets and has no bearing on display order.
• RecordSet The RecordSet is a set of Record instances. Each Record represents a row of data. Each Record is assigned a globally unique ID, which remains constant regardless of sort order. Each Record is also assigned a RecordSet index which represents its current sort order index within the RecordSet.
• DOM elements In the DOM, a <table> element contains a collection of <tr> elements. Each <tr> element displays a Record of data. If the DataTable is paginated, then the <table> will show only a subset of the entire RecordSet. Although each <tr> is assigned a Record instance to display, its unique DOM ID has no relation to its Record's Record ID or RecordSet index. Each <tr> is assigned a yuiRecordId expando property which associates it to its Record. Please note that the DOM ID and yuiRecordId are not related: Sorting will cause yuiRecordId values to be reassigned to <tr> elements but DOM IDs will *not* be reassigned .

The DataTable class provides a set of methods to interact with the DOM elements and their underlying data, such as addRow(), updateRow(), and deleteRow(). Calling addRow(oData) on the DataTable will create a Record of data at the end of the RecordSet, and create and populate a new <tr> element at the bottom of the <table> element. Calling addRow(oData, i) will create a new Record of data and a new <tr> element and insert them into the given index position i of the RecordSet and <table>, respectively.

In cases where pagination is enabled on the DataTable, calling addRow() will always add a Record to the RecordSet, but will only add a <tr> element to the <table> if the new Record is in view within the current page. Implementers should keep this in mind when dealing with RecordSet index values, as these values may or may not be equal to <tr> index values if pagination is enabled.

Using DataTable

The DataTable class and its related classes provides many configuration parameters for you to fine-tune the user experience of your DataTable instance.

• Progressive Enhancement of Markup
• Accessibility Features
• Custom Cell Formatting
• Nested Column Headers
• Basic Column Sorting
• Advanced Column Sorting
• Pagination
• Scrolling
• Adjusting the Render Loop Size
• Row and Cell Selection
• Column Selection
• Row, Cell and Column Highlighting
• More Column APIs
• Inline Editing
• Defining Custom Event Handlers
• Working with the DataSource

Progressive Enhancement of Markup

By progressively enhancing <table> markup that is already on the page, you can make core content available to end users who do not have JavaScript enabled, while delivering a fully functional DataTable control to users who do have JavaScript enabled -- all from the same code base.

To this end, the DataSource accepts an HTML <table> element as a source of data. The DataTable will parse the data out of the table, remove it from the DOM, and replace it with an enhanced control.

<div id="myMarkedUpContainer"> <table id="myTable"> <thead> <tr> <th>AAA</th> <th>BBB</th> <th>CCC</th> </tr> </thead> <tbody> <tr> <td>1</td> <td>bbb</td> <td>ccc</td> </tr> <tr> <td>2</td> <td>bbb</td> <td>ccc</td> </tr> <tr> <td>3</td> <td>bbb</td> <td>ccc</td> </tr> </tbody> </table> </div> <script type="text/javascript"> var myDataSource = new YAHOO.util.DataSource(YAHOO.util.Dom.get("myTable")); myDataSource.responseType = YAHOO.util.DataSource.TYPE_HTMLTABLE; myDataSource.responseSchema = { fields: [{key:"AAA", parser:YAHOO.util.DataSource.parseNumber}, {key:"BBB"}, {key:"CCC"} ] }; var myColumnDefs = [ {key:"AAA"}, {key:"BBB"}, {key:"CCC"} ]; var myDataTable = new YAHOO.widget.DataTable("myMarkedUpContainer", myColumnDefs, myDataSource); </script>

Accessibility Features

Out of the box, the DataTable is accessible via screen readers and keyboard-navigable. Please take advantage of the following additional features to further enhance accessibility:

/* Supply abbr values for THs */ var myColumnDefs = [ {label:"Amt Due", abbr:"Amount Due"}, {label:"Rec'd", abbr: "Received"}, {label:"YTD", abbr:"Year to Date"} ]; /* Supply caption and/or summary values for the TABLE */ var myDataTable = new YAHOO.widget.DataTable("myContainer",myColumnDefs,myDataSource, {caption:"My Caption", summary:"My Summary"});

Custom Cell Formatting

The DataSource class provides a set of built-in static functions to format certain well-known types of data. In your Column definition, if you set a Column's formatter to YAHOO.widget.DataTable.formatDate, that function will render data of type Date with the default syntax of "MM/DD/YYYY". If you would like to bypass a built-in formatter in favor of your own, you can point a Column's formatter to a custom function that you define.

As of the 2.3.0 release, the static formatter functions are called within the scope of the DataTable instance. Also as a convenience, the following string shortcuts may be used to point to the built-in formatter functions:

• "button" points to YAHOO.widget.DataTable.formatButton
• "checkbox" points to YAHOO.widget.DataTable.formatCheckbox
• "currency" points to YAHOO.widget.DataTable.formatCurrency
• "date" points to YAHOO.widget.DataTable.formatDate
• "dropdown" points to YAHOO.widget.DataTable.formatDropdown
• "email" points to YAHOO.widget.DataTable.formatEmail
• "link" points to YAHOO.widget.DataTable.formatLink
• "number" points to YAHOO.widget.DataTable.formatNumber
• "radio" points to YAHOO.widget.DataTable.formatRadio
• "text" points to YAHOO.widget.DataTable.formatText
• "textarea" points to YAHOO.widget.DataTable.formatTextarea
• "textbox" points to YAHOO.widget.DataTable.formatTextbox

// Define a custom format function var myFormatDate = function(elCell, oRecord, oColumn, oData) { var oDate = oData; var sMonth; switch(oDate.getMonth()) { case 0: sMonth = "Jan"; break; case 1: sMonth = "Feb"; break; case 2: sMonth = "Mar"; break; case 3: sMonth = "Apr"; break; case 4: sMonth = "May"; break; case 5: sMonth = "Jun"; break; case 6: sMonth = "Jul"; break; case 7: sMonth = "Aug"; break; case 8: sMonth = "Sep"; break; case 9: sMonth = "Oct"; break; case 10: sMonth = "Nov"; break; case 11: sMonth = "Dec"; break; } elCell.innerHTML = sMonth + " " + oDate.getDate() + ", " + oDate.getFullYear(); }; var myColumnDefs = [ {key:"Date", formatter: myFormatDate}, // Uses custom function myFormatDate {key:"Contact",formatter: "email"} // Uses built-in function YAHOO.widget.DataTable.formatEmail ];

Nested Column Headers

If you'd like your DataTable to display nested headers, the control will automatically correlate the correct set of headers to each <td,> element in order to support screen reader accessibility. In your Column definitions, any given Column object literal can itself host an array of Column object literals. Use the children property to assign descendant Columns. The following Column properties will cascade to descendant Columns if they are defined by a parent but not defined explicitly by children.

• className
• editor
• editorOptions
• formatter
• resizeable
• sortable
• width

var myColumnDefs = [ {key:"page", label:"Page URL"}, {key:"Statistics", className:"myClass", children:[ // className will cascade to children {key:"Visits", children: [ {key:"visitsmonth", label:"This Month"}, {key:"visitsytd", label:"YTD", abbr:"Year to Date"} ] }, {key:"Views", children: [ {key:"viewsmonth", label:"This Month"}, {key:"viewsytd", label:"YTD", abbr:"Year to Date"} ] } ]} ];

Basic Column Sorting

By default, if a Column is defined with sortable:true, then clicking on the Column header will execute a basic sort function that supports comparisons of Strings, Numbers, and Dates.

var myColumnDefs = [ {key:"name", label:"Dog's Name", sortable:true}, {key:"age", label:"Dog's Age", formatter:"number", sortable:true}, {key:"bday", label:"Dog's Birthday", formatter:"date", sortable:true} ];

Keep in mind that sorting a Column first sorts the data in the underlying RecordSet and then updates the DOM UI to reflect this new sort order. Therefore, the type of the data (e.g., String, Number, Date, etc.) held in the RecordSet determines the sort algorithm, not the type as defined in your Column definition formatter property.

In general, the RecordSet expects to hold data in native JavaScript types. For instance, a date is expected to be a JavaScript Date instance, not a string like "4/26/2005" in order to sort properly. Converting data types as data comes into your RecordSet is enabled through the parser property in the fields array of your DataSource's responseSchema. This is especially useful when data is coming over XHR as a String and needs to be converted to a Number, Boolean, Date, etc. A custom function can be defined, or you can use one of the static built-in functions:

myDataSource.responseSchema = { fields: [{key:"name", parser:YAHOO.util.DataSource.parseString}, // Stores incoming data as Strings {key:"age", parser:YAHOO.util.DataSource.parseNumber}, // Stores incoming data as Numbers {key:"bday", parser:YAHOO.util.DataSource.parseDate}, // Stores incoming data as Dates {key:"custom", parser:myParser} // Applies a custom function to incoming data ] };

If your initial data is already sorted, be sure to specify the DataTable config property sortedBy to display the proper UI at instantiation. The value of the property should be either the class constant YAHOO.widget.DataTable.CLASS_ASC or YAHOO.widget.DataTable.CLASS_DESC. Now when the user goes to sort this Column, DataTable will know to sort it in the correct (opposite) direction. Note that setting the sortedBy property does not perform a sort on the Column, it merely applies the appropriate CSS when the DataTable loads.

// The first click on the "receivedDate" Column will sort in descending order var myDataTable = new YAHOO.widget.DataTable("sorted", myColumnDefs, myDataSource, {sortedBy:{key:"receivedDate", dir:YAHOO.widget.DataTable.CLASS_ASC}});

Advanced Column Sorting

The sortOptions property can be used in your Column definitions to specify more advanced sort options. If a Column's default sort direction should be in descending order rather than ascending order, as is often the case for reverse-chronological date fields, be sure to define the defaultDir property on sortOptions:

var myColumnDefs = [ {key:"name", label:"Dog's Name", sortable:true}, {key:"age", label:"Dog's Age", formatter:"number", sortable:true}, {key:"bday", label:"Dog's Birthday", formatter:"date", sortable:true, sortOptions:{defaultDir:YAHOO.widget.DataTable.CLASS_DESC}} // First click sorts latest on top ];

More complex data structures may require custom sort algorithms. You can provide custom sort functions in your Column definition via the sortOptions property. The code below is an example of how to implement nested sorting, where clicking on Column2's header will sort by values in Column2 and, if there are equal values, further sort by values in Column1.

Please note that as of the 2.3.0 release, a single sort function is used for both ascending and descending sorts.

// Custom function to sort by Column2 then by Column1 var mySortFunction = function(a, b, desc) { // Deal with empty values if(!YAHOO.lang.isValue(a)) { return (!YAHOO.lang.isValue(b)) ? 0 : 1; } else if(!YAHOO.lang.isValue(b)) { return -1; } // First compare by Column2 var comp = YAHOO.util.Sort.compare; var compState = comp(a.getData("Column2"), b.getData("Column2"), desc); // If values are equal, then compare by Column1 return (compState !== 0) ? compState : comp(a.getData("Column1"), b.getData("Column1"), desc); }; var myColumnDefs = [ {key:"Column1",sortable:true}, // Uses default sort function {key:"Column2",sortable:true, // Uses custom sort function // Provide sortOptions as an object literal sortOptions:{sortFunction:mySortFunction} } ];

Pagination

Pagination can be used to reduce the real-estate footprint of DataTables with large data sets. As of the 2.5.0 release, implementors should use the new Paginator class to define pagination layout and behavior for the DataTable.

var myConfigs = { paginator : new YAHOO.widget.Paginator({ rowsPerPage : 50 }) }; var myDataTable = new YAHOO.widget.DataTable("myContainer", myColumnDefs, myDataSource, myConfigs);

By default, the DataTable will render a set of pagination controls above and below the table:

Templates and UI components

The Paginator class uses a template and component architecture to afford the greatest flexibility in choosing how to render the pagination controls.

var myConfigs = { paginator : new YAHOO.widget.Paginator({ rowsPerPage : 50, // REQUIRED totalRecords : myData.length, // OPTIONAL // use an existing container element containers : 'my_pagination', // use a custom layout for pagination controls template : "{PageLinks} Show {RowsPerPageDropdown} per page", // show all links pageLinks : YAHOO.widget.Paginator.VALUE_UNLIMITED, // use these in the rows-per-page dropdown rowsPerPageOptions : [25,50,100], // use custom page link labels pageLabelBuilder : function (page,paginator) { var recs = paginator.getPageRecords(page); return (recs[0] + 1) + ' - ' + (recs[1] + 1); } }) }; var myDataTable = new YAHOO.widget.DataTable("myContainer", myColumnDefs, myDataSource, myConfigs);

This Paginator configuration would result in the following UI:

Paginator instances use the configuration attribute template to describe the markup for rendering the pagination controls. The template string contains placeholders to identify where the various control elements should be located. Each placeholder in the template is the class name of a UI component found in the YAHOO.widget.Paginator.ui namespace.

The default template is "{FirstPageLink} {PreviousPageLink} {PageLinks} {NextPageLink} {LastPageLink}".

The following UI components are provided in the 2.5.1 release:

• FirstPageLink
• PreviousPageLink
• NextPageLink
• LastPageLink
• PageLinks
• RowsPerPageDropdown
• CurrentPageReport

For custom pagination controls, create new UI component classes in the YAHOO.widget.Paginator.ui namespace and reference them in your Paginator template.

See the API docs for Paginator and each UI component class for available configuration.

Scrolling

Scrolling is another way to conserve the UI footprint of larger data sets. In the DataTable control, scrolling can be

• x-scrolling: horizontal scrolling where Column headers track with body
• y-scrolling: vertical scrolling where Column headers are fixed while body scrolls
• xy-scrolling: combined horizontal and vertical scrolling where Column headers are fixed vertically but track horizontally

To enable scrolling, set {scrollable:true} in the DataTable constructor config, and define width and/or height String values. X-scrolling is enabled by only setting a width, y-scrolling is enabled by only setting a height, and xy-scrolling is enabled by setting both:

/* enables x-scrolling */ var myDataTableX = new YAHOO.widget.DataTable("myContainer", myColumnDefs, myDataSource, { scrollable: true, width: "40em" // width as a string value }); /* enables y-scrolling */ var myDataTableY = new YAHOO.widget.DataTable("myContainer", myColumnDefs, myDataSource, { scrollable: true, height: "400px" // height as a string value }); /* enables xy-scrolling */ var myDataTableXY = new YAHOO.widget.DataTable("myContainer", myColumnDefs, myDataSource, { scrollable: true, width: "40em" // width as a string value height: "400px" // height as a string value });

Adjusting the Render Loop Size

In cases where your DataTable needs to display the entirety of a very large set of data, the renderLoopSize config can help manage browser DOM rendering so that the UI thread does not get locked up on very large tables. Any value greater than 0 will cause the DOM rendering to be executed in setTimeout() chains that render the specified number of rows in each loop. By default, all rows will be rendered in a single loop.

// Render 50 rows per loop var myDataTable = new YAHOO.widget.DataTable("myContainer", myColumnDefs, myDataSource, {renderLoopSize: 50});

Row and Cell Selection Modes

You can enable row selection or cell selection by assigning the built-in onEventSelectRow event handler to a Custom Event. // Enables standard row selection myDataTable.subscribe("rowClickEvent", myDataTable.onEventSelectRow);

The property selectionMode is used to enable or disable modifier keys and define the multi-selection paradigm. By default, selectionMode is set to standard which enables the modifier keys <shift> and <ctrl> to select multiple rows.

Setting selectionMode to single enables row selection but disables the use of modifier keys for multi-selection.

// Enables single-mode row selection myDataTable.set("selectionMode","single"); myDataTable.subscribe("rowClickEvent", myDataTable.onEventSelectRow);

Setting selectionMode to cellblock, cellrange, or singlecell enables cell selection in block mode, range mode, or single mode respectively.

// Enables cell-block selection myDataTable.set("selectionMode","cellblock"); myDataTable.subscribe("cellClickEvent", myDataTable.onEventSelectCell); // Enables cell-range selection myDataTable.set("selectionMode","cellrange"); myDataTable.subscribe("cellClickEvent", myDataTable.onEventSelectCell); // Enables cell-block selection (modifier keys are disabled) myDataTable.set("selectionMode","singlecell"); myDataTable.subscribe("cellClickEvent", myDataTable.onEventSelectCell);

Take care that the selectionMode value matches the mode you have enabled. If you have assigned the onEventSelectCell handler, then selectionMode needs to be set to "cellblock", "cellrange", or "singlecell" exclusively. Conversely, the values "standard" and "single" are reserved for DataTables with row selection enabled. Finally, mixing and matching row and cell selection paradigms is not recommended.

The methods selectRow() and selectCell() also allow you trigger selection programmatically:

// Selects the first row on the page myDataTable.selectRow(myDataTable.getTrEl(0)); // Selects any cell that receives a checkbox click myDataTable.subscribe("checkboxClickEvent", function(oArgs){ var elCheckbox = oArgs.target; if(elCheckbox.checked) { var elCell = this.getTdEl(elCheckbox); this.selectCell(elCell); } });

The following methods allow you to retrieve selected rows and cells as an array:

// Returns an array of selected Record IDs (across all pages, if pagination is enabled) myDataTable.getSelectedRows(); // Returns an array of selected TR element references (on current page only, if pagination is enabled) myDataTable.getSelectedTrEls();

The look and feel of a selected element can be customized via CSS:

#myDataTable .yui-dt-selected {background-color:#000;color:#FFF;} /*white on black*/

Column Selection

You can enable Column selection by assigning the built-in onEventSelectColumn event handler to a Custom Event. // Enables Column selection myDataTable.subscribe("theadCellDblclickEvent", myDataTable.onEventSelectColumn);

The methods selectRow() and selectCell() also allow you trigger selection programmatically:

// Selects the first Column myDataTable.selectColumn(0); // Selects Column when cell is clicked myDataTable.subscribe("cellClickEvent", function(oArgs){ this.selectColumn(this.getColumn(oArgs.target)); });

The following methods allow you to retrieve selected Columns as an array:

// Returns an array of selected Column instances myDataTable.getSelectedColumns();

The look and feel of a selected element can be customized via CSS:

#myDataTable .yui-dt-selected {background-color:#000;color:#FFF;} /*white on black*/

Cell, Row, and Column Highlighting

You can enable cell, row or Column highlighting by assigning the appropriate built-in event handlers to Custom Events. Please note that mixing and matching cell, row and Column highlighting is not recommended.

// Enables cell highlighting myCellHighlightDataTable.subscribe("cellMouseoverEvent", myCellHighlightDataTable.onEventHighlightCell); myCellHighlightDataTable.subscribe("cellMouseoutEvent", myCellHighlightDataTable.onEventUnhighlightCell); // Enables row highlighting myRowHighlightDataTable.subscribe("rowMouseoverEvent", myRowHighlightDataTable.onEventHighlightRow); myRowHighlightDataTable.subscribe("rowMouseoutEvent", myRowHighlightDataTable.onEventUnhighlightRow); // Enables Column highligting myColHighlightDataTable.subscribe("theadCellMouseoverEvent", myColHighlightDataTable.onEventHighlightColumn); myColHighlightDataTable.subscribe("theadCellMouseoutEvent", myColHighlightDataTable.onEventUnhighlightColumn);

The look and feel of a highlighted element can be customized via CSS:

#myDataTable .yui-dt-highlighted {background-color:#000;color:#FFF;} /*white on black*/

More Column APIs

Columns may be hidden, shown, inserted, or deleted. At this time, these APIs are only supported for Columns which are not nested children of other Columns. The methods hideColumn() and showColumn() merely adjust the width values in the UI. However, removeColumn() and insertColumn() will remove and insert Column instances from the actual ColumnSet.

// Get a Column var oColumn = myDataTable.getColumn(3); // Hide Column myDataTable.hideColumn(oColumn); // Show Column myDataTable.showColumn(oColumn); // Remove Column var myRemovedColumn = myDataTable.removeColumn(oColumn); // Insert the removed Column into position 0 myDataTable.insertColumn(myRemovedColumn, 0); // Insert a new Column into position 3 myDataTable.insertColumn({key:"newCol", label:"New Column"}, 3);

If the Drag & Drop Utility is available on the page, Column reordering can be enabled in your DataTable constructor:

// Enable Drag & Drop reordering var myDataTable = new YAHOO.widget.DataTable("myContainer", myColumnDefs, myDataSource, {draggableColumns:true});

Inline Cell Editing

Inline cell editing can be enabled by assigning the built-in onEventShowCellEditor event handler to a Custom Event. Define the editor type with the editor property in your Column definition. As a convenience, the following string shortcuts may be used to point to the built-in editor functions, but a custom editor function may also be defined:

• "checkbox" points to YAHOO.widget.DataTable.editCheckbox
• "date" points to YAHOO.widget.DataTable.editDate
• "dropdown" points to YAHOO.widget.DataTable.editDropdown
• "radio" points to YAHOO.widget.DataTable.editRadio
• "textarea" points to YAHOO.widget.DataTable.editTextarea
• "textbox" points to YAHOO.widget.DataTable.editTextbox

// Defines editors var myColumnDefs = [ {key:"group", editor:YAHOO.widget.DataTable.editDropdown, editorOptions:{dropdownOptions:["one","two","three"]}}, {key:"date", editor:YAHOO.widget.DataTable.editDate, formatter:YAHOO.widget.DataTable.formatDate}, {key:"amount", editor:"textbox", editorOptions:{validator:YAHOO.widget.DataTable.validateNumber}}, {key:"active", editor:"radio", editorOptions:{radioOptions:["yes","no","maybe"],disableBtns:true}}, {key:"colors", editor:"checkbox", editorOptions:{checkboxOptions:["red","yellow","blue"]}} ]; this.myDataTable = new YAHOO.widget.DataTable("myContainer", myColumnDefs, this.myDataSource); // Enables inline cell editing myDataTable.subscribe("cellClickEvent", this.myDataTable.onEventShowCellEditor);

Defining Custom Event Handlers

The DataTable control provides a robust Custom Event model to allow you to seamlessly integrate and expand upon its built-in fuctionality. For example, after you enable inline cell editing (see Inline Cell Editing), you may want to provide a confirmation to your users in reaction to a successful edit event. Note that the newData value passed to your handler function is the value of the form input field, so in the case of a textbox editor, even if the user has entered a number, the type of the input value will be String.

// Create a Custom Event handler var myHandler = function(oArgs) { var oEditor = oArgs.editor; var newData = oArgs.newData; var oldData = oArgs.oldData; // Output a message to a DIV YAHOO.util.Dom.get("outputDiv").innerHTML = "Cell \"" + oEditor.cell.id + //The edited cell element "\" was successfully updated from \"" + oArgs.oldData + // oArgs.oldData refers to the old value "\" to \"" + oArgs.newData + // oArgs.newData refers to the new value "\" for DataTable \"" + this.toString() + "\"."; // this refers to the DataTable instance }; // Assign the handler to the Custom Event myDataTable.subscribe("editorSaveEvent", myHandler);

Please refer to the API documentation for a full list of Custom Events that are available for the DataTable control.

Working with DataSources

Initial Data

By default, DataTable will fire off a request for data to the DataSource at instantiation. You can disable this feature by setting the config initialLoad to false in the constructor:

// Do not load data at instantiation var myDataTable = new YAHOO.widget.DataTable( "myContainer", myColumnDefs, myDataSource, {initialLoad:false});

If, however, you would like to customize the request sent to the DataSource in the initial load, you can set that value via the initialRequest config:

// Load 10 orders at instantiation var myDataTable = new YAHOO.widget.DataTable( "myContainer", myColumnDefs, myDataSource, {initialRequest:"query=orders&results=10"});

You can further customize the intitial request that is sent to the DataSource by setting the initialLoad config to be an object literal. Doing so allows you to pass in an arbitrary payload of data that will be accessible to you in the callback loop:

// Load 10 orders at instantiation and a tracking ID var myDataTable = new YAHOO.widget.DataTable( "myContainer", myColumnDefs, myDataSource, {initialLoad:{ request:"query=orders&results=10", argument: "12345"} }); // Now oPayload is available in the callback loop myDataTable.doBeforeLoadData = function(sRequest, oResponse, oPayload) { // When response returns, oPayload is "12345" // and available in the doBeforeLoadData customizable method return true; };

Getting More Data

Data can always retrieved with a sendRequest() call to the DataSource, by passing in a DataTable method as a callback handler.

// Sends a request to the DataSource for more data var oCallback = { success : myDataTable.onDataReturnAppendRows, failure : myDataTable.onDataReturnAppendRows, scope : myDataTable }; this.myDataSource.sendRequest("query=orders&results=10", oCallback);

XHR DataSources

If your data is not held in local memory as a JavaScript value, you can point your DataSource instance to a server-generated response and access the data over XHR. Due to browser security constraints, you'll need either a local server URL or a local proxy to a remote host. The DataSource utility supports XHR response types that are JSON, XML, and plain text (such as comma-delimited strings). If your data return as JSON, be sure to include the JSON Utility on your page as a dependency.

Please note that as of the 2.3.0 release, DataSource requests over XHR no longer automatically insert a "?" in the URIs between the host and the query. Implementers should explicitly include the question mark if it is required by your server.

// Point to a local or local-proxy URL var myDataSource = new YAHOO.util.DataSource("http://url/datafeed.php?");

JSON Data

If the data for your DataTable is held in JSON, it may look something like this:

{SalesDatabase: {totalItems:40, itemsFound:2, items: [ {Company:"A1 Services", Title:"CEO", Name:"Jane Jones", Phone:"800-555-2121", Email:"janejones@a1services.com"}, {Company:"Acme", Title:"President", Name:"John Smith", Phone:"800-555-1212", Email:"johnsmith@acme.com"} ]} }

You'll want to configure your DataSource like this:

// Set the responseType as JSON myDataSource.responseType = YAHOO.util.DataSource.TYPE_JSON; // Define the data schema myDataSource.responseSchema = { resultsList: "SalesDatabase.items", // Dot notation to results array fields: ["Company","Title","Name","Phone","Email"], // Field names metaFields: { // optional or "magic" meta totalRecords: "SalesDatabase.itemsFound" } };

Note: The value for resultsList should be of type String. Values of type Array are not acceptable.

XML Data

If the data for your DataTable is held in XML, it may look something like this:

<SalesDatabase totalItems="40" itemsFound="2"> <Item> <Company>A1 Services</Company> <Title>CEO</Title> <Name>Jane Jones</Name> <Phone>800-555-2121</Phone> <Email>janejones@a1services.com</Email> </Item> <Item> <Company>Acme</Company> <Title>President</Title> <Name>John Smith</Name> <Phone>800-555-1212</Phone> <Email>johnsmith@acme.com</Email> </Item> </SalesDatabase>

You'll want to configure your DataSource like this:

// Set the responseType as XML myDataSource.responseType = YAHOO.util.DataSource.TYPE_XML; // Define the data schema myDataSource.responseSchema = { resultNode: "Item", // Node name of each result item fields: ["Company","Title","Name","Phone","Email"], // Field names metaNode: "SalesDatabase", // (optional) node containing meta metaFields: { // optional or "magic" meta totalRecords: "itemsFound" } };

Plain Text Data

If the data for your DataTable is sent as plain text, it may look something like this:

A1 Services,CEO,Jane Jones,800-555-2121,janejones@a1services.com Acme,President,John Smith,800-555-1212,johnsmith@acme.com

You'll want to configure your DataSource like this:

// Set the responseType as plain text myDataSource.responseType = YAHOO.util.DataSource.TYPE_TEXT; // Define the data schema myDataSource.responseSchema = { recordDelim: "\n", // Record delimiter fieldDelim: ",", // Field delimiter fields: ["Company","Title","Name","Phone","Email"] // Field names };

DataSource magic meta

As of 2.5.1, DataSources can be configured to extract arbitrary data from JSON or XML responses using the responseSchema.metaFields collection. Values discovered in the oFullResponse at the metaFields locations will be added to the oParsedResponse.meta object which is then passed on to the DataTable. The DataTable will then look for a few "magic" meta fields in the response object, combine them with special fields in the oPayload object, then use the aggregated information to update its pagination and sorting states. DataTable's onDataReturn methods look for the following magic meta:

recordInsertIndex

Used by onDataReturnInsertRows to indicate the RecordSet index to insert the results at. Defaults to 0.

recordStartIndex

Used by onDataReturnSetRows to indicate the first RecordSet index to set. Defaults to the Paginator's current record offset if the table is paginated; otherwise 0.

sortKey

Used with sortDir to update the DataTable's sortedBy attribute.

sortDir

Used with sortKey to update the DataTable's sortedBy attribute.

paginationRecordOffset

Used to update the Paginator to indicate which page is being displayed.

paginationRowsPerPage

Used to update the Paginator to calculate how to divide the records into discrete pages.

totalRecords

Used to update the Paginator to calculate how many pages of data to provide access to.

Magic meta are useful when you either have control of the format of the JSON/XML service response you are consuming or at least know that it includes needed information. For cases where you do not have control and the service does not provide all the information you need, you can leverage the sendRequest callback object's argument member, which the DataSource will pass to the DataTable's onDataReturn callback as the third parameter, oPayload.

Server-side Sorting and Pagination

If you need your remote server to handle sorting and/or pagination algorithms, you should provide custom code in the following manner:

// Set up DataSource var myDataSource = new YAHOO.util.DataSource("assets/php/json_proxy.php?"); myDataSource.responseType = YAHOO.util.DataSource.TYPE_JSON; myDataSource.responseSchema = { resultsList : "records", // String pointer to the Array of results fields : ["id", "name", "price"], metaFields : { // The value here will be provided to the Paginator totalRecords: "totalRecords" } }; // A custom function to translates sorting and pagination values // into a query string the server will accept var buildQueryString = function (state,dt) { return "startIndex=" + state.pagination.recordOffset + "&results=" + state.pagination.rowsPerPage + "&sort=" + state.sorting.key + "&dir=" + ((state.sorting.dir === YAHOO.widget.DataTable.CLASS_DESC) ? "desc" : "asc"); }; // Custom function to handle pagination requests var handlePagination = function (state,dt) { var sortedBy = dt.get('sortedBy'); // Define the new state var newState = { startIndex: state.recordOffset, sorting: { key: sortedBy.key, dir: ((sortedBy.dir === YAHOO.widget.DataTable.CLASS_DESC) ? "desc" : "asc") }, pagination : { // Pagination values recordOffset: state.recordOffset, // Default to first page when sorting rowsPerPage: dt.get("paginator").getRowsPerPage() // Keep current setting } }; // Create callback object for the request var oCallback = { success: dt.onDataReturnSetRows, failure: dt.onDataReturnSetRows, scope: dt, argument: newState // Pass in new state as data payload for callback function to use }; // Send the request dt.getDataSource().sendRequest(buildQueryString(newState), oCallback); }; var myTableConfig = { initialRequest : 'startIndex=0&results=25', generateRequest : buildQueryString, paginator : new YAHOO.widget.Paginator({rowsPerPage:25}), paginationEventHandler : handlePagination, sortedBy : {key:"id",dir:YAHOO.widget.DataTable.CLASS_ASC} }; var myDataTable = new YAHOO.widget.DataTable('serversorting', myColumnDefs, myDataSource, myTableConfig); // Override function for custom server-side sorting myDataTable.sortColumn = function(oColumn) { // Default ascending var sDir = "asc"; // If already sorted, sort in opposite direction if(oColumn.key === this.get("sortedBy").key) { sDir = (this.get("sortedBy").dir === YAHOO.widget.DataTable.CLASS_ASC) ? "desc" : "asc"; } // Define the new state var newState = { startIndex: 0, sorting: { // Sort values key: oColumn.key, dir: (sDir === "desc") ? YAHOO.widget.DataTable.CLASS_DESC : YAHOO.widget.DataTable.CLASS_ASC }, pagination : { // Pagination values recordOffset: 0, // Default to first page when sorting rowsPerPage: this.get("paginator").getRowsPerPage() // Keep current setting } }; // Create callback object for the request var oCallback = { success: this.onDataReturnSetRows, failure: this.onDataReturnSetRows, scope: this, argument: newState // Pass in new state as data payload for callback function to use }; // Send the request this.getDataSource().sendRequest(buildQueryString(newState), oCallback); };

Skinning DataTable

DataTable comes with a default presentation or "skin," part of the "Sam Skin" visual treatment that accompanies most YUI controls. You can read more about the general approach to skinning YUI components in this in-depth article.

The CSS provided with DataTable is comprised of core, functional CSS as well as the Sam Skin visual treatment.

To explore the CSS which controls the DataTable's presentation, please review the DataTable Skinning Example where the full CSS for the control is displayed.

Top Known Issues

Please see the bug repository at SourceForge for a complete list of known issues.

DataTable Nested in a TD Element Hangs IE7

Implementers creating a scrollable DataTable nested within another table should include the following patch to avoid problems in IE7:

// Insert this line before the instantiation of a DataTable YAHOO.widget.DataTable._bStylesheetFallback = !!YAHOO.env.ua.ie;

Wide Content Truncation in Gecko Browsers

Gecko browsers may truncate some content of Columns whose widths are not specified if a table's overall content is wider than the viewport or its parent container.

IE Quirks Mode Column Widths

In IE quirks mode, Columns without specified widths are not always auto-sized correctly.

In IE Borders Remain Visible When DataTable or Parent Is Hidden

Due to an IE bug, any TABLE element with its border-collapse CSS property set to "collapse", will keep its borders visible even while its contents will be hidden correctly.

Table Captions Incompatible with Column Resizing in Opera

In Opera, table captions interfere with the positioning algorithms needed for Column resizing.

Opera Column Inconsistencies With "scrollable" Enabled

In Opera, scrollable DataTables may experience truncated Column content when widths are not specified in the definition.

Arrow Selection Not Supported in Safari

Due to a known limitation in Safari, arrow selection of rows and/or cells is not supported at this time.

YUI on Mobile: Using DataTable Control with "A-Grade" Mobile Browsers

The core functionality of the DataTable control operates without any major issues on high-end mobile platforms. Implementers should keep in mind the impact that limited real estate may have on end users of the DataTable and be aware of the following preliminary list of smart phone known issues:

• Meta-key multi-selection is not supported.
• Fixed scrolling is not supported.
• Resizeable Columns are not supported.
• Inline editing is not fully supported across all platforms and should be well tested in your application. Specifically, input via textbox is not supported on the Nokia N95, and radio buttons and textbox input validation are not supported on the iPhone.

Support & Community

The YUI Library and related topics are discussed on the on the ydn-javascript mailing list.

In addition, please visit the YUIBlog for updates and articles about the YUI Library written by the library's developers.

Filing Bugs & Feature Requests

The YUI Library's public bug tracking and feature request repositories are located on the YUI SourceForge project site. Before filing new feature requests or bug reports, please review our reporting guidelines.

• Guidelines for YUI feature requests and bug reports.
• Review current bug list or file a new bug.
• Review current feature requests or file a new feature request.