- 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.
