- Previously it was the domain of the filtering caller to update the
global filtering input element (fnFilter or the keypress handler
specifically), but in keeping with the drive towards modularity, it
should be the control itself that updates when needed.
- This is done by listening for the `filter` event from the table and
updating the display as needed. It is a touch less efficent since the
same value might be written as what is already there, but it reduces
code size and complexity.
- Ability to filter the table through the new API.
- This effectively replaces the fnFilter method of the old API.
- Note that one capability which has been removed from the old API is the
ability to not show the new filter on the filtering input elements. I
can't see any use for that feature to be honest, so it has been
dropped. The filtering inputs always show the global filter state now.
- Additionally, note that we've been forced to call this `search` here
rather than `filter` since there is a `filter` method for the API
collection instance. This might be revisted before release.
- The fnVisibleToColumnIndex and fnColumnIndexToVisible plug-in API
methods for the old API were very useful for transforming the visible
column index to the actual index, and the return. This adds that
capability to the new API.
- Recalculate the "ideal" column sizes for the table. Might want this
after a column visiblity change for example
- Replaces the fnAdjustColumnSizing method.
- This effectively replaces the old fnSetColumnVis method (a shim will
be put in place along with the shim for the rest of the old API). It
has added get abilities, and the option, like the rest of the new API
to work on multiple tables / columns with a single call depending on
the context and selector.
- row options for column selector
- Selectors (table, rows and columns) now held in a single file, sharing
structure. A more unified API is used, with row options also being
allow for columns, through the use of the second parameter for the
columns() method, which will effect how a column function can act upon
rows (for example, the order of the rows when getting data or nodes).
- Dev: tables() is no longer an iterator - using an `iterator()` method
with options which are suitable for the different types of iteration
the API needs.
- We use the cell nodes form the table body in a number of places, and
increasing with the new API, so rather than just storing a reference
to the hidden cells, we should just store a reference to all cells and
use them, cleaning up a number of other areas - in particular
_fnGetTdNodes which is no longer needed
- Should do something similar for _fnGetTrNodes
- Disabled sort classes for the moment as that can be rewritten to be
more efficient. It did use _fnGetTdNodes, but doesn't need to now.
- API fnSetColumnVis and fnUpdate will be broken at the moment, until
merged into the new API.
- rows().nodes() - Get the TR nodes for the selected rows
- rows().data() - Get the data for the selected rows
- columns().header() - Get the header cells for the selected columns
- This also introduces the `iterator` method to the API instance, which
can be used to loop over selected columns / rows, for the context
(tables), returning a flat array / API instance.
- Use variable aliases to allow better compression
- Replace body append code with jQuery code. Much simpiler, and only
a very small performance hit (around 1mS for a draw of 100 records).
- Remove the settings._iDisplayEnd parameter finally, using only
fnDisplayEnd() is needed, and the end point is calculated on-the-fly
when needed (which is not often and it is not expensive). This also
means that the internal method `_fnCalculateEnd` can be dropped
completely.
- Refactoring the empty cell in _fnDraw
- columns() and rows() introduced with their selector components. They
don't have any additional funtionality at this time other than just
being able to selector rows and columns (returning arrays of indexes),
but the principle is now in place, and the additional functions can be
fleshed out.
- Moving to use a work in process branch, as some aspects of DataTables
may break as this work continues, and certainly the files etc are all
in flux
- 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).
- Previously the master sort and filter functions would perform a draw,
but this was a bit redundant, complex and didn't allow multiple
changes to be queued up before a new draw was performed. The new API
will allow this ability, so we need to allow it in the core as well.
You can now do a sort, and it will be performed internally, but not
actually drawn until the redraw function is called. This makes a full
redraw much simpiler, and has the benefit that a standing redraw is
now relatively trivial since it is all performed in a single place.
- 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.
apply that.
- This is much faster than the previous method of using $(this).width()
since there is no longer an invalidation and getComputedStyle
calculation. It just uses the value that is available in style.width,
which might very well be empty (if the style attribute is used with a
width property defined is it not empty).
- This also improves accuracy since it is the original that is restored,
and not the calculated size.
- See http://datatables.net/forums/discussion/14811 for the discussion
for this change.
- Thanks to `krzycho` for the discussion and suggestions.
between table's being reinitialised, so calculating the scrollbar width
every time is a real hit on performance since it needs to manipulate the
DOM. This change ensures that the calculation is performed only once.
- 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.
- Attach an event handler to the window to resize the table. Note that
this isn't debounced - possibly it should be in future(?), but don't
want to add the additional code required if it isn't required. It
seems to function perfectly well for me!
- Unbind needs to unbind by the instance unique reference since there
might be multiple tables listening for the event.
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.
- As of jQuery 1.8 `andSelf` was deprecated in favour of `andBack`.
`andBack` was not available in jQuery <1.8, and I don't want to make
1.8 a requirement yet, so a small workaround requiring two unbind
calls is used to avoid calling `andSelf` or `andBack`.
- 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
object notation.
- Previously if you had an object key that contained a period, it
wouldn't work with `data` or `render` (or rather it would need a
function call to do it manually), since a split was being done on the
periods to reconstruct the Javascript object property chain. Now it is
possible to escape a period, allowing it to be included in the
property name read / set.
- Example:
$('#example').dataTable( {
columns: [
{ data: 'a' },
{ data: 'b\\.c' }
],
data: [
{ 'a': 1, 'b.c': 2 },
{ 'a': 3, 'b.c': 4 },
{ 'a': 5, 'b.c': 6 },
{ 'a': 7, 'b.c': 8 }
]
} );
- As part of completing the planning development for reading data, I've
added support for calling functions from the string defined in `data`
and `render` column options. So you can now do something like:
`render: 'name()'` rather than needing to use an anon function and
calling name() in that. This is useful for cases where you want to
give DataTables an array of Javascript instances, rather than objects
or arrays (see example below). It also fully supports the continuation
of the dotted notation DataTables supports, so you could use
`name().first` if `name()` returns an object. Again to make it easier
than needed to define a function.
- Documentation for `data` and `render` updated to reflect this
abilities
- Unit tests for this still to come
- There is one backwards incompatiblity that should be noted - although
I think this is a real edge case and I just can't see it being an
issue. If before, you had `data:null` without `render` or
`defaultContent` specified, DataTables would have output an empty
cell. Now it will output the original data source object. Can't see
this being an issue since, why would you have a column empty cells? If
this is an issue, then you simply need to add `defaultContent:''` now.
- Example use case, using Javascript instances:
$(document).ready(function() {
var z = function (i) {
this.a = function (set) {
if ( set ) {
return this;
}
return i+'-0';
};
this.b = function (set) {
if ( set ) {
return this;
}
return i+'-1';
};
this.c = function (set) {
if ( set ) {
return this;
}
return i+'-2';
};
this.d = function (set) {
if ( set ) {
return this;
}
return i+'-3';
};
this.e = function (set) {
if ( set ) {
return this;
}
return {
q: i+'-4q',
w: i+'-4w'
};
};
};
window.dataset = [
new z(0),
new z(1),
new z(2),
new z(3),
new z(4),
new z(5)
];
$('#example').dataTable( {
columns: [
{ data: null, /*render: 'a()'*/ },
{ data: 'b()' },
{ data: 'c' },
{ data: 'd()' },
{ data: 'e().q' }
],
data: dataset
} );
} );
- Typically I think setting bDestroy or bRetrieve as default true is a
bad idea as it could lead to more processing of tables than is needed
by mistake, but if set the defaults should be acted upon.
- These are slightly different to the other defaults since the settings
object hasn't been expanded by the point they are checked, so need to
manually check the values.
- When scrolling is enabled, the scrollbar can be placed on the right or
the left of the scrolling container by the browser for rtl layout (of
the current browsers, only Safari appears to place it on the right) -
when placed on the left the padding adjustment that DataTables makes
for the scrollbar area was added to the wrong side.
- To cope with this, the browser compat method (moved to the compat
file) will check for the position of the scrollbar and set a flag so
the scroll draw can adjust the position as needed.
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...!
simplify conditions:
!A || (A && (B || C)
really is the same as:
!A || (true && (B || C))
which simplifies to:
!A || (B || C)
which simplifies to:
!A || B || C
