New in DataTables 1.7

DataTables 1.7 is quite an exciting release for the number of new features that it includes and its improved interaction methods for you the developer. Some of the changes are small, some are large, but overall DataTables 1.7 should be much more pleasant to work with. Hopefully the new feature set will make this a compelling upgrade. Enjoy!

Major new features

• X and Y scrolling:
  • X scroll demo | Y scroll demo | XY scroll demo | Y themed scroll demo
  • When dealing with large data sets, but restricted to a small visible area, it is necessary to provide a visual method to the end user to indicate that there is more data available, and make it easily accessible. Pagination has been used for this in DataTables, but now in 1.7 you can optionally enable scrolling in the X and Y dimensions - and it works perfectly with or without pagination. Using the initialisation parameters sScrollX and sScrollY simply set the height and width that you wish to constrain the table to. These two parameters accept any CSS measurement.
• Column definitions:
  • General targeting demo | Class targeting demo | Right hand columns demo
  • When giving column specific instructions to DataTables prior to 1.7, it has been necessary to provide aoColumns with an array of details, the size of which exactly matches the number of columns in the table. This can be difficult at times when you have a lot of columns, or the table size can change dynamically. To overcome this, 1.7 introduces aoColumnDefs which is an array of objects which takes exactly the same parameters as aoColumns but also has the additional parameter aTargets. This array allows you to target a specific column (or all columns) using:
  • a string - class name will be matched on the TH for the column
  • 0 or a positive integer - column index counting from the left
  • a negative integer - column index counting from the right
  • the string "_all" - all columns (i.e. assign a default). aoColumns can still be used with 1.7, and is sometimes suitable, but in general aoColumnDefs should now be preferred. A column can be targeted by multiple column definitions, in decreasing priority order, but an aoColumns parameter will take priority if it is defined.

• DataTables object retrieval:

  • Add row demo | Regex demo

  • The object that is created during the DataTables initialisation is the one that can be used for all interaction with the API. As such a reference to this object is required, typically stored in a global variable. In DataTables 1.7 it is possible to retrieve this object by calling the $().dataTable() function again on your table, thus mitigating the need for a global variable. There are a few points to note about this:

    • Calling with no parameters - $(...).dataTable(); - This will simply return the DataTables object for the selector, or create a new table if no existing table is found.
  • Retrieving with an initialisation object - $(...).dataTable({"bRetrieve":true, ...}); - It is not possible to alter the table parameters after initialisation like this, but it is useful to be able to just use a single call to $().dataTable(). Setting bRetrieve to true, tells DataTables that you acknowledge this.
  • Reinitialising the table - $(...).dataTable({"bDestroy":true, ...}); - Actually, it is possible to reinitialise the table, but it's fairly brutal. This will destroy the old table and then initialise a new one.
  • Otherwise - an alert will warning you of what is happening.

User visible features

• Formatting of numbers in table info display:
  • The formatting of numbers in the table's information display can aid readability when dealing with large numbers (for example "1,000,000"). The callback function fnFormatNumber is used to do exactly this formatting. It takes a number and returns a string. The default is to enter a comma as a thousands separator.
• Smart filtering on individual columns:
  • The global filter in DataTables has always had smart filtering - where you can enter words in any sequence and they will still be matched. 1.7 introduces this ability to individual column filtering as well.
• Global filter is shown in the input box:
  • When settings the global filter, it can be useful to have the global filter input box populated with the search string being used. This can aid user comprehension of what is happening and reduce confusion when they alter the global filter. This is enabled by default when setting a filter using fnFilter, but can be disabled by using the fifth parameter (boolean) in fnFilter.
• Empty table text option:
  • In previous versions of DataTables there has been no separation of the 'empty table' text used when there is no data available in the table at all, and the text used for when filtering is so tight that there are no matches. 1.7 introduces the language parameter sEmptyTable which is used when there is no data. If this parameter is no present, sZeroRecords is used as before.

Developer enhancements

