DataTables 2.3

I'm delighted to announce the release of DataTables 2.3.0. This release adds a number of new options and updates, plus a number of patches for issues discovered in previous versions. There is a particular focus on how the column headers of the table are drawn and controlled, as this sets out the groundwork for a new extension to the DataTables family which will be released soon, ColumnControl (keep an eye on this blog for more details when it is released)!

If you are keen to get going with DataTables 2.3 it is available now:

Full release notes are available here.

Example table

Let's take a look at a table rendered by DataTables 2.3:

Name	Position	Office	Salary
Tiger Nixon	System Architect	Edinburgh	$320,800
Garrett Winters	Accountant	Tokyo	$170,750
Ashton Cox	Junior Technical Author	San Francisco	$86,000
Cedric Kelly	Senior Javascript Developer	Edinburgh	$433,060
Airi Satou	Accountant	Tokyo	$162,700
Brielle Williamson	Integration Specialist	New York	$372,000
Herrod Chandler	Sales Assistant	San Francisco	$137,500
Rhona Davidson	Integration Specialist	Tokyo	$327,900
Colleen Hurst	Javascript Developer	San Francisco	$205,500
Sonya Frost	Software Engineer	Edinburgh	$103,600
Jena Gaines	Office Manager	London	$90,560
Quinn Flynn	Support Lead	Edinburgh	$342,000
Charde Marshall	Regional Director	San Francisco	$470,600
Haley Kennedy	Senior Marketing Designer	London	$313,500
Tatyana Fitzpatrick	Regional Director	London	$385,750
Michael Silva	Marketing Designer	London	$198,500
Paul Byrd	Chief Financial Officer (CFO)	New York	$725,000
Gloria Little	Systems Administrator	New York	$237,500
Bradley Greer	Software Engineer	London	$132,000
Dai Rios	Personnel Lead	Edinburgh	$217,500
Jenette Caldwell	Development Lead	New York	$345,000
Yuri Berry	Chief Marketing Officer (CMO)	New York	$675,000
Caesar Vance	Pre-Sales Support	New York	$106,450
Doris Wilder	Sales Assistant	Sydney	$85,600
Angelica Ramos	Chief Executive Officer (CEO)	London	$1,200,000
Gavin Joyce	Developer	Edinburgh	$92,575
Jennifer Chang	Regional Director	Singapore	$357,650
Brenden Wagner	Software Engineer	San Francisco	$206,850
Fiona Green	Chief Operating Officer (COO)	San Francisco	$850,000
Shou Itou	Regional Marketing	Tokyo	$163,000
Michelle House	Integration Specialist	Sydney	$95,400
Suki Burks	Developer	London	$114,500
Prescott Bartlett	Technical Author	London	$145,000
Gavin Cortez	Team Leader	San Francisco	$235,500
Martena Mccray	Post-Sales support	Edinburgh	$324,050
Unity Butler	Marketing Designer	San Francisco	$85,675
Howard Hatfield	Office Manager	San Francisco	$164,500
Hope Fuentes	Secretary	San Francisco	$109,850
Vivian Harrell	Financial Controller	San Francisco	$452,500
Timothy Mooney	Office Manager	London	$136,200
Jackson Bradshaw	Director	New York	$645,750
Olivia Liang	Support Engineer	Singapore	$234,500
Bruno Nash	Software Engineer	London	$163,500
Sakura Yamamoto	Support Engineer	Tokyo	$139,575
Thor Walton	Developer	New York	$98,540
Finn Camacho	Support Engineer	San Francisco	$87,500
Serge Baldwin	Data Coordinator	Singapore	$138,575
Zenaida Frank	Software Engineer	New York	$125,250
Zorita Serrano	Software Engineer	San Francisco	$115,000
Jennifer Acosta	Junior Javascript Developer	Edinburgh	$75,650
Cara Stevens	Sales Assistant	New York	$145,600
Hermione Butler	Regional Director	London	$356,250
Lael Greer	Systems Administrator	London	$103,500
Jonas Alexander	Developer	San Francisco	$86,500
Shad Decker	Regional Director	Edinburgh	$183,000
Michael Bruce	Javascript Developer	Singapore	$183,000
Donna Snider	Customer Support	New York	$112,000

It will immediately be familiar if you have used DataTables before, however, if you look closely at the header you will notice that the column title now aligns correctly with the text in the column below.

This is an evolution of how DataTables has aligned the text for the header:

1.x - Header text was always left aligned with the ordering icon on the right.
2.0-2.2 - Introduced automatic right text alignment for numbers and dates, but left the ordering icon on the right. While this helped with readability for the date, the title text didn't align correctly due to the icon.
2.3 - The ordering icon is on the opposite side of the header text, allowing the text in the column to correctly align between the header and body.

Furthermore, if you "Inspect" the header cell, you will now see that it has a div.dt-column-header element inside it, and uses flexbox for the layout. This is done to allow the addition of other elements to the header - specifically the aforementioned ColumnControl!

New features

New header control options

Continuing the focus on updating the capabilities of the header in DataTables there are a number of new options:

titleRow - provides the ability to make any row in the header the "title" row (i.e. where columns.title are read/written, and ordering icons/actions are added). Note that this replaces the old orderCellsTop option. That option is still supported for backward compatibility, but it is recommended that you use titleRow for new projects.
ordering.handler - can be used to enable/disable the default column header click-to-order listener.
ordering.indicator - can be used to enable/disable the ordering icons in the table's header cells.

Ajax data submission format

When submitting data to the server (e.g. Ajax loading data, or full server-side processing), DataTables uses HTTP parameters. There are, however, times when you might wish to send JSON to the server (particularly for .NET) - it is easy to parse, has (limited) types, and null values. Previously you would use ajax.data and return a string - e.g.:

ajax: {
    url: '/api/data',
    data: d => JSON.stringify(d)
}

The problem with this is that ajax.data executes before preXhr, so any extension or plugin that needs to add extra data to send to the server couldn't without extra processing (it would just see a string).

With 2.3 a new ajax.submitAs option is introduced which will inform DataTables how you want the data to be submitted. It will be either http (default) or json and has DataTables do the stringify of the data for you. So now you would use:

ajax: {
    url: '/api/data',
    submitAs: 'json'
}

The old method still works for backwards compatibility, but it is now strongly recommended that you use ajax.submitAs if you wish to submit a JSON string.

Events on initialisation

There are a lot of events that DataTables can trigger, and they are easily listened for using on(). However, you might wish to listen for events during DataTables' initialisation (i.e. before the API instance is available) - draw and preXhr are perhaps the most common two events for this use case.

Previously, you would need to use jQuery for this - e.g.:

$('#myTable')
    .on('preXhr.dt', (s, s, data) => {
        data.myParameter = true;
    })
    .DataTable({
        ajax: '/api/data'
    });

With the new on parameter you can assign listeners in the DataTables initialisation object and not write any jQuery-based code:

new DataTable('#myTable', {
    ajax: '/api/data',
    on: {
        preXhr: (e, s, data) => {
            data.myParameter = true;
        }
    }
});

Multiple events can be listened for; the event name you want to listen for is the key for the on object.

Upgrading

Upgrading to 2.3 is just a case of updating DataTables' JS and CSS files:

If you are using npm / yarn, run an upgrade on the datatables.net* packages
If you are using our CDN, get the latest sources from the download builder
If you host downloaded files, you can also get the latest files from the download builder.

You are unlikely to run into upgrade issues when moving from 2.3, but you may wish to check over the release notes regardless.

As always, I hope you enjoy using DataTables. Feedback is always welcome in the forums.