Upgrading to DataTables 1.10 from 1.9
As with all 1.x releases of DataTables, backwards compatibility is a key aim of the upgrade. We want DataTables to simply drop into your current site so you can get the benefits of the new features with the minimum of fuss. The latest version of DataTables can always be downloaded from the downloads page.
While most upgrades should be very smooth, there are a number of points that must be taken into consideration when upgrading DataTables to 1.10 from 1.9 or earlier (see previous update notes for earlier versions).
A DataTable can now be created using:
The difference between the two is that the first will return a jQuery object, while the second returns a DataTables API instance.
The old API (the
fn prefixed methods) is still available in DataTables 1.10 for backwards compatibility, attached to the jQuery object as they were before, but the new API is significantly improved, and I would encourage you to try it!
DataTables 1.10 has significantly upgraded the paging controls of DataTables (see
pagingType), a consequence of which is that the old built-in
two_button form of paging has been removed.
If you are using the
two_button pagination control, and wish to continue doing so (rather than using the
simple option in 1.10, which provides the same buttons, but has more consistent class names for the buttons), an integration file is available. Simply include this file in your document, after you load DataTables but before you initialise your table and the
two_button pagination will be restored exactly as it was in 1.9 (including class names etc).
In keeping with the change to camelCase for the options and API in DataTables, the server-side processing parameters have also been updated to be more modern (see the docs for full information). This change is optional, and only conditionally enabled to ensure full backwards compatibility:
$.fn.dataTable.ext.legacy.ajaxcan be used to force which mode is used. Set to
falseto use the modern scheme, or
trueto use the 1.9- scheme. By default it is
nullfor automatic detection.
- DataTables will automatically decide which form of parameters to use based on if
sAjaxSourceis used to initialise the table:
ajax- The modern scheme will be used
sAjaxSource- The old scheme will be used.
As such, if you are simply updating DataTables and not changing any parameters, you don't need to change your server-side scripts.
If you are using any API plug-ins, they may need to be updated for 1.10 as a few internal functions have changed - some of which may have been used by plug-ins.
The plug-ins available on this site have all been updated to operate correctly with DataTables 1.10 and if you are using these plug-ins, will simply drop into place.
The above improvements have been made possible by the removal of three features of DataTables 1.9- which were deprecated in 1.9 and scheduled for removal in 1.10.
fnRender option provided a method of manipulating a cell when it was created. however, it was provided with a confusing list of options as its arguments, and required a particular structure in DataTables internally that caused performance issues. Removal of
fnRender has lead to a significant improvement in performance of DataTables with large data sets and the ability to provide object instances to DataTables as data source objects (for example Knockout observable objects).
The built-in ability of DataTables 1.9 to show an infinitely scrolling grid through the
bScrollInfinite option has been removed due to the inconsistencies it caused in the API. Removal has also helped simply the internal code significantly.
In place of
bScrollInfinite, the Scroller extra for DataTables is recommended.
Cookie based state saving has been replaced with
localStorage based state saving in DataTables 1.10. Cookie's, with their 4KiB limit were very limited, and incurred a performance penalty since they were part of every HTTP request.
localStorage is much faster and more flexible, and is used as the default storage for state information in DataTables 1.10.
localStorage is not available in IE6/7. As such, the built-in state saving of DataTables is not available in these browsers, in which the state saving will silently fail. The
This document contains general information about upgrading to 1.10, more detailed information about individual topics can be found in the following documents:
If you do happen to encounter any other issues during the upgrade process, please let me know in the forums so it can be addressed or fully documented as required.