- Because of the manipulation of the initalisation object initialisation
of multiple tables with a single jQuery call (i.e.
`$('.dataTable').dataTable();`) was broken since the second table
would see the modified init object. Need to take a coopy of the object
before entering that state.
- This could probably do with a bit of a clean up sometime...
- The displayLength option is poorly named, particularly with the new
API refering to it as the page length (page.len()) so, using the new
translation option to allow backwards compatiblity while using new
parameter names, I've updated this parameter's name and its
documentation.
- Renaming in keeping with the new terminology
- Updating example which uses it (main documentation still to be
written)
- Backwards compatible with a bit of logic to check if the old version
is being passed in
- Decided that it would be better to provide the new API by having
plug-ins extend it directly, rather than providing their own API.
Using the plugin() method it was possible to get a plug-in insta,ce
for example TableTools, but the way it should work is that TableTools
would provide a tabletools() API method, registering it as an
extension to the DataTables API objects. Further more, TableTools
should provide methods such as row().select() etc, extending the
current API rather than doing its own thing which the plugin() methods
prompted.
- No backwards compatiblity issues here as the plugin() code hasn't
shipped as a release.
- I added a static DataTable.on() method previously in the 1.10
development for a single event called `construct` which would tell us
when a table was constructed. But I've realise that since the events
that DataTables' triggers bubble up through the document, that effect
can already be achieved:
- Use:
- $(document).on( 'init.dt', function ( e, settings ) { } );
- Rather than:
- $.fn.dataTable.on( 'construct', function ( settings ) { } );
- No backwards compatiblity issues as the DataTable.on code was never
shipped, its dev code only
- Previously DataTables would only show an error message if there was a
JSON parsing error. However, if there was any other kind of error,
such as a 404, it would just silently swallow the error. THink its
best to show an error and a tech note.
- This is a breaking backwards incompatible change - please be aware of
this!
- DataTables fires custom events such as `draw` etc, but these events
were in no way identifyable as eminating from DataTables rather than
some other component, which can cause confusion and difficulty
resolving bugs.
- As such, all DataTables events are now fired with the `dt` namespace -
this means if you are currently using events, you must update your
code to also use the .dt namespace. If you are already using
namespaces, that's great, you can continue to do so as jQuery allows
multiple namespaces, but you must still use the .dt namespace.
- This is a breaking change because the old behaviour was incorrect -
i.e. this was a bug to be fixed, hence why we haven't gone through a
deprecation cycle. The old events weren't well documented (only in the
JSDoc generated docs and a few of my forum posts), whereas in 1.10
they will form a key part of the documentation. As such, now is the
time to get this right. This will be documented clearly in the upgrade
notes.
- Discussion on this topic here:
https://github.com/DataTables/DataTables/issues/245
- columns().cache() should check for the parameter 'search' for naming
consistency
- Plural error on column().nodes()
- Change column.index() fromIndex/toIndex to fromData/toData - its an
index be it data or visible, so the old method was meaningless
- The columns() methods have header() and footer() children to get the
header and footer cells for the columns. For naming consistency the
table() methods should be named likewise
- to$ - Convert the result set to a jQuery object. Compliment to the
toArray method. This is mainly useful when working with the node() and
nodes() methods.
- toJQuery - Alias of to$
- join - Array join method
- With the new API the filter() and sort() methods already have meaning
(the array methods built into Javascript) so the methods for filtering
and sorting in the API are called search() and order() respectively.
However, the intialisation parameters and events in DataTables use a
mix of filter, search, sort and order in their terminology so this
commit harmonises on just search and order, updating where
appropriate.
- There are a number of incompatible changes if you are already using
the new options in 1.10, but no incompatible changes to the latest
release (1.9.4). 1.10 changes:
- Server-side processing, the new parameters sent have been updated
to refelect the new terminology
- The Ext object likewise has been updated
- Default with the old options and padding int he old options will still
work as before, compatiblity functions have been added to provide
mapping. If both are provided the new parameter value will take
president.
- The change is primarily around `sort` since that was reasonably
consistent in its terminology for the initlaisation parameters before.
column index referencing of the cells.
- Previously a colspan in a footer cell would cause index misalignment -
for example if you had a table of 6 columns with two in the footer
(one colspan=5) the fotoer cells would be assigned to the first two
columns in the table, breaking column index order. Now a cell can be
used over multiple columns. This allows column().footer() to always
reflect the cell that belongs to that column (possibly sharing it with
other columns).
- Note that the footer will only use cells from the first row in the
footer. If there is more than one row, use table().foot() to access
the TFoot element and then manipulate it as needed.
- The fix here is to set the box sizing for the table and its cells to
be content-box sizing to allow the column width calculations to occur
correctly - 17932
- Packagist requires that packages use only lowercase letters in their
name (although the composer spec says nothing about this), so in order
to make DataTables usable with packagist we need to change the name
slightly.
display
- In the examples we want to show the following information to help
developers to get to grips with DataTables more readily:
- Init javascript code
- HTML used for the table
- Additional CSS used
- Ajax loaded data
- List of the libraries files loaded in the example
- All but the last point is complete, a bit of styling and information
text.
option
- By passing in no parameters to the search API methods we can get the
current search value - for example:
$('#example').DataTable().search();
- This is to round of the API as the order() method already has a get
option as to the paging information
- Variables and functions which are to be private in DataTables, but
available across all files have a single leading underscore.
- Variables and functions which are to be private in a single file have
two underscores (but no self executing function to restrict scope as
that will just take extra space).
- Externally exposed functions and JSHint globals list updated
- 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
styling
- Note that I've included the bootstrap and Foundation integration files
in the resources folder. In future these files will be on the CDN, but
that isn't up and running yet...
- 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.
- A numebr of support requests are about why the layout immediately
after a DataTable looks wrong, and its usually because of the floats
used by info / paging, so we self clear the wrapper around the
DataTable controls
- Updating the build process to introduce the example builder to convert
the XML example files into HTML files. This process is performed for a
number of reasons:
- Much more maintainable - links automatically updated
- Add / remove examples easier
- Modify page styling easier
- Examples can be directly integrated into web-site since they are
transformed by template
- Common data sharing
- Note that the work on the new example build process is not complete in
this commit, there are still a few things to do! css, media paths and
completing the templates.
- 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()).
- It is quite common to have a row selection styling in DataTables, so
it makes sense to built this ability directly into the core CSS. It
doesn't add too much extra weight, but it would be a huge pain for
developers to do themselves and also it means I can reuse it in
TableTools / Editor.
- 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.
