Upgrading to DataTables 3 from 2

DataTables 3 is a major step forward for DataTables with a massive number of changes internally, particularly in relation to it no longer having a jQuery dependency, being TypeScript based and the code being modernised. There have also been some items which have been removed or updated, and they are highlighted in this document.

This page is part of a number of related documents detailing the release process for DataTables 3:

• Announcement blog post
• New features
• Upgrade notes
• Download builder
• Examples
• Detailed release notes

Backwards compatibility for a library such as DataTables is very important, so a lot of work has been invested in making sure that as few as possible breaking changes have been made for v2, but there have necessarily been some, and they are detailed below. Please note that these will only impact you if you have written extensions or plugins for DataTables - if you've just followed the public API, you are very unlikely to have any problems. Many of the points that have been changed have been required by the dropping of jQuery as a dependency.

Please note that this is not an exhaustive list of all minor changes. For a complete list, please refer to the release notes.

• Breaking changes
  • Native selectors
  • Renaming of internal properties
  • Callback function scope
  • Cross column search
  • Trigger method return
  • Header and footer rendering methods
• Removed
  • Cache API methods
  • SCSS variables for build time styling
  • scrollXInner option
  • camelToHungarian utility method

Breaking changes

Native selectors

DataTables previously used jQuery to perform the majority of DOM selections. With v3 no longer having a dependency on jQuery, it uses native DOM methods to perform selections. The result is that any selectors that use jQuery's extension methods (i.e. those not part of the native CSS selector specification) will need to be updated. These include :gt(), :lt(), :contains() and others. Please note that DataTables adds support for :eq() on its own as a row selector.

Renaming of internal properties

As part of the modernisation of DataTables, the hungarian notation that was used for the internal properties has been replaced with camelCase notation. DataTables 1.10 introduced camelCase to the DataTables public API, and the odds are high that you've never had to interact with its legacy internal naming - indeed, any interaction with the internal parameters has been strongly discouraged! However, if you have written a plugin for DataTables, or interact with the internal parameters in some way, they will need to be updated for v3.

In most cases, if you do need to update property names, it is just a case of changing them to their camelCase equivalent. However, some internal properties have changed (e.g. the search stores) and might need to be updated. If you are using internal properties, refer to the DataTables source code for how to update them.

Callback function scope

With the removal of jQuery as a dependency for DataTables, it has necessitated a change in the scope of the callback functions, such as rowCallback. Previously, the callback scope used to be a jQuery instance containing the table with an api() function to access the API.

The api() method stays exactly the same, so you can continue to use it, however, the scope is now a DataTable.Dom object. Dom is DataTable's internal DOM library and in many ways is similar to jQuery, but it is not jQuery, nor does it try to be (jQuery is incredibly flexible - more than DataTables needs).

This is only an issue if you are using a jQuery method in the callback function from this. In such cases, you must either wrap this into a new jQuery object or update your code to not use jQuery. For example, if you did:

rowCallback: function () {
 this.addClass('row-rendered');
}

you could now use one of the following options:

rowCallback: function () {
 // Wrap `this` to get a jQuery instance
 $(this).addClass('row-rendered');

 // Use the `Dom` equivalent method:
 this.classAdd('row-rendered');

 // Use a native method
 this[0].classList.add('row-rendered');
}

Cross column search

The behaviour of columns().search() has changed. Previously, it would apply the same search term to all columns, which was rarely used due to its limited usefulness. Now the method will create a search that is applied to the content in the selected columns as a single search term. While the new style is generally far more useful, it does mean that if you used the old method, you will need to update your code. Fortunately, this is easy to do:

If you previously used columns().search() like this to apply a search term equally to multiple columns:

table.columns().search('searchTerm');

you must now replace that with:

table.columns().every(function () {
 this.search('searchTerm');
});

i.e. you apply the search to each individual column by using column().search() (via columns().every()).

Trigger method return

The trigger() method will now return defaultPrevented in the result set, rather than the return values, which were error prone, particularly if multiple event handlers were used. Only if you used trigger() and its return value will this impact you.

Header and footer rendering methods

The plugin API for header and footer renderers (DataTable.ext.renderer.header) used to have the second parameter passed in as a jQuery object. However, with jQuery no longer being a dependency for DataTables, this parameter has changed to be a Dom object. The styling integrations for DataTables have all been updated to account for this, and I've never actually seen anyone using their own custom plugin renderer, so it is very unlikely to cause you any issues!

Removed

Cache API methods

DataTables holds an internal cache of a cell's data to improve performance for ordering and search (trading memory for performance). It used to be possible to access this internal cache using methods such as row().cache(), cell().cache() and column().cache().

These methods were limited and error prone, particularly as the cached data wasn't always guaranteed to be present (it is only cached if DataTables needs the data). As such, these methods were deprecated in v2 and scheduled for removal in v3, which has now been done.

If you want to get the specific data for a cell, use the render() method, which is much more flexible, and the data will always be present. For example, if you previously used:

table.column(0).cache('order');

You should now use:

table.column(0).render('sort');

SCSS variables for build-time styling

DataTables has used SCSS for the stylesheets source for a long time, and as part of that, a limited amount of flexibility was available through SCSS variables. As native CSS variables have become more widespread in browsers, DataTables has been moving towards using them. v2 introduced the use of CSS variables alongside SCSS variables, which produced some complex stylesheets! v3 simplifies that by removing the SCSS variables.

This will only affect you if you were building DataTables from source, with your own custom values for the SCSS variables. If you were going through that process, you would need to update your code to use the new CSS variables.

scrollXInner option

DataTables used to have a scrollXInner option, which could be used to constrain the width of a scrolling table inside a container. This was never a useful feature and added complexity to the code and options. As such is was removed from the documentation for v2 and has now been functionally removed from the code as well. If you do need to constrain the table width, use the container to do so. DataTables defaults to filling the width of the container.

camelToHungarian utility method

This was a conversion method to change camelCase parameter notation to the legacy notation that DataTables used internally. As DataTables uses camelCase internally now, there is no need for their conversion method, and thus it has been removed.