Upgrading to DataTables 3
DataTables 3 is a major release with a lot of internal changes, enhancements and improvements over the 2.x series. There have also been some items which have been removed or updated and are highlighted in this document.
It is part of a number of related documents detailing the release of DataTables 3:
As always, backwards compatibility in DataTables is crucial - upgrading your library software to the newest versions should not be a task that we all cower away from! As such, despite the extensive changes in v3, a lot of work has been invested in making sure that as few as possible breaking changes have been made. That said, there have been some legacy features removed, and other changes that you need to be aware of. They are detailed in this document.
Updated
The following section provides details on the major updates in DataTables 3.
CSS selectors
DataTables no longer requires jQuery. This is important here as jQuery has its own Sizzle selector engine that extends what CSS selectors can do (e.g. with :eq() and :contains()), and jQuery used to be used for API methods such as rows() and columns().
DataTables now uses the browser native querySelector methods as its selector engine. The upshot of this is that if you were using jQuery specific selector extensions, they will need to be updated in order to work with DataTables 3. If you were not using jQuery only selectors, then you'll have no errors! If this is an issue, an error such as:
[...] is not a valid selector
Will be shown in your browser's console.
To help mitigate this issue, a new :eq() selector has been implemented for DataTable.RowSelector, as it can be useful to select rows from the table using their position. This selector can be used on its own only, and not as part of a larger selector.
ES6 target
In keeping with the 10 year support goal for DataTables, the Javascript target for DataTables is now ES6 minimum. This means the library can make use of anonymous functions, and other features to help keep the library as small as possible. DataTables has been fully ported to Typescript as part of the v3 work, so the ES6 emit target now comes from and is enforced by Typescript.
Internal properties
Way back when I first wrote DataTables, the code style guide the company I worked for required Hungarian notation. I used that for DataTables, and it got stuck! v1.10 introduced a translation layer so you never needed to use the Hungarian notation parameters or API, but it was still present in the internal properties. That is now no longer the case!
DataTables internal properties have all been updated to be consistently camelCase. This has not affected the APIs, and indeed you can still use the Hungarian notation parameters that worked with DataTables 1.0! However, if for some reason you have used the private internal properties (via settings()), you will need to update them to their equivalent new names.
As an example, one property that was used to get the table ID was .nTable.id (where nTable was DataTables' cached node for the table element). This property is now called simply table, so you could update your code to use settings.table.id. However, I would strongly advise you to not use the private properties, and instead use table().node() to get the table node.
Multi-column search
Previously, when columns().search() was used, it would apply the search term to all columns - i.e. these two are equivalent:
table.columns().search('Upgrade');
// was the same as:
table.columns().every(function () {
this.search('Upgrade');
});
// is the same as:
table.column(0).search('Upgrade');
table.column(1).search('Upgrade');
table.column(2).search('Upgrade');
table.column(n).search('Upgrade');
If you wanted to perform a smart search similar to search() on a subset of columns, you would need to create a custom function for it.
This is no longer the case in DataTables 3 which will automatically create a subset smart search for the matched columns. This means that the two examples above are no longer equivalent. The first line will now perform an "OR" search over the selected columns (in this case all columns, since there is no selector specified).
The old behaviour was undesirable, and I don't recall seeing a single use of it where it was intentional, and therefore it was decided that this change was a safe decision to improve the functionality of DataTables. If you required the old behaviour, you would need to update your code to apply the search term to all required columns.
Callback function scope
If you are using callback functions such as drawCallback or rowCallback, please be aware that the scope of the functions, when they are executed, has changed in DataTables 3. Previously, they used to have the scope of a jQuery instance that contained the table in question.
As DataTables 3 no longer requires jQuery, the callback scope has had to change. Instead, it is now DataTable.Dom, which is similar in many ways to jQuery, but is not jQuery. It is a DOM manipulation library specifically designed for DataTables and its requirements.
The most common action to perform on this in the callback functions was to access the DataTables API via a .api() method. This is retained, so it is unlikely you will need to update any code based on this change, however, if you need to make use of the object as a jQuery object, and that use falls outside the scope of the new DataTable.Dom object, you will have to update your callback function.
Removed
The following section highlights features or methods which have been removed in DataTables 3. These are all very rarely used, so it is unlikely you will encounter any issues with them, but it is important to note these changes.
Cache API methods
DataTables holds an internal cache for some data types (e.g. search information for each cell) and it used to provide methods to be able to access this internal cache such as row().cache(), cell().cache() and column().cache() - plus their plurals. These methods were deprecated in v2 and scheduled for removal in v3, which has been implemented. The cache methods were error-prone due to cache invalidation and far too limited to be useful.
If you used these methods, please update to their render equivalents - e.g. column().render() and cell().render().
scrollXInner option
The legacy scrollXInner option was also deprecated and scheduled for removal in v3. This was a property that could restrict the width of the table inside its container, but I've never seen it actually used in a deployed site or application, so to help keep the code small, it has been removed. Using this property will not throw any errors, but it also will not have any effect.
If you do need this ability, simply use CSS to restrict the table width!
camelToHungarian method
The DataTable.camelToHungarian() method was used to translate camelCase options to the legacy Hungarian notation for use internally in DataTables. However, now that DataTables has been updated internally to use only camelCase notation, this translation is no longer required and thus has been dropped to save space.
The only reason you would have been using this method would have been to provide compatibility with a legacy plugin that you might have created. In the unlikely case that you are using it, it should be dropped and any code updated to use camelCase only.
SCSS variables
The DataTables stylesheets have long used SCSS for its stylesheets, including using SCSS variables to provide customisation. Unfortunately, any changes to those variables require the stylesheets to be recompiled, and thus they are very rarely (if ever!) utilised.
With the advent of native CSS variables, the utility of SCSS variables has fallen off. DataTables 2 started the process of using CSS variables and this has been progressed further in DataTables 3. As such, although SCSS is still used, styling variables are now performed via CSS variables only.
If you were taking the extra step of modifying the SCSS variables and recompiling the stylesheets yourself, you can either continue to do so, or update to use CSS variables.