Thursday 9th October, 2014

DataTables 1.10.3

A minor release of any component that forms the DataTables suite of libraries wouldn't typically be cause for a blog post, with the release information being announced in the release feed only, but DataTables 1.10.3 sees a number of new features that are very much worth a proper introduction. These include:

Reading DOM sourced data into Javascript objects
Selectors can be provided as functions
cells().render() and cell().render() API methods
iterator() API method
searchDelay option

DataTables 1.10.3 also includes 11 bug fixes, as well as a number of updates for the documentation and examples that are available on this site.

The latest 1.10.3 release is available from the download page now and is also available on the DataTables CDN if you would like to have the files hosted remotely. Full release notes are also available.

DOM sourced objects

When reading data from an HTML table, historically DataTables has always read the information into an array - an entry in the array for each column. However, working with object based data (which many of us are familiar with through JSON) can have a number of advantages such as easy to remember parameter names (rather than needing to remember column indexes).

Reading information into an array is still the default operation in DataTables, but 1.10.3 introduces the ability to read the information into an object - useful for if you are working with the API to manipulate the data. This is done through the familiar columns.data option. Simply set it to be the property name you wish to use for the data read from that column and DataTables will construct the object for you. This also benefits from columns.data's ability to work with complex and nested objects thought dotted object syntax, should you wish to create a more complex data structure.

A running example of this new ability is available, showing how the initialisation on the left below, can construct the object data shown on the right below:

$('#example').DataTable( {
    "columns": [
        { "data": "name" },
        { "data": "position" },
        { "data": "office" },
        { "data": "age" },
        { "data": "start_date" },
        { "data": "salary" }
    ]
} );

[
    {
        "name":       "Airi Satou",
        "position":   "Accountant",
        "office":     "Tokyo",
        "age":        "33",
        "start_date": "2008/11/28",
        "salary":     "$162,700"
    },
    ...
]

API

The new API that was introduced with the release of 1.10 has been well received and forms a core part of what makes DataTables attractive as a library to developers. v1.10.3 introduces a number of new abilities to the API which extend its flexibility and usefulness.

Selector functions

Part of what makes the DataTables API so powerful are the selector options for rows(), columns() and cells() providing the ability to select elements from the table in a natural way based on the structure of the table and building on the flexibility of the selector options in jQuery.

v1.10.3 introduces the ability to provide the selector for these methods (and their singular counterparts) as a function, giving you, the developers using DataTables, complete control over the elements that make it into the matched set. This can be particularly useful when searching for data or using some other complex selection algorithm.

The three selector types (row-selector, column-selector and cell-selector) share a common argument signature when being used as a function (see the documentation for each type for full details):

Index
Data
Node

The function should return true if the item is to be included in the result set, and false if not.

As an example, the code below uses rows() with a row-selector function to select all rows from a table which has a property of overdue set to true in the data for each row. A class is then added to those rows to highlight them:

var table = $('#timetable').DataTable();
var rows = table
    .rows( function ( idx, data, node ) {
        return data.overdue ? true : false;
    } )
    .nodes();

$(rows).addClass('highlight');

Iterator

When working with the rows(), columns() and cells() methods it is common to want to loop over the items that the selector has found and either perform some operation on those items, or read information back from them. This is typically done with the each() method or a for loop, both of which work well, however DataTables has a method it uses internally in the API called iterator() that handles the loop logic for the selected indexes for you. v1.10.3 exposes this method for use externally.

A number of different loop options exist and I would encourage you to read through the iterator() documentation if you want to use this method - it is potentially the most complex in the DataTables API, and is primarily designed for use by plug-in and extension authors.

Renderers

DataTables' ability to work with orthogonal data and and the formatting options of columns.render can be very powerful, but you might often wish to be able to access the rendered data (for example when constructing a select input based on the data in the table to provide filtering options).

The row().data() and other data() methods all provide access to the underlying data, but v1.10.3 introduces the cells().render() and cell().render() methods to be able to trigger a render of the specific data type requested.

Search delay

Finally, a relatively minor, but none-the-less welcome feature is the ability to control the throttling rate of the built-in search input. DataTables 1.10 introduced a throttle of 400mS when using server-side processing to the default search input, reducing the number of times an Ajax request is made to the server for a filtering table to a maximum of once every 400mS, regardless of how quickly a user types into the input.

This throttling rate is now controllable for both server-side and client-side processing using the searchDelay option. The default is still 400mS for server-side processing and 0 for client-side processing, but using this new option you can customise it as you wish.

Coming up...

DataTables 1.10.3 has been hugely enjoyable to work on and I hope you will all be able to benefit from the enhancements it brings. While there are a number of new features here, each individual new feature is relatively small, but they each compliment the customisability and flexibility of the library as a whole. The features here are almost deserving of a major new release, but rather than holding back these enhancements for the other changes slated for 1.11 I wanted to release them as soon as possible.

Work towards v1.11 continues, with a major overhaul of how search works in DataTables being planned. Expect v1.11 in the first half of 2015.

Meanwhile work continues on Editor v1.4 which will introduce C# libraries and .NET examples, with v1.5 planned for release quickly following that. AutoFill, KeyTable and TableTools are all also going to see major updated in the short term.

Enjoy!