Improved last page calculation when page size is changed on last page.
e.g. Suppose there are total 12 records and page size is set to 5 records/page. Go to last page, which should be 3, change page size to 10. Page#2 should be selected and it should show 2 records on it.
* This reverts the last commit which documented the old behaviour.
Thinking again about it, if you want to modify the rendered data use
`$(cell).html()`.
* When `dt-init columns.data` / `dt-init columns.render` resolve to a
function, that function is executed. Previously this execution was in
the global scope, but in order to be able to use an instance as a data
source for the row (something I wanted as part of 1.10) we need to
execute the function with the instance's scope. A simple `call()` does
this.
* I could add a check to see if the `rowData` is a plain object or not,
but that would add significant overhead to the processing, and this
particular part of the code needs to be very fast. Additionally, I
think it is unlikely that any one was dependant on this being executed
in global scope, so the change is made.
* This fixes DataTables/DataTables #368.
* 1.10.0 had issues when searching for boolean data as the search
extension methods were checking for empty data, but if found they were
using `''` as the term to filter. It should more accurately just use
the given data.
* Relates, the `_empty()` method was considering `false` to be empty,
but not `true`. Both are now considered to be empty.
* `dt-api state()` - get the last saved state
* `dt-api state.loaded()` - get the state that was loaded when the table
was created
* `dt-api state.save()` - trigger a state save
* `dt-api state.clear()` - clear the saved state
* Fix is to convert from hungarian notation to camelCase in a loop for
the array
New: State staving object structure is now full documentated
* The structure has been altered to be camelCase notation like the rest
of the 1.10 API. State loaded from older versions of DataTables will
be silently ignored
* The native `forEach` is suprisingly slow. I had assumed that it would
be faster that a for loop, but it appears that due to the function
execution it is actually much slower. A simple for loop is much better
for performance and we loose nothing since hte API instance is array
like.
* This fixes DataTables/DataTables #364
* It appears that if you have a reference to a DOM node, but that DOM
node is overwritten by use of innerHTML, the reference is destroyed
and you cannot use the referenced DOM node any more.
* This became apparent from using Editor's inline editing mode, where in
IE the inline edit would work only once. No other browser has this
issue but it is in IE7-DC1.
* The workaround is to remove the child nodes first. not ideal at all,
but it does work.
* Searching the internet I didn't find much about this so I've opened an
issue on the IE connect site:
https://connect.microsoft.com/IE/content/content.aspx?ContentID=29582
* DataTables uses custom jQuery events which propagate up through the
DOM, with the custom event being triggered on the table node. Ideally
I'd like to change the event handling to use $().triggerHandler() to
avoid this issue, but as discussed in issue #245 that would mean that
delegated events wouldn't work. Perhaps there should be two forms of
events triggered by DataTables, those which do bubble and those which
do not. `init` is the only one which would _have_ to bubble.
* The workaround for the moment is to check that the settings object in
context of the executed settings handler is the same as the one that
was used in the addition of the event handler.
* This fixes DataTables/DataTables #361
* In particular this fixes the FixedColumns + ColReorder example which
was showing the problem by expanding the columns to the full container
width for each column. See thread 20848 for information.
* V8 strips unknown characters not only at the start of a string given
to Date.parse() but also at the end. So `10%` (for example) was being
detected as a date type.
* This fixes DataTables/DataTables #354
* This is likely to be of more interest to plug-in authors rather than
for general DataTables usage, but I've found myself wanting it a
couple of times recently for plug-ins.
New: `dt-api row().child.remove()` and `dt-api row().child().remove()` methods to provide the ability to remove and destroy child rows
Fix docs: Note that the row().child() method's return value can have an effect on the chaining
* This fixed DataTables/DataTables issue #326.
* Special thanks to `Scottmitch1` (on github) for help with this one!
Dev: Modify the initialisation of _Api - the old method of using `=`
twice on a row caused Chrome's debugger to show it as both names
concatinated which was confusing.
Fix: Remove API "build" code. That was part of the API prototype and the
design moved away from that approach. The code was redundant and unused.
* Originally this was done because it makes removing items a little bit
easier with Array.splice(), however, it doesn't make any sense to go
through the rows in reverse if there might be an interdependency
between the rows.
* It has never been documented what order the rows are filtered in, so I
think this is a safe change to make.
* I've also added the row display index to the parameters passed in
* This fix was partly committed earlier by mistake [b7feaa2]
* The fix is simply to store the draw hold state and make use of it in
the draw scroll callback.
* In IE8 if the DataTables width calculation functions were being
triggered DataTables would clone the table node and then do a jQuery
$().remove() on the cloned node. This was bad in IE8 as it meant that
on the remove the events that were attached tot he original table were
removed as well as the ones on the clone table. IE8 must retain some
kind of link between the original and clone nodes. Using jQuery's
clone() method resolves this.
* See thread 21040 for more information
* Previously the filter builder was created as a string, so we had to
escape quotes, otherwise it could create invalid HTML. That is no
longer the case as we are using jQuery DOM manipulation, so the escape
is redundant and potentially harmful
* See thread 21197
* Due to the manipulation of DOM elements rather than strings for the
length list, the browser was cropping elements which were being cut
short. Fix is to switch back to string manipulation, which can be done
easily using the outerHTML property of the DOM element. This is
supported in all browsers since Firefox 11, so happy to use it here.
* See thread 21170 for more information
* The two data handling functions for each column are now given a forth
parameter if you are using them as a function. This new parameter
gives index position information about the cell in question, as well
as access to the settings object.
* This additional information allows abstraction functions to be created
external to DataTables that can be reused for different columns, with
those abstraction functions now having access to the information about
the cell they are operating on. For example, you might have a number
formatting function which can be reused, and it will determine what
data to read based on the column index given.
* This additional information is required in order to be able to fully
replace fnRender which was removed in DataTables 1.10.
* This fixes DataTables/DataTables #321
* Documentation updated, including an error fix for columns.data
* The error was that the registered cells array was growing on every
call, so the processing took longer and the memory usage went up
* See thread 21063 for details
* The sort handler was expecting to deal with a 2D array, so we always
dropped into the single column first sort condition.
* See thread 20811 for more information.
- The stateDuration option has been updated to provide the ability to
indicate if sessionStorage should be used rather than localStorage
(set value to -1).
- Settings stateDuration to 0 also indicates that the duration is
infinity.
- Parts of the state saving have been optimised for code size, so this
commit actually reduces the min size by 32 bytes despite the new
abilities.
- See thread 19572 for discussion on this
- The column index selector was broken by a previous commit (d9f416232).
- Fix also an error in the column selector whereby a result was being
tested against itself
- If you provided your own <select> list for the lenght language option,
DataTables would still append its own and ignore your custom one
- See thread 20548
- Feedback from James Craig on improving the accessiblity of DataTables.
Since the `role=grid` option is added to the DataTables table, we
should also add `role=row` to the rows in the table so the browsers
can see them correctly. As James notes, it is debatable if this is
needed or not but it is required in current Chrome and Webkit.
- Webkit do now allow roles to be optional in the nighties - see:
https://bugs.webkit.org/show_bug.cgi?id=131819 . Once Apple deploy
this in a Safari update, and Chrome also deploy support, I think this
should be removed from DataTables core, since it will no longer be
needed in the latest browsers, and manipulating the DOM can hit
performance a bit.
- It is useful to be able to filter row indexes by a condition and then
operate on the resulting array of indexes, but before the selector
would only itterate over real arrays. So if you passed is an API
instance with the result set being the indexes to delete, it wouldn't
work!
- Fix is to loop over anything which has a `length` property
- Thread 20572
- Remove the aria-relevant from the info text to use the default,
otherwise it was reading information that isn't very useful
- Change info text role to `status`
- Remove `role=row` from header - this is experimental and might change.
Might need it on this row and all rows in the table
- Based on feedback from James Craig (thanks!)
- If you were to click the 'previous' button when on the first page, the
table would redraw - that's the easiest manifestation of this bug to
see. There is no need to redraw the table when the paging hasn't
changed, so don't.
- This fixes DataTables/DataTables #304
- Because DataTables is destroying and creating elements for the paging
control, focus is lost when navigating via keyboard. This is a real
pain when trying to operate DataTables that way! Fix is to refocus on
the new element.
- If you used client-side processing ajax, the parameter passed into
_fnBuildAjax is an array, needed for the old 1.9 compatiblity, but the
ajax wasn't transforming this into a data object and then sending it
to the server. The fix is to check if the data passed in is an array
or not - if so, transform it to an object
- If you use multiple column definations such that a columns' sorting
options are initially disabled and then enabled, the sorting classes
for the header were not being applied correctly.
- The fix is to always assign classes based on the most up-to-date
information for the column.
- This fixes DataTables/DataTables #303
- The resolution of unknown sorting types was being done after the
sorting structure array of objects was being calculated. As such, a
string sort was always being done in the first instance!
- This fixes thread 20433
- In a fenced code block, need to encode the HTML elements. However, the
HTML was being detected and saved first. Run the fencer first.
- Type links updated
- When invalidating a DOM row, DataTables wasn't taking into account the
fact that the columns in the row might be hidden. This means that the
array of data read is shortened by the number of hidden columns, and
thus the data is corrupted.
- Fix is to read from the known cells if the row already exists
- Issue here was that when doing the camelCase to hungarian conversion
on objects, the user object was copying over the hungarian default.
This meant that parameters were lost and things broke! The fix is to
decend into the object
- See thread 20233 for the original report
- DataTables' smart filtering now has the ability to search for an exact
string, in the given order, over multiple words. This is done by
providing the exact match search string in quotes - for example:
Angela "Cheif Exec" London
Will match three terms - `Angela`, `Cheif Exec` and `London`. Those
three terms will be matched in any order.
- This matches the search behaviour that we all know and love in Google!
- It can be disabled along with the rest of DataTables' smart filtering
using the `smart` option.
- This enhancement comes courtesy of Barry Keepence. Original forum
thread: http://datatables.net/forums/discussion/16250/. Thanks!
- See thread 20075 for the original report
- Basically the issue here was that the object being used for the API
extension on objects (e.g. `table.ajax` is an object) the object was
not unique to each API instance, so it was being shared between
instances and as a result, whatever instance was created last, would
win!
- Fix is to use a new object each time.
- DataTables uses the `DT` namespace for events internally and will
remove them automatically on destroy, but `dt` is used for public
events. As such, the public events used internally should use `.dt.DT`
to ensure that the listener works as expected, but also so that the
destroy call will remove these listeners
- This is to preserve user added listeners on destroy. If they want to
remove their listeners to prevent memory leaks, then they should do
so. But DataTables won't do it for them, as actually, you might want
to keep your event listeners!
- fnServerData's second parameter should be an array of objects with
name/value pairs. It was being passed through as the more modern
object, but fnServerData is only present for compatiblity with 1.9 and
should the original format should be retained. This is done with a
simple map function
found
- The old fnGetData method would return null, rather than undefined for
some reason if a given row was not found in the DataTable. The new
wrapper api for the legacy interface should do the same.
- Previously if you cancelled an Ajax request, or the browser did (for
example following a link) the error handler would be entered and show
an alert. This just ensures that the request is complete before
showing an error
- Previously when using columns.render as an object, you had to supply
an `_` option which was the fallback. However, I've now made it so
that if there is no `_` option it will just use the raw data from
`columns.data`
- I've come accross a lot of cases recently where numbers need to be
formatted for display, so I wanted to introduce rendering helpers for
DataTables to make this easier. Only one helper introduced here -
`$.fn.dataTable.render.number()` which will return an object that can
be used by `columns.render` to format "raw" numbers.
- The child row feature of DataTables should be able to take a `tr`
element and add that directly as a child. That wasn't working due to a
logic error before.
would be removed from the array of data passed through to the custom
filtering functions. This would cause indexes to misalign.
- The fix is to simply pass in the data filter array that has already
been computed, as that is 1:1 for the display. Also added the raw data
source object for the row for completeness and a bit of a code tidy
up.
- This will cause a bit of an indexing issue, if you have bVisible:false
set, but this is certainly a bug that had to be fixed - it just didn't
make sense as it was, and went against the documentation!
- See thread 19593 for more information
newly created elements
- The fix i've put in is basically the same as what DataTables 1.9-
used. I had tried to opitmise it a little, but it wasn't working for
newly created cells. I still think this can be optimised, but for the
moment, this is at least allows it to work.
and result set for the plural methods.
Fix: Row details events were itterating over non-DataTables rows
creating a Javascript error
Fix: Example - Server-side processing row details example updated to be
able to restore the details row on a redraw.
Update: Documentation - Most examples which used `flatten()` are more
correct to use the new `eq()` method, so they have been updated.
- This set of changes is based on the discussion in thread 19377. While
working on the fix, I realised that the use of flatten() is too broad,
so the new `eq()` function is introduced. It is similar to the jQuery
eq() method in that it reduces the instance to just the selected
index, although in DataTables this is both the context and the result
set. Its a small addition, but I think it will provide to be very
useful
DataTables which character is used as a decimal place in the table's
data, so that number which are formatted using characters other than a
dot as the decimal place can be correctly detected and sorted.
- A large part of the world uses the comma as a decimal place, so it
makes sense to have this option built-in directly to DataTables,
rather than needing to use plu-in sorting types as before:
http://en.wikipedia.org/wiki/Decimal_mark
- However, the decimal place character cannot be detected automatically
since there are far to many ambiguities. As such, a new
`language.decimal` option is defined which is passed through to the
type detection functions. The type detection functions can then use
that character to alter their detection functions to transform numbers
into the dot formatted equivilent for parsing in Javascript.
- The numeric sorting methods have been bundled together in the function
`_addNumericSort` which is called when a character is given for the
decimal mark, adding the sorting functions required specifically for
that mark. This means that any character at all can be added, while
keeping the table's sort performance as it was.
- Code size in increased a little for this new feature, but a lot of
work has been done to keep it to a minimum (while still optimising for
the most common use case of a dot decimal place), and this is a good
feature to have in DataTables' core code.
- All required documentation added and updated.
- Special thanks to Tobias Bäthge for suggesting and sponsoring this
feature.
- This is caused due to different content in the displayed header and
the size forcing header in the body scrolling table. The browsers can
lay the two tables out differently even although the widths applied
are identical, due to the different content.
- The fix is to keep the content in the scroll body header, but hide it
by wrapping in a div which has height 0 and overflow hidden
- See thread 19311 for more information
server-side processing
- A popular plug-in for DataTables is the `fnSetFilteringDelay` plug-in,
which provides a bit of a buffer when typing into the filter input so
you don't make an Ajax request for every key stroke - i.e. don't DDoS
your own server!
- Since we have _fnThrottle built in now for the scrolling, we can also
use it to provide this buffering functionality for server-side
processing filtering in the core. A couple of small changes for
_fnThrottle were required to get the callback context correct and ot
call it not immediately, but only after the delay
footer
Update: Update CSS to display the table border properly when there is no
footer when scrolling
Dev: Update the _fnAddOptionsHtml function to be smaller in code size.
Identical functionality, just smaller code
fact that the table width attribute has been removed, but was being
applied to the table anyway, as 0px - causing the table to be as narrow
as possible. On the plus size, the columns kept their alignment with
such a misconfiguration! However, now the `width` option for columns is
correctly applied in x-scrolling tables.
don't need to look it up with inArray. Also the header renderer does not
pass in the column index now (the column.idx property can be used). This
is to allow operations such as ColReorder to reorder teh columns and
still have the renderers update correctly
- Column width is always a particularly difficult one to get quite
right. In this case, the fix is to have DataTables read column width
information from the `width` or `style` attributes of a column header
cell, if that information is present. If it is, it is treated as
sWidth is (although user supplied sWidth can override). That is it say
that it will be applied to the column width calculation table.
- The remaining gap is if a developer assigns a width using css classes.
We can't get that information, so we fall into the old problem.
- This change comes about from the discussion in
http://datatables.net/forums/discussion/19089 and the fiddle here:
http://jsfiddle.net/EysLd/1/
- What is happening in the test case is that the calculation table is
being created, but it is then stripped of widths due to this commit:
https://github.com/DataTables/DataTables/commit/6a9e324 . That was to
allow DataTables column headers to have their applied size removed, so
a new size could be calculated. Only sWidth would override that - now
the width and style attributes will as well
- IE8- requires that Function.prototype.apply be used with an array or
arguments object as the second parameter - it being "array-like" isn't
good enough.
- This fixes DataTables/DataTables #262
plug-ins
- A lot of plug-ins use _fnCalculateEnd and although all that is needed
in the upgrade is to remove it, since the value is calculated
automatically now, it will likely cause confusion and hassle. So I've
added this stub to prevent those errors.
- Chrome (V8) will incorrectly detect '$245.12' and similar as dates,
since V8 will strip unknown characters from a string given to
Date.parse and then attempt to parse the rest of the string - in the
example above: Dec, 245:
https://code.google.com/p/v8/source/browse/trunk/src/dateparser-inl.h#72
- The fix implemented to to check for a leading a-zA-Z, number or +-.
Although this isn't a perfect match for what Chrome does, it, I think,
a good enough effort to chatch nearly all particular use cases.
- Additionaly, V8 will try to parse a single number passed into
Date.parse - 1-12 are months, 32+ are years. As such, the numeric type
detection much be a highter priority than the date detection, since
Chrome might incorrectly use a column as a date. It would sort
correctly, but it isn't "correct".
- The take away from this is that Date.parse cannot be used for date
format validation on its own...
1D arrays.
- The method implemented isn't actually 100% perfect - if you mix arrays
and scalars, then the behaviour is undefined. But that shouldn't
happen in DataTables. Will look into it further, though
- This is actually a little more complex than it might first appear
since any classes which have been added by DT_RowClass need to be
removed. We can't just bindly remove all classes, so we need to track
that classes have been added in a private variable.
- It appears that ti is impossible to know in CSS if a table doesn't
have a tfoot element reliably and cross browser, so I've added a class
which is added to the table automatically if the table has no footer
or the fotoer is empty to complete the styling of the table.
- Fixed error when there are no cells in an empty TR row in the footer.
- With the change to camelCase, it is easier to extend the usageof
optiosn now, and in this case I've allowed the `orderFixed` (formally
`aaSortingFixed` parameter to be passed in as an object as well as an
array. As an object the `pre` and `post` parameters are used to
specify prefix and / or postfix ordering. Useful for gouping.
- The _pluck() function that was being used to get the tr elements
didn't remove nulls, while jQuery doesn't like removing a class from!
- Thanks to `RagingTroll` in the forums for spotting this:
http://datatables.net/forums/discussion/18651
the property being expanded is an object or not. If not, then set it to
be an empty object which will be extended. Only really effected the
`ajax` property
Based on the discussion in the forms (
http://datatables.net/forums/discussion/18456 ) the fix from 8935b8a
wasn't good enough. What was happening was that the _save_data function
was doing a deep copy of all arrays (minus the data array) so the
default sort was stil applied.
The fix is to reinstate the _fnExtend function which does a jQuery like
deep extend on objects and a shallow extend on arrays. That is extended
slightly to allow array references to be broken on initialisation, to
resolve the issue 8935b8a attempted to (sorting array would be used for
two tables for example), by an optional parameter. This should resolve
the issue correctly this time!
- This fixes DataTables/DataTables issue #241.
- Most of the properties attached are objects, so we want the references
to them, rather than a copy, so a simple assignment is all that is
needed. Strings etc will continue to work as well.
syntax paraneter names
- Data added using fnServerParams with array syntax had different
behaviour in 1.10 from 1.9. In 1.9 jQuery would create an array for
us, but in 1.10 before we create an object first, we need to create
that array ourselves. So the following code had different behaviour:
"sAjaxSource": "data/arrays.txt",
"fnServerParams": function ( d ) {
d.push(
{name: 'somekey[]', value: 'somevalue1'},
{name: 'somekey[]', value: 'somevalue2'}
);
}
In 1.10 it would have sent `somekey[] = somevalue2` but 1.9 would have
sent both as part of an array.
To maintain full compatiblity with 1.9 we need to convert this syntax to
an array - this commit does that.
I was concerned about using parameters in the brackets, but jQuery only
searches for `[]` when performing this conversion. We could use $.param
and then decode the created query string, which would be absolutely 100%
comaptible, but would involve additional code and I think this method
provides that 100% compatiblity from reading the jQuery code), and its
shorter.
- This is the CSS version of the cellspacing attribute on the table in HTML. It will work in all browsers except IE6/7. IE8+ and the others are all fine. So for the moment most of my examples will continue carrying the cellspacing attribute, but this is useful to have in the core css
- The ability to use negative numbers as a column selector for the
column data index was added recently, but that didn't include the
ability to work with negative numbers with the :visible pesudo
selector. This commit adds that ability so you can do:
`table.column("-1:visible")` to always get the right most visible
column
with :name postfix.
- Previously you could use a jQuery selector for columns by using the
:jq postfix, and names were matched otherwise. This is reversed now
for consistency with the rows and cells selectors which treat strings
as jQuery selectors without the :jq postfix.
returned undefined, null etc.
- The base issue was in the instanceof check which has a priority error,
it was:
! obj instanceof _Api
which is the same as:
(! obj) instanceof _Api
which is rubbish.
We want:
! (obj instanceof _Api)
but there is of course a wrapper function, so that needs ot be taken
into account as well. The new logic does just that.
- 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
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.
- 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.