• Destroy API function:
  • With DataTables 1.7 it is now possible to return the HTML page to the state it was before DataTables initialisation took place. By calling the new fnDestroy API function, all of the enhancements DataTables adds to the table will be removed and the full table drawn as it was in its basic state.
• Automatic type detection of HTML data, and trimming of white space:
  • In prior versions of DataTables it was necessary to specifically indicate if you wanted DataTables to treat a column as 'html' (using sType) which would effect sorting and filtering. This is now done automatically. Furthermore, white space is automatically trimmed from data which makes life much flexible when formatting tables in HTML.
• null data now accepted:
  • Having a "value" of null for data in a JSON structure is not uncommon, particularly when using a JSON parser built into PHP, .NET etc. DataTables used to reject this since it is not a display value, but will now treat it as an empty string. As such null values are accepted from any data source for DataTables.
• Specify paging length menu easily:
  • Length menu customisation demo
  • It has always been possible to define your own length menu using the language options in DataTables, but this is a cumbersome method for doing this. The new initialisation parameter aLengthMenu makes this much simpler. This parameter is either a 1D array of options which will be used for both the displayed option and the value, or a 2D array which will use the array in the first position as the value, and the array in the second position as the displayed options (useful for language strings such as 'All').
• Enable or disable smart filtering:
  • Smart filtering is very useful for user interactions when you just want a quick search box, but when you want to provide a regular expression to the filter, it can confuse things significantly. Smart filtering can now be enabled and disabled on both individual columns and the global filter using the 'bSmart' in the initialisation objects, or the fourth parameter (boolean) in fnFilter.
• Callback functions are executed with the DataTables object scope:
  • API function in initialisation demo
  • Using API functions in the initialisation callbacks (fnDrawCallback for example) can be useful for data retrieval, but used to be difficult since the object you want to access wasn't fully initialised at the time of calling it! The callback functions are now executed with the scope of the DataTables object, meaning that all of the API functions can be retrieved through this this object.

Minor new features

• Closure compiler:
  • The minified file version of DataTables is now compiled using Google's Closure Compiler, rather than YUI Compressor. This yields a dramatic decrease in size of the .min.js file. 1.6.2 with YUI compiler is 70K, but 1.7.0 beta is only 54K, despite all of the new features! Wonderful - thank you Google.
• Date and number sorting now allow blank values:
  • It is not uncommon to have blank values in a column which is otherwise populated with dates or numbers. The built in sorting functions now allow for this case, and date or numeric sorting is preserved.
• Anti-IE XHR cache:
  • A common issue with IE and GET XHRs is that it will cache the return value, even although the data on the server might have changed. Before it was possible to get around this using fnServerData and POST (or a random variable), but now DataTables using the jQuery anti-cache option for $.ajax() (a random variable).
• Don't redraw option in fnDeleteRow:
  • When deleting more than one row at a time, it is now possible to tell the table not to redraw when calling fnDeleteRow (third parameter - boolean), making the action much faster. After you have deleted the rows required, just then call fnDraw to update the table to take account of the changes.
• Malformed JSON warning:
  • Built in JSON parsing in jQuery 1.4, rather than using eval, is superb, but when it can't parse a JSON string it will simply call its error function, rather than throwing a warning to the user. As such prior to DataTables 1.7 this would fail silently and could be quite confusing. Now DataTables will 'alert' an error telling you what has happened.
• Specify a cookie prefix:
  • At times you might wish you use your own cookie prefix for storing state, rather than the default. This can now be done using sCookiePrefix. The cookie handling infrastructure in DataTables 1.7 has been rewritten to cope with a large number of state saving cookies, which could before cause server errors when hitting the 4KiB limit. DataTables now uses smart handling to avoid this.

There are a wide range of bug fixed and internal updates as well as all of these new features - for example it should no longer be possible (or at the very least much less likely) to exceed the 4KiB cookie limit, and fnClose will work with server-side processing. To read the full release notes, please check the release notes.