- 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.
- Previously the sort classes were being applied at the end of the
_fnSort function, with a callback for when using deferred rendering
and server-side processing (that was a performance hit for deferred
rendering thinging about it, since it hapened twice).
- Now a single callback is used so sorting classes are applied only
after the draw is done.
- Rendering functions can now be provided for the header cells in the
table, which will format HTML in the cells (note only the cells that
are identified as the 'control' cell for the column have the renderer
applied) and apply any classes needed (thus the renderers should
listen for the 'sort' event).
- This is done to provide integration options for other frameworks and
advanced styling controls. For example, FontAwesome could now easily
be used to style a header with sorting icons sourced from the font.
- jQuery UI header rendering has been seperated out into its own
renderer which is activated by the bJQueryUI initialisation option.
This, along with the whole of DataTables' jQuery UI ThemeRoller
support will be moved into a plug-in in 1.11 (it is very tempting make
that change now, but one major version for the decprecated option is
correct I think). This is the last part of the jQuery UI integration
that needed to be decoupled from the DataTables core - it can now all
be provided by plug-ins.
- This fixed issue #153
- Renderers still be to documented.
- Setting `box-sizing: border-box;` for table cells would cause
DataTables to incorrectly calculate the size of the element when
applying the scrolling draw. This is because jQuery's $().width()
always returns the content width (taking into account box-sizing).
- One possible fix was to detect the box model used and switch between
width() and outerWidth(), but a much better fix is to use
$().css('width') as this does take into account the box-model and
allows DataTables to draw the scrolling table columns correctly,
regardless of the box model. It should actually also improve
performance, since jQuery doesn't need to look the box model up
itself.
- This fixes issue #157
can return only objects now.
- The new `ajax` option for 1.10 did previously allow both arrays of
objects with name value pairs and objects, however, this change
removes the option of using arrays of objects to try and simplify
things. One of the most common questions in the forums is about name
value pair objects, so this sidesteps that.
- The big benefit of doing this is that the data passed into `data()` is
now very easy to manipulate. Rather than needing to loop over the
array, you can just modify the parameter you want.
- It also allows an object to be passed back from the function,
manipulated as desired. For example it is now super easy to nest the
DataTables parameters in a sub-object:
$('#example').dataTable( {
'processing': true,
'serverSide': true,
'ajax': {
'url': '../server_side/scripts/server_processing.php',
'data': function ( data ) {
return { 'myprop': data };
}
}
} );
This fixed issue #124.
- The parameters submitted to the server and those expected back are
currently left as is. They will be updated to be camelCase at some
point, but not yet sure if that will be for 1.10 or 1.11.
- Styles weren't being correctly applied becuase the selector was
`table.dataTable.display.stripe` rather than just
`table.dataTable.display` for the "correction" styles when multiple
styles are enabled.
- Reducing the complexity of how the global filter is applied in
DataTables by removing the `asDataSearch` internal settings array
which held information about each row's filtering data. This is now
held on a per row basis in `_sFilterRow` which is built only when the
data is invalidated. This should result in a small performance
improvement as well as simplifying and reducing the code.
- Filtering is now implemented by simply checking the built regex
against the `_sFilterRow` parameter for the display array (with a
reset to master, as there was before, if needed)
- This also fixes an indexing issue that was present in the filtering in
1.10.dev only
for the header cells (matching the standard case, in addition to the
ui-state-default class for styling).
- This allows the developer to add styling information based on the
sorting state of the cell.
- This fixed issue #17
- When using _pluck with deferred rendering, there were a number of
errors due to the nTr element being undefined (that's what deferred
rendering is all about of course). So the logic to check that pluck
can pluck from a source object needs ot be added.
object
- Previously to modify the class names that DataTables uses for its
components you has to use $.fn.dataTable.ext.oStdClasses. Now you can
use the `classes` initialisation option which will extend the classes
object of the DataTable.
- This fixes issue #180.
- Building on the new ability of DataTables to work with element
attributes as data sources for sorting and filtering, this commit adds
auto-detection of the attributes 'data-sort' and 'data-filter' in DOM
sourced tables.
- The first row in the table is used for this auto-detection and the
built mData object assigned only when it is found to be the default
for the column (i.e. the column index). So any custom value is
retained and thus if you want to use a custom value you need to build
the attribute querying object manually (I think the majority of uses
will not need this!).
source orthogonal data for filtering, sorting and type detection data.
- In HTML5 the data-* attributes can be used to add semantic data to an
HTML page, which a user will not see, but the scripts on the page can
interact with. DataTables now has the ability to use these attributes
(actually any attribute can be used) as a data source. Previously DOM
sourced tables always used just the content of the cells for all data
interaction, but this can provide advanced controls in just the same
way that Javascript / Ajax sourced data can do orthogonal data in
DataTables.
- A typical use case is to provide numeric sorting information for
complex formatted dates that the browser doesn't understand with
Date.prase().
- The SCSS stylesheet is now feature complete, and the
jquery.dataTables.css file found in the repo is now directly generated
from that SCSS file. The SCSS online compiler will run the stylesheet:
http://sass-lang.com/try.html .
New: SCSS base stylesheet with variables for colours
New: Pagination styling
- DataTables now has the ability to selectively enable different style
types by applying different class names to the host table. The options
supported are:
- hover - show a hover effect over rows
- stripe - show odd/even row stripes
- row-border - show a vertical border between rows
- cell-border - show a border around all four sides of a row (only
one of row-border or cell-border should be used)
- sort-column - highlighting of the sorting column.
I will be adding another class along the lines of `display` which will
enable 'hover, stripe, row-border and sort-column' (although this is
not yet implemented).
The reason for doing this is to encorage developers to style their
DataTables more their own way, but making it easier to enable the
features they want.
- To that end, the DataTables stylesheet will be generated from a SCSS
template in future. The SCSS template is included in this comment
(although the generated stylesheet is not yet committed). This allows
colours to be changed which a trivial amount of effort, while still
being able to get row highlighting etc, thanks to SCSS's colour
functions.
- Pagination styles have been updated to fit in with the new styling of
the DataTable.
flexible and simple to actually use.
New: Two additional built-in pagination types: 'simple_numbers' and
'full'.
Update: 'two_buttons' type pagination (previous default) renamed to
'simple'.
New: Default pagination type is now 'simple_numbers'.
New: Introducing renderers to DataTables (something that will play an
important part moving forward).
New: Simplified pagination button classes to simply:
* "sPageButton": "paginate_button"
* "sPageButtonActive": "current"
* "sPageButtonDisabled": "disabled"
- The basis for this commit is a restructuring of how pagination
plug-ins work in DataTables, whereby the pagination plug-in simply
returns an array of button types which should be shown. These are then
actually displayed by the renderer. This seperates the logic for which
buttons to show from the display logic, making it much easier, both to
customise which buttons will be shown, and for integration plug-ins to
customise the display of the buttons (since they don't need to
replicate the button calculation logic). This change allows us to
introduce two new built-in pagination types to DataTables with minimal
size cost. Indeed, this change as a whole reduces the compressed
DataTables size by 2.5K (additional functionality, simpler and smaller
- what's not to like!?).
- Pagination button classes in DataTables were a mess before, with
different classes used for the two built in types, with the additional
complexity of only one of the defined class options being used, rather
than concatinating the classes based on the type. This was bonkers and
a barrier to new users styling the form as they wanted. Reducing to
just three class options, and having the active and disabled options
added to the base class makes it MUCH simpiler. This could hit
backwards compatiblity for those who had styled the mad old style, but
it would have been crazy to keep it while writing the rest.
- If a row has been invalidated, then we need to perform a full
re-filter, so we need to pass this invalidation information back up
from the invalidation checker to the filtering functions.
- If the number of columns in the table were reduced, then the column
filter state that was saved would be incorrect since it would define
more columns that there were. Equally sorting could potentially be
done on a column that no longer exists.
- There were a few work around in the code already to try and address
this a bit, bit not satisfactorily as seen by thread 14114. The real
issue was that the columns were being detected after the state was
being loaded - ideally we want to load state after the columns had
been detected and throw away the state saved if the columns did not
match since the table might be entirly different.
- This is done by a little bit of reordering in the constructor, and
actually simplifies the code a bit.
- I had inadvertantly broken the ability to set an initial draw position
using `displayStart` or state saving with the small refactoring of
_fnDraw and fnDisplayEnd. fnDisplayEnd must be called with
settings._iDisplayStart set, which is now done simply by changing the
order of calling a little.
property
- Extending the funtionality of DT_RowId and DT_RowClass, this commit
adds DT_RowData which utalises jQuery's `$().data()` method to set
HTML5 data-* attributes, which can be useful for additional meta data.
- This is some what complimentary to using objects as the data source
where you could just use row().data() to get the data, but this is
effectively an orthogonal way of getting the data and might be useful
for existing Javascript libraries.
- It should be noted that the data-sort and data-filter work I'll be
doing for v1.10 shortly will not interact with this method, that will
be DOM sourced data only, while this is Ajax / Javascript based only.
However, if you do want to use data from this source for filtering /
sorting, its easy to do with `data` - `data: 'DT_RowData.sort'` for
example.
- This fixes issue #45.
- Had split the row details out into its own file a little while back,
since it is 100% self contained now, but hadn't committed the file!
Here is it now.
errors
- A lot of posts in the forum are questions such as "what does the
invalid JSON response" error mean, or "how to fix the unknown
requested parameter error". To address these, rather than having them
answered individually in the forum, I'm going to write a series of
technical notes for DataTables (getting started, how to use columns
etc) and as part of those, each error that DataTables can fire off
will have a technical note explaining in deatil what the error means.
- Example:
DataTables warning: table id=example - Invalid JSON response. For
more information about this error, please see
http://datatables.net/tn/1
- This commit puts the required logic in place. The technical notes
don't exist yet, but they will soon. They will be:
1 - Invalid JSON response
2 - Non-table node initialisation ({this.nodeName})
3 - Cannot reinitialise DataTable
4 - Requested unknown parameter {param} for row {idx}
5 - Unknown paging action: {action}
6 - Possible column misalignment
- The table cannot fit into the current element which
will cause column
- This also has the advantage that the errors in the DataTables code can
be a little smaller. Around 500 bytes saved.
- This fixes issue #173
non-array element
- If found to be something other than an array, it will treat it as if
it were an array with a single element in it, of the value given.
- With the new API that is being introduced in v1.10, the old API
(fnUpdate, fnAddData etc) is being deprecated and retired. It is now a
shim layer calling through the new API, rather than duplicating the
logic of the calls, but is still provided for backwards compatiblity.
- It is _strongly_ recommended that you start to use the new API from
this point in - very certainly for new projects.
- The api() method, is not deprecated, it is new in 1.10 and provides a
way to get access to a DataTables API instance from the jQuery host
object, if the table is initlaised with `dataTable()` (rather than
`DataTable()` which does give you the API instance. It has a single
option which is used by the old API's shim layer to allow it to use
the iApiIndex option to get the context to be used.
- There were two functions called _fnGetRowData, which were conflicting
- The $().map doesn't execute with the scope of the element, need to
pass the element through to the get data function correctly.
- The row()/rows() methods have index methods, so it makes sense that
the column(s) and cell(s) methods also have index methods to get the
raw information out of the table. Rather than shying away from the
indexes in 1.10, as has been done with the pervious versions of
DataTables, 1.10 will embrase them as first class citizens.
- New methods:
- columns().index()
- column().index()
- cells().index()
- cell().index()
- It is possible at the moment to use rows().data() to get the data for
the table, you can use rows().data( { order: 'index' } ); to get the
data in index order - I suspect a reasonably common use when working
with the data set (at least, I use it that way!) and its a but clumsy
to write that way, particularly compared to the old fnGetData method.
So the new data() method is a short cut for `rows().data( { order:
'index' } ).flatten()` to get the data set for the host table(s).
- For consistency and completeness, the cell() and cells() methods now
accept their own cell selector option (rather than just rows and
columns) which is a jQuery selector, or no selector at all for all
cells. Additionally it allows an options object to be passed in, to
allow configuraiton of the order of data etc.
- The cells() method now has these calling options:
- cells() - all cells
- cells( opts ) - option configuration
- cells( selector ) - cell selector
- cells( selector, opts ) - cell selector + options
- cells( rowSelector, columnSelector ) - row + column selector
- cells( rowSelector, columnSelector, opts ) - row + column selector +
opttions
- The cell() method as the same signature.
with newly added rows
- Looking at fnAddData, and about to replace it, I realised that
fnAddData returned the indexes of the newly added row while the new
methods didn't. It makes sense for row.add() to return a row()
extended object with the newly added rows so row().node() etc can be
used. Also the indexes are in the inst, so that information is also
available. Likewise is done for its plural counterpart.
- Did consider creating an `augment` static method for the API, and
might yet do this, but this is the only place to use it at the moment.
Possibly it might be useful for plug-ins, but before adding, lets see
how the new API is used.
with plurality
- There are four groupings of plural / singular methods in the new API:
table(s), row(s), column(s) and cell(s). We need to provide similar
methods for each, often leading to code duplication. To help reduce
this code duplication I've created a new `registerPlural` method which
allows both the singular and plural to be derived from a single
function automatically. The plural form is given and wrapped up by a
container function which extracts a singular return.
- Note that not all singular methods can use this approach, for example
row().data() provides extra functionality over rows().data() in that
it can be used as a setter as well as getter.
- To round off the API, this commit adds a column() method, for working
with a single column, as with row/rows, cell/cells and table/tables.
- New methods:
- column() - Column selector
- column().data() - Get column data
- column().header() - Get the column header cell
- column().visible( set ) - Get / set the column visiblity
- column().order( dir ) - Order the table by this column
- Note that I haven't implemented column().search() yet as I'm sure
there must be a better way of dealing with the singular functions...
Need to look at the four groups a bit more before this (and then the
API :-) ) is finalised
- The columns().data() method was flattening the returned array. While
possibly okay on its own, that doesn't match the behaviour of how
rows().data() works, where each row is an entry in the array, rather
than the array being flattened. As such I've changed columns().data()
to work work in the say way, for each column you select, you get an
entry in the api instance - an array with the data for the that
column.
- To allow for hte fact that some may want to work with the flattened
data, I've added a `flatten()` method to the instance base, which is
basically a shortcut call to `reduce`.
- Now that we have the cells() / cell() methods, with the ability to
select based on column and row, and the ability to get the whole row
or column cells, the TD get methods on row / rows / columns were
redundant and I think should be removed for berevity. It could also
get confusing with the chaining since there are nested and top level
methods with the same name.
- Removed:
- rows().cells()
- row().cells()
- columns().cells()
- New API methods:
- cell().invalidate() - Invalidate a single cell
- cells().invalidate() - Invalidate multiple cells
- Note that the invalidation is actually row based, rather than cell
based - i.e. the whole row is invalidated. This may change in future
versions of DataTables, but I'm concerned that it would add a lot of
code for little enhancement.
- New API methods:
- cells( rowSelector, columnSelector, opts ) - Cell selector
- cells( ... ).nodes() - Get the nodes for the selected cells
- cells( ... ).data() - Get the data for the selected cells
- cell( rowSelector, columnSelector, opts ) - Single cell selector
- cell( ... ).node() - Get the cell node
- cell( ... ).data() - Get the cell data
- There was a bug in `_selector_first` whereby it wasn't correctly
reducing the set - was gatting away with it before, because it was
reducing to a single element array, which has a toString() method
which allowed it to appear to work for integers.
- New API methods:
- table() - select a single table
- table().node() - get the table node for the table
- To be honest, these methods are not likely to be used particuarly
often, so I think they are fairly low priority, but they could provide
useful, and it is a public way to get the table node.
- New API methods:
- rows().invalidate() - Invalidate the matched rows
- row().invalidate() - Invalidate the matched row
- row().data( set ) - Set the data to use for the matched row
- This involves building upon the invalidation work done in the last few
commits and creating an invalidation function. This new function will
mark the cached data as invalid for re-reading by the sort and
filtering methods (this will need to be abstracted into modules in
1.11, but there is no infrastructure for that yet - that's what 1.11
is all about). Additionally the invalidation method will update either
the data held by DataTables (read from the DOM), or update the DOM if
the data source was not the DOM. A flag allows an override to state
the direction, although I think that generally speaking you might not
want to use the override (you might nuke parts of your data source
object if you read from the dom for example).
- Like sorting, for the new API we need to be able to invalidate data
held for filtering in a fairly simple manner (it could be done before,
but it was messy, see fnUpdate - you need to call the methods in the
parent function, rather than just invalidating). This commit adds that
ability to DataTables.
- Performance improvements:
- The big one is that filtering data is only obtained and formatted
when invalidated, rather than every full filter now.
- Regular expressions for newline and HTML matching are variables,
rather than redefined on every call.
- DIV for reading text version of an HTML formatted string is a
variable, rather than being recreated on every call.
- Type based formatters have been moved into the extension API ('string'
and 'html'). They can be overridden there if wanted. Allows
simplication of the call for the formatter.
- Fixes issue #158 as part of the refactoring.
- Smaller by 22 bytes (compressed)... Likely once invalidation is fully
implemented that will be swallowed up...
- Refactoring _fnSortingClasses to be more efficient in how it operates
and to compress better. This is done by looping first over the
elements to have their classes removed, and then looping over only
those to have them added. Previous all columns were operated upon.
Also using _pluck and that fact that all cells fromt he tbody are
stored makes the code much smaller, more readable and compressable.
Only 0.5KiB saved in the refactor, but every little helps...
- Restored column sorting classes functionality that had been disabled
earlier in the 1.10 development sequence.
- Think this code was in DataTables 1.0 and has been relatively
untouched! A refactor allows it to be more readable and smaller when
compressed (about 450 bytes saved)
- invalidation is going to play an important part in the new API, with
the ability to invalid the cached data for sorting, filtering, display
etc so we need to be able tos upport this in the core.
- In fairness the sorting didn't actually need invalidation because it
would always get data on every sort, which is bad for performance -
proper invalidation and caching will resolve this. Which is what has
been implemented here.
- I had expected (hoped) to be able to save a bit of space in the
refactor, but only aorund 100 bytes (compressed) saved, which will
probably be lost when the invalidation is fully implemented in the
API. Still, better performance, tidier code, and no extra space...
Fix: Sorting classes now show multi column sorting when a column is
defined to sort over multiple columns (sortData). Previously it would
only show the first column.
- Two new methods for the new API to allow new data (rows) to be added
to the table.
- row.add() - Add a single row to the table. object, array, jQuery
object or TR node can be passed in.
- rows.add() - Add one or more rows to the table from a source array.
An array or jQuery object must be passed in, containing objects,
arrays, or TR nodes (or any combination thereof).
- Should be noted that this is iterated over all tables in the current
API context, so care should be taken when adding a node to multiple
tables, since it will be moved between them. Equally, when adding
data, the original object reference is retained, so changing it in one
table will change it in all!
- These two methods effectively replace fnAddData from the old API.
fnAddData had a few issues with distingusihing a multiple row add and
a single row add, since arrays could be used for both (indeed, it
simply couldn't cope with something like using a single integer as
reference for a data object, which can now be done in 1.10). The two
new methods sidestep this problem by providing one method for multiple
row add, and another for single row add - the developer needs to know
that the plural has meaning here!
Only call once each to check to see sort ascending / sort descending is is active. (And only check for the descending class if we didn't find the ascending class)
Should also lead to smaller minified code.
- Addition of a destroy method for the new API, effectively replacing
fnDestroy from the old API.
- The functionality is identical to fnDestroy, but it has been
refactored to make better use of jQuery and allow for better
compression (should be 1/4 - 1/2 KiB saved)
- $ - perform a jQuery selector on the nodes in the table (matching the
$ method from the old API).
- clear - clear the table completely (replaces fnClearTable).
- settings - get an array of the settings objects for the tables used in
the API instance.
- on - jQuery event listener proxy. Use for table specific events
('draw', 'xhr' etc).
- one - jQuery event listener proxy (single event).
- off - jQuery event unlistener proxy.
- Showing and hiding details about a row in a child row is very useful
and proven to be a popular part of DataTables. This commit provides
that ability in the new API and extends it. It also fully modularises
the child rows aspects, so it could be removed from the core without
effecting any other aspects (it may be moved into a seperate file in
future).
- This will effectively replace fnOpen, fnClose and fnIsOpen
- Added methods:
- row( selector, opts ).child()
- row( selector, opts ).child( str, class )
- row( selector, opts ).child( str, class ).show()
- row( selector, opts ).child( str, class ).hide()
- row( selector, opts ).child.show()
- row( selector, opts ).child.hide()
- row( selector, opts ).child.isShown()
- Note that unlike the old API you need to specify the data first, and
then use the show() method to show the child row. This allows the
details rows to be configured before they are actually shown.
- Additionally multiple child rows can be attached to a parent (pass
`str` (from above) as an array to use this feature. API plug-ins could
use this ability to show fully nested tables.
- Not just a string can be passed in now, but also a TR node which will
actually be used (rather than put into a nested row), any other type
of node (which will be inserted into a wrapper row/cell) or a jQuery
object.
- The rows() method allows operations on multiple rows with a single
call, this new singualr option, `row()` performs operations on a
single row, allowing fine grain control and easy access to certain
aspects. For example. `rows().data()` will return an array of data
objects, even if there is only one row as a result of the selector,
while `row().data()` will return the data object directly.
- Impletemented thus far:
- row()
- row().node()
- row().cells()
- row().data() - get only as of yet
- row().index()
- row().remove()
- 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
- 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.
Simplify and improve performance
- Only check once for the presence of any sorting class instead of checking for the 3 individual classes
- Use lastIndexOf(str, 0) instead of indexOf
http://jsperf.com/rep-reg-string/4
Use greedy match regex for replacements
Otherwise, you could have:
"_START_ of _TOTAL_, showing _START_ to _END_"
replaced as:
"1 of 5, showing _START_ to 3"
Tweaks to improve performance
Cache nodes
Restructure to use nextSibling rather than childNodes
(small increase in file size, but may be a slight decrease in minified size)
