- When working with plug-ins such as TableTools, there is no clearly
defined way at the moment to get at the plug-in instance, with each
doing it its own way (TableTools as a static function, while Scroller
attaches itself to the settings object and KeyTable is its own
intialiser, amoung others...) so I'm introducing these methods to
unify this.
- plugin() is used by DataTables users to get their plugin instance, for
example `table.plugin('tabletools')` would get the TableTools
instance allowing full access to its API.
- plugin.register() and plugin.deregister() are called by the plug-ins
when they attach themselves to a DataTable. The 'extras' will all need
to be updated to use this new method.
- Some plug-ins would benefit from be able to automatically initialise
when a DataTables is constructed, to this end, a construct for static
events is added here, with the static function $.fn.dataTable.on()
listening for events. Currently only the `construct` method is
available, although others could potentially be added in future if
they are useful. As such, the code driving it is intentionally simple
for this cas,e but the API abstract enough to allow future expansion.
- There is no `off()` method, as I'm not sure it would be that useful.
Could be added in future if needed!
- The server-side processing parameters used by DataTables 1.9 are very
ugly, and rather arkward to work with, so in keeping with the
camcelCase approach of 1.10 and its general monderisation, when using
the `ajax` option to set the ajax url for data, DataTables server-side
processing will now use a much more modern method of telling the
server what data is required - specifically using arrays and objects
in neatly formatted data.
- The old 1.9 method is invoked if sAjaxSource is used to set the ajax
url, or if $.fn.dataTable.ext.legacy.ajax is set to true. As such,
this change should be fully backwards compatible since `ajax` is a new
option in 1.10.
- This new ability adds 334 bytes to the min file, primarily, because
the old method is retained (using just the new method would actually
reduce the size slightly).
- The _fnCalculateColumnWidths is probably the oldest function in
DataTables which has mostly reamined as it was 5 years ago! However,
its time to trim it down a bit and optimise now. This rewrite has all
the same actions, but results in a minified file which is about 700
bytes smaller than before.
- The bAutoCss parameter is not one that I've ever actually seen used,
so I've dropped it out here to reduce complexity. It was only useful
for making the scrollbars always visible on the table, which can just
as easily be done with `div.dataTables_scrollBody { overflow: scroll
!important }` since that will take a heigher priority that the
DataTables appled style.
- The moster _fnFeatureHtmlTable and _fnScrollDraw functions have been
refactors, saving around 1.5K in size (in the minified file)
- The infinite scrolling feature of DataTables is inadequate as a
solution for the problem it is trying to solve as it introduces a
number of compatiblity issues with the rest of the API parimarily
due to the fact that it "tricks" the rest of DataTables into drawing
just a small proportion of the table, leaving the elements which are
currently in place. This means that DataTables doesn't realise that
the table has additional rows at the top of the table, thus breaking
numerous interactions with the API and confusing developers. As such,
its a poor feature that is just taking up space and could be done much
better externally.
- I will write an infinite loading feature for DataTables in future for
users that do what to use this ability - there is nothing stopping a
simple scroll event being attached to the scrolling element and
calling the rows.add() function. This is exactly what the new plug-in
will do.
- Scroller is a much better solution for defined length tables.
- In keeping with the camelCase name changes for DataTables 1.10, the
default Ajax data source object property name has been updated from
`aaData` to just `data`. Note that this is a fulyl backwards
compatible change - if aaData is present in the data, it will be used.
<input> controls used by DataTables for length change and filtering
respectively.
- Bootstrap 3 requires a styling class be set directly on the element,
so in order to correctly support Bootstrap 3, which we want to do, we
need to have the ability to set these classes. This commit adds that
ability
- Because of the decoupling of the filtering and sorting, the filtering
was missing that the indexes of the displayed data will have changed
after a sort. So need to do a full filter when just sorted
- scrollX was often the source of frustration when setting it to
anything other than "100%", which is was in the demos and
documentation but it makes it easy to see that you could set it to be
50% or anything else. That usually broke the developer's layout. So
now you can just use scrollX: true, to enable horizontal scrolling.
The demos have been updated for this.
- Rather than creating a new JSON object from the XHR, use the one that
was returned by the server. This is useful if you manipulate the data
since you want to just keep using the same object.
- The HTML5 attribute detection for sorting, filtering etc was breaking
if you didn't provide a filtering _and_ sorting attributes since they
created an undefined get data function, which causes DataTables to
complain. Fix is to just check for a null value.
- IE10 has a little `x` to clear text boxes which fires the `input`
event, so we need to monitor for that in the filtering input.
- While I'm here, I've also added support for the paste and cut events
to change the filtering when they fire. Via keyboard the fire on
keyup, but not if you use the mouse. They do now.
- Not that it us possible to have multiple events fire (keyup + paste
for example). The logic of checking for a change of input counters
this.
- Thhis fixes DataTables/DataTables issue #227.
- Based on thread 17024 - if you have a large table with a lot of
elements in the tbody, the find('*') selector was of course selecting
them all. That results in poor performance. DataTables doesn't add any
events to the children in the tbody, so we can filter out those
elemetns and keep the element list ot a sensible size.
- Based on the discussion in forum thread 16961 and the results from
http://jsperf.com/html-decode I've updated how the HTML decode for
filtering is done to bypass jQuery and use DOM methods directly. It is
more code but it is also much faster.
- Based on feedback from Rich Caloggero in forum thread 13421 the ARIA
live region DataTables was adding to the TBODY element of the table
have been moved to the table information element, so screen readers
don't go mad announcing the new informaiton in the table on every
change, but rather just read the summary.
- The built in filtering formatters and type detection need to be able
to handle just about any data being passed into them. They were
tripping up with null data being passed in before.
- Based on the discussion in forum thread 16938 DataTables now has the
ability to use _PAGE_ and _PAGES_ in addition to the exisiting
_START_, _END_, _MAX_ and _TOTAL_ options in the information language
strings. This allows the developer to show paging information rather
than record based information in the information element.
Based on DataTables/DataTables/issues/214 this commit uses the optional id parameter for the AMD define function to give DataTables a 'name' for easy referencing.
- DataTables tables previously did not automatically adjust their sizing
when the window width was changed, which let to a lot of additional
calls to fnAdjustColumnSizing in peoples code (and support questions
in the forums). This commit add adjustment to the sizing automatically
for tables width have width="100%" as an attribute (we can't use CSS
since we can't know if it is relative or absolute sizing) - extending
what went before. This has full compatiblity with scrolling and
non-scrolling tables. A throttle is used to not bring IE to its
knees...
- The shim layer call to api.draw() was telling the API to reset the
paging, but it should have been holding it static (as it now does by
passing false in to draw()).
- This event allows plug-ins (specifically FixedColumns in this this
case is what I'm thinking of, but others such as FixedHeader could
also benefit) to alter their layout when the column sizing is changed
(for example by a window resize).
- My fix a while back for detecting if a column was no longer available
in a table was duff, since it used $.map which flattens its array
return, but sorting needs a 2D array.
- Fixed by doing our own itteration
- Because of the way _fnExtend() was deep copying objects, but shallow
copying (i.e. references) arrays, the arrays used in the settings
object were actually being shared between all instances of DataTables
on a page.
- This is most noticable in the column filtering, whereby if you apply
a filter to the column of one table, it is applied to all tables!
- The fix is to dump _fnExtend and replace it with a typical jQuery
extend. However, one special consideration is made for the data being
passed it - we absolutely do want that reference to be retained (that
+ the fact that extend is slow on large arrays/objects) so it is
dumped into a temp variable which is then assigned back to the cloned
object.
- This fixed DataTables/DataTables issue #213
- The `settings.aoPreSearchCols` array was being shared between every
table on the table (test using a simple:
$.fn.dataTableSettings[0].aoColumns ===
$.fn.dataTableSettings[1].aoColumns
) which meant that a column filter aplpied to one table would be
applied to all others.
- Fix is to deep copy the search model when adding a columns
- Fixes DataTables/DataTables issue #213
- It is far from uncommon to do `* { box-sizing: border-box; }` at the
top of your CSS these days, including in frameworks, but this could
cause DataTables a little bit of a problem when scrolling both
horizontally and vertically since the padding it adds to the header
linear element to allow it to scroll over the vertical scrollbar would
be folded into the width of the div linear, rather than added to it.
- Fix is to simply set the box-sizing for the linear. I've decided to do
this in Javascript rather than CSS since it is going to be needed
regardless of the CSS being used.
- This commit sees the number of built in type detection and sorting
functions increase to cover the most common cases of use of plug-ins
for DataTables (witht he exception of dates, for which a new first
class plug-in will be created). Specifically, DataTables now has built
in support for:
- Dates (Date.parse())
- Numeric sorting
- Formatted numbers sorting (including currency and thousands
seperators)
- Numbers wrapped in HTML (link tags for example)
- Formatted numbers in HTML
- HTML
Although the numeric sorting plug-ins could have been collapsed down to
just two plug-ins (rather than 4) I decided to do it this way to allow
type based filter formatters to be used with the formatted number types
to allow search for "100,000" or "100000" to match the same data. This
is not built in, but it is possible (and might be in future).
- The goal with these additional functions is to enhance the abilities
of DataTables out of the box to cover the most common cases for data
usage - DataTables is all about making data in tables more accessable
after all! The size cost is ~300 bytes for these additional functions
- In the case of filtering, if there is no filtering extension for the
column type, then the basic string based filter formatting is
performed (i.e. string is always the fallback - there can't be an
error because a function isn't there).
- This commit matches that behaviour in sorting. If you define a column
type as something for which there is no column sorting function, then
the string type will be used rather than resulting in a javascript
error.
- Automatic column type detection was a real weak point of v1.9- - it
did basically work, but if you then updated a row that didn't match
the current data type it would always end up as a string. A good
example of this is the ambiguous date "06-06-13" (is it dd-mm-yy or
mm-dd-yy?). If it was detected as dd-mm-yy and then you add '05-20-13'
to the column (or update an exisiting cell), the type would not match
the exisiting value that thus failover to a string.
- Type detection is now more rigorous, but still optimised (since it
has the potential to take up a significant amount of time). When a row
is added or updated, or a cell is updated, the exisiting type is
removed from the target column(s) and then, before sorting or
filtering, the _fnColumnTypes function checks to see if any column
needs to be type detected and do so if needed. This approach allows
multiple rows to be added (for example) before the draw is performed and
the type actually needs to be calculated.
- In future I'd like to have a 'data-ready' type event which will tell
DataTables, and any of its components that something wants to work with
the data in the table and it should prep the data. The counterpart would be
a 'data-invalid' flag which would be set on update, add etc so it knows
when an update is needed.
- The oApi option wasn't being attached correctly to either the settings
object or the instance, so plug-ins were breaking. This adds the alias
back in.
- If you were multi-column sorting, and didn't have shift depressed and
click on the first column in the sorting priority, the multi-column
sort would be retained. Non-shift click on any of the other columns
would reduce to a single column sort, so match here
- This is a fairly far reaching commit in that the DataTables.ext object
is updated to primarily use camelCase, just like the rest of the 1.10
API. The old notation is still available for compatiblity, but
deprecated.
- While working in this area, I've made a number of updates:
- .model.ext has been removed - that was redundant and not useful.
DataTables.ext is where the plug-ins for DataTables will live and
will be correctly publically documented as such.
- Type based actions (detection, sorting and filter) now live in a
`type` namespace to make it clear that they are type based.
- Internal references to .ext updated to use the new parameters. We
could use the old ones since they are fully backwards compatible,
but I'd rather set the standard by using the modern ones.
- JSDoc comments for .ext updated
- Extension examples updated
- When creating the new visiblity methods, I forgot to have the table do
a scroll draw to have the columns align correctly for the header and
body. This commit fixes that.
- Also update the column visiblity example to use jQuery events rather
than DOM0 events.
- Previously you'd need to use initComplete and columns.adjust() to take
account of the data that was loaded by Ajax. Now this will be done
automatically. It does mean a few more clock cycles, but I think
that's a tradeoff that is worth it.
- Alias the static methods to camelCase and hungarian varients:
- versionCheck()
- tables()
- isDataTable()
- Small updates in styling of the static functions
- I'd previously added columns().cache() which gets the cached
information about filtering or sorting, but this rounds the API off,
extending that also to rows and cells:
- rows().cache()
- row().cache()
- cells().cache()
- cell().cache()
Fix: I've removed the third entry in the aaSorting array, as the issue
was that after using order() that entry wasn't present. It was a bit
confusing as well, so it is now replaced with a property (_idx on the
aaSorting entries) which indicates the current sorting index (in
asSorting) - and this property is optional. If not given, it is looked
up or 0.
build and commit scripts to keep the src and build repos in sync.
Dev: Update the dataTables main file to the latest build which was
accedentally committed. Just a couple of little dev fixes - no API
changes.
- DataTables/DataTables is now going to be a build mirror of
DataTables/DataTableSrc which will host the source core. Scripts will
be used to build the generated files as there will be a number of
these now (examples, JS, CSS, web-site documentation etc).
- Previously there was columns().cells() and column().cells(), but these
were removed in f0a73ce due to the changes for the new top level
cell() and cells() selector methods.
- This commit effectively re-instates those functions but under the
`nodes()` name, matching the row and cell selection options. This is
for completeness in the API.
- order() and order.listener() added (to replace fnSort and
fnSortListener) from the old API.
- Note that the name `order` is selected to not conflict with the `sort`
method of the API object, which can be used to order the sort data
held in the collection.
- The `sort()` method is expanded over the abilities of fnSort to allow
multiple different forms of input (column + direction, 1D array, list
of 1D arrays or a 2D array).
- draw() and ajax.reload() can now have `false` passed as their first
(and currently only) parameter, which instructs DataTables to do a
'static' redraw (i.e. not to reset the pagination).
- Introducing several methods which will control the ajax aspects of
DataTables through the API:
- ajax.json() - get the last JSON returned from the server
- ajax.reload() - reload from JSON source
- ajax.url( [url] ) - get / set the Ajax URL
- ajax.url( url ).load() - load data from new URL after a set
- Note that this effectively replaces the old fnReloadAjax plug-in which
was quite popular.
- Not yet fully tested - further work required.
- Paging control methods for the new API:
- page() / page(n) - Get / set the current page
- page.info() - Get information about the table's paging state
- page.len() / page.len(n) - Get / set the page length
- Rewrite of core.page.js and core.length.js to be more space efficient.
The functionality is identical to before, but now compresses much
better (796 byte saving). The new paging API methods add only 614
bytes (compressed), so overall a saving of 182 bytes, with the new
functionality added by the new API.
- Start of draw methods for new API:
- draw() - Draw the table. Need this to test the new paging methods
since page() etc do not do a redraw themselves, you must call draw()
when you are ready for the table to be redrawn now.
- tables() is a table selector and iterator that most other API methods
will likely use.
- tables().nodes() gets the selected HTML table nodes.
- Documentation of these functions is rather incomplete. Not yet sure
how to fully document them. Currently thinking of having seperate
documentation, a bit like jQuery, which can be a lot more involved,
rather than building it fromt he doc comments which might get rather
long (they already are!).
- This commit introduces the new Api core, a 'class' which is a data
helper and DataTable control interface. Methods of this class are
designed to be chainable (although it is not manditory - some can
return boolean values if needed).
- The core data helper functions are present in this comment, although
not yet fully documented. That will come as the Api stablises and I'm
happy with the structure.
- There are no table control methods yet - coming soon.
- When server-side processing is enabled, fnInitComplete will now be
passed a second parameter, the json returned from the server for that
first draw, matching the Ajax data source with client-side processing
option.
- Full license available here: http://datatables.net/license_mit
- Note that this effectively makes the BSD and GPLv2 licenses that
DataTables is also available under redundant since the MIT is the most
relaxed of these licenses. At some point in the not too distant
future, it would make sense to remove these two licenses and have
DataTables available under only the MIT license.
used for the different data types very easily.
- Until now, if you want to use different data for the different data
types (I've called these orthogonal data in relations to DataTables)
you had to specify a function. That's fine, but it seems a rather
clumsy way of just pulling different data out of a source object based
on the type. This method allows the data types to be very easily
defined with an object, allowing the same rules as `render` normally
does (dotted object notation, array notation etc).
- For example:
$(document).ready(function() {
$('#example').dataTable( {
columns: [
{ data: null, render: {
_: 'a',
sort: 'c',
type: 'c',
filter: 'd'
} },
{ data: 'b' }
],
data: [
{ 'a': 1, 'b': 2, 'c': 4, 'd': '1' },
{ 'a': 3, 'b': 4, 'c': 3, 'd': '3' },
{ 'a': 5, 'b': 6, 'c': 2, 'd': '5' },
{ 'a': 7, 'b': 8, 'c': 1, 'd': 'allan' }
]
} );
} );
- Tabbing through a scrolling table the tabindex on the cloned header in
the body part of hte table meant that the browser would focus on those
elements. Fix is to remove the tab index from the clone nodes.
- DataTables 1.9 had 5 different parameters that controlled how Ajax
data was obtained, which with its own naming properties, often mapping
to the jQuery.ajax methods, or otherwise extending them. To hugely
simply and extend the Ajax functionality DataTables has, these five
parameters have now been deprecated and the funtionality provided by
them merged into the new `ajax` parameter.
- Deprecated properties:
- sAjaxSource
- fnServerData
- sAjaxDataProp
- sServerMethod
- fnServerParams
- Note that these parameters are still fully supported and can be used,
but for new projects, `ajax` should be used as they will eventually be
removed (likely DataTables v2 whenever that is, as they are too widely
used to be removed in v1.x).
- Added additional / missing tests for the deprecated properties to
ensure full backwards compatiblity
- The new `ajax` property is fully documented in the doc comments, but
as a summary it can take three forms:
- string - the url to get the data from (i.e. this is the new
sAjaxSource)
- object - maps directly to jQuery.ajax, allowing full control of the
Ajax call (provides the abilities of fnServerParams, sServerMethod,
sAjaxDataProp)
- function - a function so you can get the data your own way
(provides the abilities of fnServerData)
- Added unit tests for the new `ajax` property and doc comment examples
updated to use this property exclusively.
- jQuery migrate gives a warning about the use of `attr` rather than
`prop`. However, we should really just be using `val` here - much
easier.
- Thread: 13931
Removed: fnCookieCallback (cookieCallback) - This is now irrelevant since DataTables does not state save in cookies by default.
Removed: sCookiePrefix (cookiePrefix) - This is now irrelevant since DataTables does not state save in cookies by default.
Depreciated: iCookieDuration (cookieDuration) - Since DataTables does not use cookies for state saving by default the name of this parameter is now incorrect. The new parameter `stateDuration` should be used instead, although the old parameter is still supported. It will be removed in the next major version of DataTables.
Update - Performance / Memory: The functions that DataTables uses are not instance based, they are locally scoped, but they were included in the DataTable constructore, which meant that every time you create a new 'instance' of DataTables ($().dataTable()) it would create these functions in that scope again and again. That's completely pointless since we only need them once, so moving them outside the constructor helps both performance and memory (not huge, but very little helps!).
Backwards compatibility issues: The main goal here (other than to use camel-case notation!) is to preserve backwards compatibility. Unfortunately this isn't 100% possible:
- DataTable.defaults.columns has been renamed to be DataTable.defaults.column
- Otherwise it conflicts with aoColumns in the defaults.
Without doubt this is going to be a long process - for example the unit tests and examples need to be completely updated for this change. The JSDoc comments have been updated, so the site should take care of itself for the most part, when released.
In terms of implementation, it is important to note that I have not broken backwards compatibility here - the way it is does is that the current defaults are retained, and a camel-case to Hungarian mapping is automatically generated and then applied to the objects given by the end user. This adds around 0.5K to the size of DataTables, but writing the mapping manually would require at least 3K, and changing DataTables wholesale to camel-case would utterly break backwards compatibility. This is the least 'evil' way to accomplish this. It is important to note that this is a step along the roadmap for DataTables - come v2 Hungarian notation will likely be dropped completely.
One important note to make about this mapping is that if you use camel-case DataTables will copy the value from the camel-case properties to their Hungarian counterparts, so you will end up with additional properties on your source object. As I say, this appears to be to be the least 'evil' option, although still not perfect itself. The challenges of working with legacy software and installs...!
- With the introduction of the -pre method in DataTables 1.9, the -asc and -desc sorting functions became more or less redundant since they are simple comparisons (all of the complexity is now in the -pre formatting function). As such the call to the -asc / -desc method is overhead that really isn't needed, and this commit introduces a sort function that doesn't call the -asc / -desc methods, instead just doing the comparison itself. In tests, this relatively simple change leads to a performance improvement of around 15% in all browsers (it also has the side benefit of less operations, so IE8- will be able to sort larger tables before flagging up a slow script warning).
- We can't just remove the sorting method which will call -asc / -desc though since not all sorting plug-ins will have a -pre method. Therefore, for backwards compatiblity the old sort function (albeit updated for the changed variables) is retained. The backwards compatibality code adds around 300 bytes to the library, but this is an unaccounced change, so backwards compatiblity must be retained.
- The old sort method will be removed in v1.11. The -asc and -desc methods are now fully depricated.
- Altered the sorting method to flatten the aaSorting array since the introduction of aDataSort in v1.9 required an extra loop in several locations. The functionality is very useful, but the extra loop can be a bit messy and slightly hit performance, so it is now flattened to be a single array (with object information so it makes sense, rather htan array indexes!).
- Altered the order of sorting when building _aSortData since it was looking up the same variable smultiple times which really wasn't needed.
This is part of a small incremental changes plan for DataTables! There are still a huge number of things to improve in this area, but this is a nice clean up and a nice 15% sorting performance improvement to get us started :-).
Note: _fnColumnOrdering is left in place at the moment, although it may be updated as work progresses on 1.10 with regard to the increased use of column names.
Removed: fnRender - fnRender was depricated in 1.9 and is now being completely removed here. Its always been a bit messy and is now superseded by mRender. The main reason for this is that DataTables use to take an independent copy of the input data source object / array. This is a performance hit and it means we can't do any binding to external objects (for example it makes Knockout integration almost impossible).
Removed: bUseRendered - with fnRender being removed, bUseRendered is irrelevent
Updated: With fnRender being removed we no longer need to take an independent copy of the data source object / array (since DataTables itself isn't ever going to write to it now - fnRender did and the copy was included so we didn't inadvertantly change a developers data source object without them knowing about it. This is no longer a problem, and in fact having it use the same data source object is extremely useful in many cases.
Fix: Use jQuery html() and text() for HTML data to search method. Much tidier and copes with strict XHTML - downside is that it is a little slower if & is in a data string.
New: Static API method - fnIsDataTable - check if a TABLE node is a DataTable or not
New: Static API method - fnTables - get the DataTables that are initialised on the table (optionally limit to just the visible tables)
Examples update - Tabs and scrolling updated to use the new static fnTables method
Fix: Settings object model was missing the nScrollHead and nScrollFoot properties from the documentation
Fix: Table could conitnually expand when x-scrolling was enabled. This was partly addressed in 6776, but the fix was incomplete as it would still occur on Safari Mac (possibly other browsers as well). This fix is very closely related to 8332 (hence commiting together as they are interdependent). Now use padding right on the header/footer wrapper to provide the overflow scroll ability, but only add it when a scrollbar is present - otherwise the width gets added on and we get the forever expanding table.
Dev: Unit tests - New tests for scrolling to ensure 6776 and 8332 don't occur again
Fix: When using full numbers pagination in IE and clicking upon one of the numbers in the paging control, a Javascript error would occur due to trying to blur an element that was no longer in the DOM
Dev: Removed the "fast lookup" function for data get and set as they weren't really that useful in terms of speed and would require more code to be added to copy with the above change to the error handling for missing objects. Smaller code and virtually no difference in speed. Sold.
New: API: Underscore function updated to use fnGetData rather than its internal function calls. Although slightly more expensive in computation terms, it extends the capacibabites of the underscore function greatly, allowing TD nodes to be the result of the selector as well as TR nodes. So now you can get a column of data with something like: $('#example').dataTable()._('td:nth-child(4)') . Cool :-)
Dev: New internal function called _fnNodeToColumnIndex, adapted from fnGetPosition for reuse.
Fix: The calculation to detect if the scroll bar would be shown in IE6/7 was incorrect - it was calculating the height of the entire table, rather than just the body of the table (i.e. body + header + footer) which caused the "correct" for the scrollbar to be incorrectly applied to small tables.
