It is with great pleasure that I announce the release of DataTables 1.9 beta 1. After two weeks of intensive work on DataTables 1.9 (and a good deal of planning beforehand), I'm really pleased with the results, and I hope you will be as well! There is no magical leaps forward here, it is all evolutionary, but there is a lot that will make DataTables a lot easier to work with.
As you will be able to see from the release notes this is a big release of DataTables, with a lot of improvements. More details about what is new in 1.9 are available in the forum.
Release notes for DataTables 1.9.0 beta 1:
API: New API method '$' which will perform a jQuery selector action on the TR elements from the table's TBODY, regardless of paging. For example: oTable.$('#allan').css('background-color', 'red') will find the element (TR, TD or anything else) which has an ID of 'allan' and perform the css action on it. This is potentially a much nicer interface than needing to use fnGetNodes. Still more to be done, such as options to take column visibility, ordering and filtering into account, but this might be the tipping point for calling it 1.9 :-)
API: New API method: fnIsOpen - to work with fnOpen and fnClose, allowing a quick check to see if the row is currently open or not.
API: New init option: Add "sServerMethod" initialisation option to make it easy to change from GET to POST for server-side requests. Needing to supply a custom fnServerData just to get POST was a bit of a pain - this is now no longer needed. In theory fnServerData should generally not be needed now (with fnServerParams, mDataProp and this new parameter making set up much more flexible).
API: New init option: fnCreatedCell - Fired whenever a TD cell is created (or read from the DOM). Very similar to fnRender, but called when the cell is available allowing actions to be taken on the element
API: New init option: oLanguage.oAira.sSortAscending and oLanguage.oAria.sSortDescending language strings which are attached to the label for a column header when it can be sorted. Basically the same as before, but now customisable.
API: New Init option: iTabIndex initialisaiton option - allow the developer to decide what tab index could be given to the table.
API: fnFormatNumber: Now also called for the full numbers pagination elements where a number is displayed. This now means that all numbers displayed by DataTables go through fnFormatNumber - 7441
API: fnPageChange: Will now accept integers as well as the four current strings. The integer given represents the page that the table should jump to. Also update the internal calls to use this new ability as it is cleaner.
API: mDataProp: Pass the cell read 'specific' type to mDataProp if it is given as a function. This might seem like a really simple change, but it greatly expands the flexibility of DataTables. It means that for a column, if you define this function and switch between the four 'get' data types for the cell ('display', 'type', 'filter' or 'sort') you can use different data for each one. So for example you could display a formatted number but do sorting on the numeric version of the number, and filtering on both types (so the user can type either version). The "type" option is for DataTables' type detection. Most of the framework for this was in 1.8.0 - I had thought to include options such as mFilterData (and might in future), but this is the first step to do that without introducing much overhead.
API: fnDestroy: Add an optional parameter to fnDestroy that will cause the table to be completely removed from the DOM, as well as unbinding events etc (the default is the original behaviour, which is to reinsert the table into the DOM where it was originally located) - 7523
API: fnFilter: Filtering now has a case insenstive option - this is bCaseInsensitive in oSearch, or the 6th parameter for fnFilter
New: Accessability change - use A tags rather than DIV/SPAN for the pagination buttons. This is a backwards incompatible change, but a sensible one
New: aDataSort parameter for columns - this allows a column's sorting to take multiple columns into account when doing a sort. For example first name / last name columns make sense to do a multi-column sort. Previously in DataTables you would need to have the user do a multi-column sort themselves (with shift), but now you can define aDataSort (for example aDataSort: [ 0, 1 ]) to do effectively a multi column sort. Note that this is not shown to the end user that this was a multi-column sort in the same way that iDataSort wouldn't indicate that it could sort on a different column (if that was configured). Also note that iDataSort is still available for use and has not been modified externally, but if aDataSort is defined it will be given priority over any iDataSort parameter.
New: Add a 'compress' "target" to the build script (still needs a bit of tidy up). Going to continue using Closure Compiler for DataTables. Tried UglifyJS as well, but found that added about 11K to the size of the library when compressed, relative to Closure:
New: Add a class to the table to identify it as a DataTable
New: Add detailed JSDoc comments for the initialisation options for DataTables
New: Add examples to API methods and tidy up the way oApi is generated a little
New: Add JSDoc comments for the DataTables column object
New: Add JSDoc comments for the DataTables settings object
New: Add my unit test manipulation script. Had it knocking around my own file system forever, but this is the first time I've pulled it into git. Makes sense to have it in given the new build sctruture and the need for a build script now.
New: Add unit test for filtering on non-string input
New: Always add an ID to a table if it doesn't already have one
New: ARIA supoprt for the full numebrs pagination style
New: Big change to how DataTables constructed in the file system - breaking the various parts of DataTables seperate files. This is probably the biggest individual change to DataTables since it was first written, but the code itself is more or less the same - just split out into different files. The one big change to the code thus far is to change the function classSettings into an object that is extended. More work is required on this to complete the alteration, but for now DataTables is building into the same workable form as before using the new make.sh file.
New: Example showing how to set defaults
New: Experiment with tabindex on the sorting headers and the pagination buttons. More to follow...
New: First effort at ARIA support - the table control widgets link themselves to the table now ('controls') and the column headers say what they do. The table is also described by the information control. Note that an ID on the table is needed for most of this, since ARIA can reiference elements.
New: Flexible width example
New: For plug-in authors, the internal function _fnApplyColumnDefs has been created and made available to make it much easier to present aoColumns and aoColumnDefs options for plug-ins (the names of the parameters can be whatever you want). Basically the function will take each of the two arrays (or null if not available) and figure out what definations should be applied to what columns - and then callback to a function that will apply the configuration (specific to the plug-in). This is now also used for the DataTables aoColumns and aoColumnDefs.
New: Internal and API methods now use JSDoc comments rather than my old system
New: jQuery plug-ins package file
New: One thing that has bugged me a little since I first wrote DataTables was that for some mental reason I picked $.fn.dataTable rather than $.fn.DataTable as the jQuery access function. This commit now allows either approach.
New: Optimisation for sorting - when the sorting runs it will execute the sorting function a lot, particularly for large tables, so we want these functions to be as fast as possible. As it stood, each time the function ran it would prep the data and then do the required comparison - and it would do that data prep every time. This is pointless since toLowerCase (for example) is always going to give the same result when using the same input - so now introduced a third sorting function type (in addition to 'asc' and 'desc') called 'pre', which will pre-format the data to be sorted, only once for each item to be sorted, allowing the sorting comparison function itself to be really fast (simply just the comparison). This is also backwards compatible, if the sorting type doesn't have a 'pre'-formatting method then it will just use the two sorting functions as normal.
New: Update SyntaxHighlighter to include a submit button to run the example directly in JSBin (live.datables.net)
New: Update the styling of the default pagination to make it more attractive. Also remove the previous change to use A tags - concerned about backwards compatibility and developers needing to update styles. Impact on accessibility to be evaluated, when ARIA button roles are added.
Update: Add a parseInt to the two integer values that come back from server-side processing. The question about why it doesn't work when strings are returned (or rather, why is it broken) keep cropping up in the forum.
Update: Add and document the extension object for DataTables. The extension object (ext) allows plug-ins to be added to DataTables (and is also used for this internally as well).
Update: Change how the state loading callback functions operate - previously it would require that a cookie be available before the state loading callback is called. Now is state loading occurs at all the callback function will be fired - allowing easer integration with server-side state storage. I don't actually see a downside to this and it should be perfectly backwards compatible.
Update: Complete ARIA support for column headers so we now consider bSortable
Update: Copy the column options on top of the column settings object
Update: Correct link for initialisation options
Update: Documentation - note that DataTable is not a global object, but give variables for how it can be accessed
Update: Documentation changes, suggested by Michael Mathews (author of JSDoc). Generated documentation for DataTables should now be more or less complete.
Update: documentation links to add defaults example and remove fnGetNodes from post-init description
Update: Documentation update for fnDrawCallback - it does actually get a parameter - the settings object
Update: highlight example to use $ API method
Update: jQuery 1.7 time - DataTables passing all unit tests with the new jQuery
Update: Language options always get extended with the initalisation object now - this allows you to use both a file source and the local script if you wanted. It also allows backwards compatiablity with language files that don't have the oAria namespace.
Update: Little bit of info in the build script
Update: Make warning message smaller - too much payload for something that is virtual never seen
Update: Modification to the way table width is handled - if the 'width' attribute is on the table tag, then we use that to size the table. This makes having a table width of 100% much easier than before. The reason we need to do this is that there just doesn't appear to be a good way to get the relative width from stylesheets across browsers.
Update: modify the api_in_init.html example to use the $ API method
Update: Modify the form example to use the new $ API method
Update: Performance changing sorting / filtering
Update: readme for v1.9 and note that the license can be either/or for the GPLv2 or BSD
Update: Remove trailing commas!
Update: The 'i' counter that was in the sort loop was outside the function scope, so the JS engine would need to go back up a level in its scope chain. Not a big thing, but any speed in the sorting function is welcome
Update: The A tag for the pagination causes the A tag colour to show through - add a colour to stop that
Update: the select row examples to use the $ API method
Update: Tidy up the initialisation code a bit for creating the settings object and integrate the language compatibility fully
Update: Tidy up the pagination functions a bit - lass code and easier to understand
Update: Tidy up the way events are added to the pagination and headers to reduce code.
Update: Tidy up use of typeof and undefined in DataTables - the main goal is to reduce code size under 70K here, but its a good opertunity to get this area sorted out. Note that the unit test update for fnInitComplete is because 'json' is now always passed through, although it will be undefined in anything but Ajax sourced client-side processing.
Update: Trivial change to the full numbers conditional logic. Its the same logic as before, just more sensibly laid out.
Update: Update ARIA attributes based on feedback from Vinnie Young ( http://groups.google.com/group/free-aria/browse_thread/thread/96156d857f35e10d#msg_e451dd817dfe01b1 ). Label for column header now states the column title and the next sort. TBODY has a role of alert and TR elements in THEAD have a role of 'row'
Update: Update documentation for column defaults name change
Update: Update internal variable names - rather than using the local private variables _aoSettings and _oExt, these are now attached to the DataTable object as static parameters. Cleaner and will document easier as well.
Update: Update package version
Update: Update path given new location for the build script
Update: Update setAttribute to use id - works just as well and slightly smaller
Update: Update to jQuery 1.7.1
Update: Update unit tests to take account of the change to the pagination elements now being A tags, rather than SPANs/DIVs. Good that the change broke the unit tests since it is backwards incompatible
Update: Updates for hte build script - to do a test build now do "./make.sh debug", otherwise docs, jshint and compiler will all run
Update: Use the oSearch model for the default initialisation and column initialisation
Removed: _fnArrayCmp is not used anywhere these days - ditch it
Removed: Drop "_iId" from the row model - its not used anywhere in DataTables these days. An old legacy property from the 1.3 days I think - can't imagine any third party plug-ins use this property either - its more or less useless these days.
Removed: iNextId can go the same way as _iId since that is all it was needed for
Fix: Add a default unit test set for the mDataProp test set - objects
Fix: Add copyright header to the min file
Fix: Add field quotes (`) to the main server-side processing script. For most cases this will make no difference, but some columns might have a special character in them (- for example) and need this quoting.
Fix: Alter how the selector for the $ API method works so that it works on the TR elements and their decendants
Fix: Alter the extending of the initialisation parameter with the defaults a little such that objects are deep copied and arrays are not (code needs tidied a little - want to get it passing all unit tests first). The thing here is that we can't use jQuery's $.extend for a full deep copy since we don't want to deep copy arrays (for example aaSorting, where the default sort would always be applied), but we do want to deep copy objects (and not just take a reference to the default object). Thus we can't use $.extend :-(.
Fix: Apply default column options - the column defaults weren't actually being included, nevermind applied. Now put them in DataTable.defaults.columns and have them work!
Fix: Apply some DRY to pagination extension code
Fix: bAutoWidth wasn't documented
Fix: Calculating the width of a table can be incorrect when the calculation table is hidden due to an issue with jQuery's width/outerWidth calculation (http://bugs.jquery.com/ticket/9945). This is a bit of a work around to get the css value and check if it is a percentage - this is not perfect (since other relative values aren't checked - although they are generally unlikely to be used), but it is effective for most cases.
Fix: Can't extend null on the classes - make the default an object for the settings classes holder
Fix: Cast fnFilter input to a string always - since we are always going to treat it as a string
Fix: DRY for the four event handlers
Fix: Filtering doesn't deal with carriage returns - 6313 - thanks to Jonathan Camp for this fix.
Fix: Fix numeric sorting pre-formatting method typo, picked up by the unit tests
Fix: Fix typo 'destory' -> 'destroy'.
Fix: Fix various comment spelling mistakes
Fix: Fixes from JSHint and JSHint configuration. Note that I'm using a slightly modified JSHint to remove checking of mixed spaces/tabs and trailing white space due to issue 21 against JSHint (https://github.com/jshint/jshint/issues/21) - specifically it objects to my comment styling for the JSDoc comments, which I've got _everywhere_!
Fix: fnDestroy does not remove all jQuery UI markup
Fix: fnInfoCallback was not being executed in the DataTables' instance scope
Fix: fnUpdate recursion would cause an error if dealing with nested arrays - 7292. Fix is to let the function know, with a private variable, that it is being called recursively.
Fix: Function name in comment for fnSetColumnVis was wrong
Fix: If there is an sClass defined for a column, and a footer element for the column, apply the sClass to it, just as we do to the header.
Fix: Ignore MacOS .DS_Store files
Fix: Ignore min file in git
Fix: It appears that the latest Webkit browsers have changed their scrolling behaviour slightly, which is causing the unit tests to fail. Basically the 'scroll' event is being fired when the infinite scrolling table is having data written to it (i.e the scroll changes - so its kind of fair enough!), so add a check to only load the first set of data when there is no scrolling applied.
Fix: Limit the span modification for the sort classes - from pull request 40 (https://github.com/DataTables/DataTables/pull/40).
Fix: No hover underline or active outline for full numbers pagination
Fix: Only the constructor should be referring to oJUIClasses - also in the constructor copy the class object rather than referencing
Fix: Rolling back the change to starting that used localeCompare - it was causing incorrect sorting in IE9 (unit test failures)
Fix: Same thing for two button pagination control
Fix: Small documentation update for fnGetNodes to suggest that $ should be used
Fix: Unit tests were using asStripClasses which was an old legacy typo... It should be asStripeClasses and I've removed the alias in 1.9, thus the unit tests need to be updated.
Fix: Was only binding xhr event where there was more than one table! Doh!
Examples: Update editable example to use $ API method
Examples: Update post init events example to use $ API method - easlier than fnGetNodes
Examples: Add JSONP examples for the 'id's and 'objects' sever-side scripts. Might make all JSONP compatible at some point...
Examples: Don't initialise the xhr listener if there is no DataTable on the page
Examples: Simplify select row code
Examples: Update example links with new flexible width example
Examples: Need element scope to calculate TD index! - 6647
Dev: Add defaults for aDataSort and sServerMethod (the two new parameters that have been introduced since the last release)
Dev: Add the Ajax core JS file (forgot to commit it before!)
Dev: Change the defaults object from attaching to DataTable.models to just the top level DataTable as DataTable.defaults - makes it much easier to access it when trying to set a default.
Dev: Document the row model and update the data methods to extend this model as the base for aoData
Dev: Don't include duplicate classes - just extend the base for the jQuery UI version
Dev: First pass are using $.extend for the settings and initialsation objects.
Dev: Had broken API extension methods... There was a bit of confusion between oApi as an internal variable and as an external variable. This commit effectively brings them together - you can access the internal functions as regular API methods now - although that might not be a particularly good idea just yet - not to be documented until I'm happy with this.
Dev: Override the default sDom when using jQuery UI
Dev: Pull the Ajax functions into their own file
Dev: Rearrange the 'ext' option and make the base object a model so it can be readily documented. More documentation required for the model to explain what each of the options does
Dev: Reduce code size slightly (not much in fairness - but every little helps...)
Dev: Remove pointless duplication of code - it was doing the same thing, just with different pointers
Dev: Remove redundant information in the message
Dev: Slight modification of style for the inner functions in the pagination controls
Dev: Slight modification of the code for getting the Ajax source property for Ajax sourced data and server-side processing to save a few more bytes :-)
Dev: Small tidy up of how the column filter state is saved
Dev: Tidy up the constructor to take account of the fact that we now have every possible property in the initalisation objects, since it is being extended from the details - i.e. no need to check for 'undefined' any more.
Dev: Tidy up the settings object - a lot of the settings should have null as the default since they are set by the initialisation.
Dev: Two button navigation using A tags again - important for if there is no CSS
Dev: oLanguage is a namespace, not a member
Download DataTables 1.9.0 beta 1