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