Update doc comments for new web-site

Fix a number of errors such as leaking variables and code style
pull/40/head
Allan Jardine 11 years ago
parent 4f29d7fda6
commit 4df671ed24

@ -1,13 +1,24 @@
/** /**
* Average the values in a data set. * It can sometimes be useful to get the average of data in an API result set,
* be it from a column, or a collection of cells. This method provides exactly
* that ability.
* *
* @name average() * @name average()
* @summary * @summary Average the values in a data set.
* @author [Allan Jardine](http://sprymedia.co.uk) * @author [Allan Jardine](http://sprymedia.co.uk)
* @requires DataTables 1.10+ * @requires DataTables 1.10+
* *
* @returns {Number} Calculated average
*
* @example * @example
* // Average a column
* var table = $('#example').DataTable();
* table.column( 3 ).data().average(); * table.column( 3 ).data().average();
*
* @example
* // Average two cells
* var table = $('#example').DataTable();
* table.cells( 0, [3,4] ).data().average();
*/ */
jQuery.fn.dataTable.Api.register( 'average()', function () { jQuery.fn.dataTable.Api.register( 'average()', function () {

@ -1,20 +1,25 @@
/** /**
* Add a new row to the table and display it on the screen by jumping the * Add a new row to the table and display it on the screen by jumping the
* pagination to the required location. This function also returns an object * pagination to the required location. This function also returns an object
* with the added TR element and it's index in aoData such that you could * with the added `dt-tag TR` element and it's index in `aoData` such that you
* provide an effect (fade for example) to show which row has been added. * could provide an effect (fade for example) to show which row has been added.
* This function is a drop in replacement for fnAddData with one important *
* This function is a drop in replacement for `fnAddData` with one important
* exception, it will only take a 1D array or an object, and not a 2D array * exception, it will only take a 1D array or an object, and not a 2D array
* (i.e. it will not add multiple rows like fnAddData). * (i.e. it will not add multiple rows like `fnAddData`).
* *
* @name fnAddDataAndDisplay * @name fnAddDataAndDisplay
* @summary * @summary Add data and shift the paging to display it immediately
* @author [Allan Jardine](http://sprymedia.co.uk) * @author [Allan Jardine](http://sprymedia.co.uk)
* *
* @param {data} aData Data to add to the table
* @returns {object} Object with `nTr` and `iPos` parameters, where the former
* is the added `dt-tag tr` element and the latter is the row's index.
*
* @example * @example
* $(document).ready(function() { * $(document).ready(function() {
* var oTable = $('#example').dataTable(); * var table = $('#example').dataTable();
* oTable.fnAddDataAndDisplay( [ 1, 2, 3, 4, 5, ... ] ); * table.fnAddDataAndDisplay( [ 1, 2, 3, 4, 5, ... ] );
* } ); * } );
*/ */
@ -45,7 +50,9 @@ jQuery.fn.dataTableExt.oApi.fnAddDataAndDisplay = function ( oSettings, aData )
if( iPos >= 0 ) if( iPos >= 0 )
{ {
oSettings._iDisplayStart = ( Math.floor(i / oSettings._iDisplayLength) ) * oSettings._iDisplayLength; oSettings._iDisplayStart = ( Math.floor(i / oSettings._iDisplayLength) ) * oSettings._iDisplayLength;
this.oApi._fnCalculateEnd( oSettings ); if ( this.oApi._fnCalculateEnd ) {
this.oApi._fnCalculateEnd( oSettings );
}
} }
this.oApi._fnDraw( oSettings ); this.oApi._fnDraw( oSettings );

@ -1,13 +1,30 @@
/** /**
* Take a TR element and add it to a DataTables table. Useful for maintaining * This method will add an existing `dt-tag tr` element to a DataTable. This can
* custom classes and other attributes. * be useful for maintaining custom classes and other attributes which have
* been explicitly assigned to the row.
*
* DataTables 1.10+ has `dt-api row.add()` and `dt-api rows.add()` which have
* this ability built in, and extend it to be able to use jQuery objects as well
* as plain `dt-tag tr` elements. As such this method is marked deprecated, but
* is available for use with legacy version of DataTables. Please use the
* new API if you are used DataTables 1.10 or newer.
* *
* @name fnAddTr * @name fnAddTr
* @summary * @summary Add a `dt-tag tr` element to the table
* @author [Allan Jardine](http://sprymedia.co.uk) * @author [Allan Jardine](http://sprymedia.co.uk)
* @deprecated
*
* @param {node} nTr `dt-tag tr` element to add to the table
* @param {boolean} [bRedraw=false] Indicate if the table should do a redraw or not.
* *
* @example * @example
* * var table = $('#example').dataTable();
* table.fnAddTr( $('<tr>'+
* '<td>1</td>'+
* '<td>2</td>'+
* '<td>3</td>'+
* '</tr>')[0]
* );
*/ */
jQuery.fn.dataTableExt.oApi.fnAddTr = function ( oSettings, nTr, bRedraw ) { jQuery.fn.dataTableExt.oApi.fnAddTr = function ( oSettings, nTr, bRedraw ) {

@ -1,19 +1,33 @@
/** /**
* When DataTables removes columns from the display (bVisible or * When DataTables removes columns from the display (`bVisible` or
* fnSetColumnVis) it removes these elements from the DOM, effecting the * `fnSetColumnVis`) it removes these elements from the DOM, effecting the index
* index value for the column positions. This function converts the data * value for the column positions. This function converts the data column index
* column index (i.e. all columns regardless of visibility) into a visible * (i.e. all columns regardless of visibility) into a visible column index.
* column index. *
* DataTables 1.10+ has this ability built-in through the
* `dt-api column.index()` method. As such this method is marked deprecated, but
* is available for use with legacy version of DataTables.
* *
* @name fnColumnIndexToVisible * @name fnColumnIndexToVisible
* @summary * @summary Convert a column data index to a visible index.
* @author [Allan Jardine](http://sprymedia.co.uk) * @author [Allan Jardine](http://sprymedia.co.uk)
* @deprecated
*
* @param {integer} iMatch Column data index to convert to visible index
* @returns {integer} Visible column index
* *
* @example * @example
* * var table = $('#example').dataTable( {
* aoColumnDefs: [
* { bVisible: false, aTargets: [1] }
* ]
* } );
*
* // This will show 1
* alert( 'Column 2 visible index: '+table.fnColumnIndexToVisible(2) );
*/ */
$.fn.dataTableExt.oApi.fnColumnIndexToVisible = function ( oSettings, iMatch ) jQuery.fn.dataTableExt.oApi.fnColumnIndexToVisible = function ( oSettings, iMatch )
{ {
return oSettings.oApi._fnColumnIndexToVisible( oSettings, iMatch ); return oSettings.oApi._fnColumnIndexToVisible( oSettings, iMatch );
}; };

@ -1,13 +1,19 @@
/** /**
* Update the internal data for a TR element based on what is used in the * Update the internal data for a `dt-tag tr` element based on what is used in the
* DOM. You will likely want to call fnDraw() after this function. * DOM. You will likely want to call fnDraw() after this function.
* *
* DataTables 1.10+ has this ability built-in through the
* `dt-api row().invalidate()` method. As such this method is marked deprecated,
* but is available for use with legacy version of DataTables. Please use the
* new API if you are used DataTables 1.10 or newer.
*
* @name fnDataUpdate * @name fnDataUpdate
* @summary * @summary Update DataTables cached data from the DOM
* @author Lior Gerson * @author Lior Gerson
* @deprecated
* *
* @example * @param {node} nTr `dt-tag tr` element to get the data from
* * @param {integer} iRowIndex Row's position in the table (`fnGetPosition`).
*/ */
jQuery.fn.dataTableExt.oApi.fnDataUpdate = function ( oSettings, nRowObject, iRowIndex ) jQuery.fn.dataTableExt.oApi.fnDataUpdate = function ( oSettings, nRowObject, iRowIndex )

@ -1,16 +1,17 @@
/** /**
* Take a TR element and alter the table's paging to show the TR in question. * This plug-in will take a `dt-tag tr` element and alter the table's paging
* to make that `dt-tag tr` element (i.e. that row) visible.
* *
* @name fnDisplayRow * @name fnDisplayRow
* @summary * @summary Shift the table's paging to display a given `dt-tag tr` element
* @author [Allan Jardine](http://sprymedia.co.uk) * @author [Allan Jardine](http://sprymedia.co.uk)
* *
* @param {node} nRow Row to display
*
* @example * @example
* $(document).ready(function() { * // Display the 21st row in the table
* // Display the 21st row in the table * var table = $('#example').dataTable();
* var oTable = $('#example').dataTable(); * table.fnDisplayRow( table.fnGetNodes()[20] );
* oTable.fnDisplayRow( oTable.fnGetNodes()[20] );
* } );
*/ */
jQuery.fn.dataTableExt.oApi.fnDisplayRow = function ( oSettings, nRow ) jQuery.fn.dataTableExt.oApi.fnDisplayRow = function ( oSettings, nRow )
@ -36,7 +37,9 @@ jQuery.fn.dataTableExt.oApi.fnDisplayRow = function ( oSettings, nRow )
if( iPos >= 0 ) if( iPos >= 0 )
{ {
oSettings._iDisplayStart = ( Math.floor(i / oSettings._iDisplayLength) ) * oSettings._iDisplayLength; oSettings._iDisplayStart = ( Math.floor(i / oSettings._iDisplayLength) ) * oSettings._iDisplayLength;
this.oApi._fnCalculateEnd( oSettings ); if ( this.oApi._fnCalculateEnd ) {
this.oApi._fnCalculateEnd( oSettings );
}
} }
this.oApi._fnDraw( oSettings ); this.oApi._fnDraw( oSettings );

@ -3,25 +3,30 @@
* table. * table.
* *
* @name fnDisplayStart * @name fnDisplayStart
* @summary * @summary Change the table's paging display start.
* @author [Allan Jardine](http://sprymedia.co.uk) * @author [Allan Jardine](http://sprymedia.co.uk)
* @deprecated
*
* @param {integer} iStart Display start index.
* @param {boolean} [bRedraw=false] Indicate if the table should do a redraw or not.
* *
* @example * @example
* * var table = $('#example').dataTable();
* table.fnDisplayStart( 21 );
*/ */
jQuery.fn.dataTableExt.oApi.fnDisplayStart = function ( oSettings, iStart, bRedraw ) jQuery.fn.dataTableExt.oApi.fnDisplayStart = function ( oSettings, iStart, bRedraw )
{ {
if ( typeof bRedraw == 'undefined' ) if ( typeof bRedraw == 'undefined' ) {
{
bRedraw = true; bRedraw = true;
} }
oSettings._iDisplayStart = iStart; oSettings._iDisplayStart = iStart;
oSettings.oApi._fnCalculateEnd( oSettings ); if ( oSettings.oApi._fnCalculateEnd ) {
oSettings.oApi._fnCalculateEnd( oSettings );
}
if ( bRedraw ) if ( bRedraw ) {
{
oSettings.oApi._fnDraw( oSettings ); oSettings.oApi._fnDraw( oSettings );
} }
}; };

@ -1,13 +1,19 @@
/** /**
* Creates rowspan cells in a column when there are two or more cells in a * Creates `rowspan` cells in a column when there are two or more cells in a
* row with the same content, effectively grouping them together visually. * row with the same content, effectively grouping them together visually.
* *Note* - this plug-in currently only operates correctly with *
* *server-side processing*. * **Note** - this plug-in currently only operates correctly with
* **server-side processing**.
* *
* @name fnFakeRowspan * @name fnFakeRowspan
* @summary * @summary Create a rowspan for cells which share data
* @author Fredrik Wendel * @author Fredrik Wendel
* *
* @param {interger} iColumn Column index to have row span
* @param {boolean} [bCaseSensitive=true] If the data check should be case
* sensitive or not.
* @returns {jQuery} jQuery instance
*
* @example * @example
* $('#example').dataTable().fnFakeRowspan(3); * $('#example').dataTable().fnFakeRowspan(3);
*/ */

@ -1,19 +1,31 @@
/** /**
* Apply the same filter to all DataTable instances on a particular page. The * Apply the same filter to all DataTable instances on a particular page. The
* function call exactly matches that used by fnFilter() so regular expression * function call exactly matches that used by `fnFilter()` so regular expression
* and individual column sorting can be used. * and individual column sorting can be used.
* *
* DataTables 1.10+ provides this ability through its new API, which is able to
* to control multiple tables at a time.
* `$('.dataTable').DataTable().search( ... )` for example will apply the same
* filter to all tables on the page. The new API should be used in preference
* to this older method if at all possible.
*
* @name fnFilterAll * @name fnFilterAll
* @summary * @summary Apply a common filter to all DataTables on a page
* @author [Kristoffer Karlström](http://www.kmmtiming.se/) * @author [Kristoffer Karlström](http://www.kmmtiming.se/)
* @deprecated
*
* @param {string} sInput Filtering input
* @param {integer} [iColumn=null] Column to apply the filter to
* @param {boolean} [bRegex] Regular expression flag
* @param {boolean} [bSmart] Smart filtering flag
* *
* @example * @example
* $(document).ready(function() { * $(document).ready(function() {
* var oTable = $(".dataTable").dataTable(); * var table = $(".dataTable").dataTable();
* *
* $("#search").keyup( function () { * $("#search").keyup( function () {
* // Filter on the column (the index) of this element * // Filter on the column (the index) of this element
* oTable.fnFilterAll(this.value); * table.fnFilterAll(this.value);
* } ); * } );
* }); * });
*/ */

@ -2,20 +2,34 @@
* Remove all filtering that has been applied to a DataTable, be it column * Remove all filtering that has been applied to a DataTable, be it column
* based filtering or global filtering. * based filtering or global filtering.
* *
* DataTables 1.10+ new API can achieve the same effect as this plug-in, without
* the requirement for plug-ins using the following chaining:
*
* ```js
* var table = $('#example').DataTable();
* table
* .search( '' )
* .columns().search( '' )
* .draw();
* ```
*
* Please use the new API in DataTables 1.10+ is you are able to do so.
*
* @name fnFilterClear * @name fnFilterClear
* @summary * @summary Remove all column and global filters applied to a table
* @author [Allan Jardine](http://sprymedia.co.uk) * @author [Allan Jardine](http://sprymedia.co.uk)
* @deprecated
* *
* @example * @example
* $(document).ready(function() { * $(document).ready(function() {
* var oTable = $('#example').dataTable(); * var table = $('#example').dataTable();
* *
* // Perform a filter * // Perform a filter
* oTable.fnFilter('Win'); * table.fnFilter('Win');
* oTable.fnFilter('Trident', 0); * table.fnFilter('Trident', 0);
* *
* // Remove all filtering * // Remove all filtering
* oTable.fnFilterClear(); * table.fnFilterClear();
* } ); * } );
*/ */

@ -1,12 +1,14 @@
/** /**
* This plug-in removed the default behaviour of DataTables to filter on each * This plug-in removes the default behaviour of DataTables to filter on each
* keypress, and replaces with it the requirement to press the enter key to * keypress, and replaces with it the requirement to press the enter key to
* perform the filter. * perform the filter.
* *
* @name fnFilterOnReturn * @name fnFilterOnReturn
* @summary * @summary Require the return key to be pressed to filter a table
* @author [Jon Ranes](http://www.mvccms.com/) * @author [Jon Ranes](http://www.mvccms.com/)
* *
* @returns {jQuery} jQuery instance
*
* @example * @example
* $(document).ready(function() { * $(document).ready(function() {
* $('.dataTable').dataTable().fnFilterOnReturn(); * $('.dataTable').dataTable().fnFilterOnReturn();
@ -20,12 +22,14 @@ jQuery.fn.dataTableExt.oApi.fnFilterOnReturn = function (oSettings) {
$.fn.dataTableExt.iApiIndex = i; $.fn.dataTableExt.iApiIndex = i;
var $this = this; var $this = this;
var anControl = $('input', _that.fnSettings().aanFeatures.f); var anControl = $('input', _that.fnSettings().aanFeatures.f);
anControl.unbind('keyup').bind('keypress', function (e) { anControl
if (e.which == 13) { .unbind('keyup search input')
$.fn.dataTableExt.iApiIndex = i; .bind('keypress', function (e) {
_that.fnFilter(anControl.val()); if (e.which == 13) {
} $.fn.dataTableExt.iApiIndex = i;
}); _that.fnFilter(anControl.val());
}
});
return this; return this;
}); });
return this; return this;

@ -5,16 +5,20 @@
* match. * match.
* *
* @name fnFindCellRowIndexes * @name fnFindCellRowIndexes
* @summary * @summary Search for data, returning row indexes
* @author [Allan Jardine](http://sprymedia.co.uk) * @author [Allan Jardine](http://sprymedia.co.uk)
* *
* @param {string} sSearch Data to search for
* @param {integer} [iColumn=null] Limit search to this column
* @returns {array} Array of row indexes with this data
*
* @example * @example
* $(document).ready(function() { * $(document).ready(function() {
* var oTable = $('#example').dataTable(); * var table = $('#example').dataTable();
* *
* var a = oTable.fnFindCellRowIndexes( '1.7' ); // Search all columns * var a = table.fnFindCellRowIndexes( '1.7' ); // Search all columns
* *
* var b = oTable.fnFindCellRowIndexes( '1.7', 3 ); // Search only column 3 * var b = table.fnFindCellRowIndexes( '1.7', 3 ); // Search only column 3
* } ); * } );
*/ */
@ -28,7 +32,7 @@ jQuery.fn.dataTableExt.oApi.fnFindCellRowIndexes = function ( oSettings, sSearch
{ {
aData = oSettings.aoData[i]._aData; aData = oSettings.aoData[i]._aData;
if ( typeof iColumn == 'undefined' ) if ( iColumn === undefined )
{ {
for ( j=0, jLen=aData.length ; j<jLen ; j++ ) for ( j=0, jLen=aData.length ; j<jLen ; j++ )
{ {

@ -1,20 +1,24 @@
/** /**
* Much like fnFindCellRowIndexes this plug-in will search a table for * Much like `fnFindCellRowIndexes` this plug-in will search a table for
* matching data (optionally the search can be restricted to a single column), * matching data (optionally the search can be restricted to a single column),
* but in this case the returned array contains TR nodes of the matching rows, * but in this case the returned array contains `dt-tag tr` nodes of the
* rather than data indexes. * matching rows, rather than data indexes.
* *
* @name fnFindCellRowNodes * @name fnFindCellRowNodes
* @summary * @summary Search for data, returning row nodes
* @author [Allan Jardine](http://sprymedia.co.uk) * @author [Allan Jardine](http://sprymedia.co.uk)
* *
* @param {string} sSearch Data to search for
* @param {integer} [iColumn=null] Limit search to this column
* @returns {array} Array of `dt-tag tr` element with this data
*
* @example * @example
* $(document).ready(function() { * $(document).ready(function() {
* var oTable = $('#example').dataTable(); * var table = $('#example').dataTable();
* *
* var a = oTable.fnFindCellRowNodes( '1.7' ); // Search all columns * var a = table.fnFindCellRowNodes( '1.7' ); // Search all columns
* *
* var b = oTable.fnFindCellRowNodes( '1.7', 3 ); // Search only column 3 * var b = table.fnFindCellRowNodes( '1.7', 3 ); // Search only column 3
* } ); * } );
*/ */
@ -28,7 +32,7 @@ jQuery.fn.dataTableExt.oApi.fnFindCellRowNodes = function ( oSettings, sSearch,
{ {
aData = oSettings.aoData[i]._aData; aData = oSettings.aoData[i]._aData;
if ( typeof iColumn == 'undefined' ) if ( iColumn === undefined )
{ {
for ( j=0, jLen=aData.length ; j<jLen ; j++ ) for ( j=0, jLen=aData.length ; j<jLen ; j++ )
{ {

@ -1,23 +1,29 @@
/** /**
* Due to the fact that DataTables moves DOM elements around (mainly TR * Due to the fact that DataTables moves DOM elements around (mainly `dt-tag tr`
* elements for sorting and filtering) it can at times be a little tricky * elements for sorting and filtering) it can at times be a little tricky to get
* to get the next row based on another, while taking into account pagination, * the next row based on another, while taking into account pagination,
* filtering, sorting etc. This function is designed to address exactly this * filtering, sorting etc.
* situation. It takes two parameters, the target node, and a boolean *
* indicating if the adjacent row retrieved should be the next (true, or no * This function is designed to address exactly this situation. It takes two
* value) or the previous (false). * parameters, the target node, and a boolean indicating if the adjacent row
* retrieved should be the next (`true`, or no value) or the previous (`false`).
* *
* @name fnGetAdjacentTr * @name fnGetAdjacentTr
* @summary * @summary Get the adjacent `dt-tag tr` element for a row.
* @author [Allan Jardine](http://sprymedia.co.uk) * @author [Allan Jardine](http://sprymedia.co.uk)
* *
* @param {node} nTr `dt-tag tr` element to get the adjacent element of
* @param {boolean} [bNext=true] Get the next (`true`), or previous (`false`)
* `dt-tag tr` element.
* @returns {node} `dt-tag tr` element or null if not found.
*
* @example * @example
* $(document).ready(function() { * $(document).ready(function() {
* var oTable = $('#example').dataTable(); * var table = $('#example').dataTable();
* *
* var n1 = $('#example tbody tr:eq(2)')[0]; * var n1 = $('#example tbody tr').eq(2)[0];
* var nNext = oTable.fnGetAdjacentTr( n1 ); * var next = table.fnGetAdjacentTr( n1 );
* var nPrev = oTable.fnGetAdjacentTr( n1, false ); * var prev = table.fnGetAdjacentTr( n1, false );
* } ); * } );
*/ */

@ -2,12 +2,25 @@
* Return an array of table values from a particular column, with various * Return an array of table values from a particular column, with various
* filtering options. * filtering options.
* *
* DataTables 1.10+ provides the `dt-api column().data()` method, built-in to
* the core, to provide this ability. As such, this method is marked deprecated,
* but is available for use with legacy version of DataTables. Please use the
* new API if you are used DataTables 1.10 or newer.
*
* @name fnGetColumnData * @name fnGetColumnData
* @summary * @summary Get the data from a column
* @author [Benedikt Forchhammer](http://mind2.de) * @author [Benedikt Forchhammer](http://mind2.de)
* @deprecated
*
* @param {integer} iColumn Column to get data from
* @param {boolean} [bFiltered=true] Reduce the data set to only unique values
* @param {boolean} [bUnique=true] Get data from filter results only
* @param {boolean} [bIgnoreEmpty=true] Remove data elements which are empty
* @returns {array} Array of data from the column
* *
* @example * @example
* * var table = $('#example').dataTable();
* table.fnGetColumnData( 3 );
*/ */
jQuery.fn.dataTableExt.oApi.fnGetColumnData = function ( oSettings, iColumn, bUnique, bFiltered, bIgnoreEmpty ) { jQuery.fn.dataTableExt.oApi.fnGetColumnData = function ( oSettings, iColumn, bUnique, bFiltered, bIgnoreEmpty ) {

@ -6,11 +6,15 @@
* the column index, helping to overcome this problem. * the column index, helping to overcome this problem.
* *
* @name fnGetColumnIndex * @name fnGetColumnIndex
* @summary * @summary Get the column index by searching the column titles
* @author [Michael Ross](http://www.rosstechassociates.com/) * @author [Michael Ross](http://www.rosstechassociates.com/)
* *
* @param {string} sCol Column title to search for
* @returns {integer} Column index, or -1 if not found
*
* @example * @example
* * var table = $('#example').dataTable();
* table.fnGetColumnIndex( 'Browser' );
*/ */
jQuery.fn.dataTableExt.oApi.fnGetColumnIndex = function ( oSettings, sCol ) jQuery.fn.dataTableExt.oApi.fnGetColumnIndex = function ( oSettings, sCol )

@ -1,10 +1,18 @@
/** /**
* Get a list of all TR nodes in the table which are not currently visible * Get a list of all `dt-tag tr` nodes in the table which are not currently
* (useful for building forms). * visible (useful for building forms).
*
* This function is marked as deprecated as using the `dt-api rows()` method in
* DataTables 1.10+ is preferred to this approach.
* *
* @name fnGetHiddenNodes * @name fnGetHiddenNodes
* @summary * @summary Get the `dt-tag tr` elements which are not in the DOM
* @author [Allan Jardine](http://sprymedia.co.uk) * @author [Allan Jardine](http://sprymedia.co.uk)
* @deprecated
*
* @example
* var table = $('#example').dataTable();
* var nodes = table.fnGetHiddenNodes();
*/ */
jQuery.fn.dataTableExt.oApi.fnGetHiddenNodes = function ( settings ) jQuery.fn.dataTableExt.oApi.fnGetHiddenNodes = function ( settings )

@ -1,20 +1,31 @@
/** /**
* Get a TD node from a row, taking into account column visibility. While * Get a `dt-tag td` node from a row, taking into account column visibility.
* getting a TD node is easy when it is visible on the page by using normal * While getting a `dt-tag td` node is easy when it is visible on the page by
* DOM methods, jQuery or whatever, it becomes a lot more complicated when * using normal DOM methods, jQuery or whatever, it becomes a lot more
* taking into account hidden rows and columns. This function can be used to * complicated when taking into account hidden rows and columns. This function
* overcome these difficulties. * can be used to overcome these difficulties.
*
* DataTables 1.10+'s new API provides the `dt-api cell()` and `dt-api cells()`
* methods which are preferable for use over this method. As such this method is
* marked deprecated, but is available for use with legacy version of
* DataTables. Please use the new API if you are used DataTables 1.10 or newer.
* *
* @name fnGetTd * @name fnGetTd
* @summary * @summary Get the `dt-tag td` element for a cell.
* @author [Allan Jardine](http://sprymedia.co.uk) * @author [Allan Jardine](http://sprymedia.co.uk)
* @deprecated
*
* @param {node} mTr `dt-tag tr` element to get the `dt-tag td` of
* @param {integer} iTd Column index to get the node of
* @param {boolean} bVisOnly Consider visible columns only
* @returns {node} `dt-tag td` element in question
* *
* @example * @example
* $(document).ready(function() { * $(document).ready(function() {
* var oTable = $('#example').dataTable(); * var table = $('#example').dataTable();
* *
* // Sort in the order that was origially in the HTML * // Sort in the order that was origially in the HTML
* var nTd = oTable.fnGetTd( $('#example tbody tr:eq(1)')[0], 1 ); * var nTd = table.fnGetTd( $('#example tbody tr:eq(1)')[0], 1 );
* console.log( nTd ); * console.log( nTd );
* } ); * } );
*/ */

@ -1,10 +1,19 @@
/** /**
* Get an array of TD nodes from DataTables for a given row, including any * Get an array of `dt-tag td` nodes from DataTables for a given row, including
* column elements which are hidden. * any column elements which are hidden.
*
* DataTables 1.10 has the `dt-api row().nodes()` method, built-in, to provide
* this functionality. As such this method is marked deprecated, but is
* available for use with legacy version of DataTables. Please use the new API
* if you are used DataTables 1.10 or newer.
* *
* @name fnGetTds * @name fnGetTds
* @summary * @summary Get the `dt-tag td` elements for a row
* @author [Allan Jardine](http://sprymedia.co.uk) * @author [Allan Jardine](http://sprymedia.co.uk)
* @deprecated
*
* @param {node} mTr `dt-tag tr` element to get the `dt-tag td` of
* @returns {array} Array of `dt-tag td` elements
* *
* @example * @example
* $(document).ready(function() { * $(document).ready(function() {

@ -2,14 +2,20 @@
* Change the number of records that can be viewed on a single page in * Change the number of records that can be viewed on a single page in
* DataTables. * DataTables.
* *
* DataTables 1.10 provides the `dt-api page.len()` method to get and set the
* page length using the built-in API. As such this method is marked deprecated,
* but is available for use with legacy version of DataTables. Please use the
* new API if you are used DataTables 1.10 or newer.
*
* @name fnLengthChange * @name fnLengthChange
* @summary * @summary Change the paging display length
* @author [Pedro Alves](http://www.webdetails.pt/) * @author [Pedro Alves](http://www.webdetails.pt/)
* @deprecated
* *
* @example * @example
* $(document).ready(function() { * $(document).ready(function() {
* var oTable = $('#example').dataTable(); * var table = $('#example').dataTable();
* oTable.fnLengthChange( 100 ); * table.fnLengthChange( 100 );
* } ); * } );
*/ */

@ -1,17 +1,36 @@
/** /**
* This plug-in adds to DataTables the ability to set multiple column * This plug-in adds to DataTables the ability to set multiple column filtering
* filtering terms in a single call (particularly useful if using server-side * terms in a single call (particularly useful if using server-side processing).
* processing). Used in combination with the column sName parameter, simply * Used in combination with the column sName parameter, simply pass in an object
* pass in an object with the key/value pair being the column you wish to * with the key/value pair being the column you wish to search on, and the value
* search on, and the value you wish to search for. * you wish to search for.
*
* DataTables 1.10's API provides a easy built-in way to apply multiple filters
* to the table without redrawing until required. For example, the example below
* with the DataTables 1.10 API could be written as:
*
* ```js
* var table = $('#example').DataTable();
* table
* .column( 0 ).search( 'Gecko' )
* .column( 1 ).search( 'Cam' )
* .draw();
* ```
*
* As such this method is marked deprecated, but is available for use with
* legacy version of DataTables. Please use the new API if you are used
* DataTables 1.10 or newer.
* *
* @name fnMultiFilter * @name fnMultiFilter
* @summary * @summary Apply multiple column filters together
* @author _mrkevans_ * @author _mrkevans_
* @deprecated
*
* @param {object} oData Data to search for
* *
* @example * @example
* $(document).ready(function() { * $(document).ready(function() {
* var oTable = $('#example').dataTable( { * var table = $('#example').dataTable( {
* "aoColumns": [ * "aoColumns": [
* { "sName": "engine" }, * { "sName": "engine" },
* { "sName": "browser" }, * { "sName": "browser" },
@ -20,7 +39,7 @@
* { "sName": "grade" } * { "sName": "grade" }
* ] * ]
* } ); * } );
* oTable.fnMultiFilter( { "engine": "Gecko", "browser": "Cam" } ); * table.fnMultiFilter( { "engine": "Gecko", "browser": "Cam" } );
* } ); * } );
*/ */

@ -3,9 +3,15 @@
* using to display each page, including the number of records shown, start * using to display each page, including the number of records shown, start
* and end points in the data set etc. * and end points in the data set etc.
* *
* DataTables 1.10+ provides the `dt-api page.info()` method, built-in, provide
* the same information as this method. As such this method is marked
* deprecated, but is available for use with legacy version of DataTables.
* Please use the new API if you are used DataTables 1.10 or newer.
*
* @name fnPagingInfo * @name fnPagingInfo
* @summary * @summary Get information about the paging state of the table
* @author [Allan Jardine](http://sprymedia.co.uk) * @author [Allan Jardine](http://sprymedia.co.uk)
* @deprecated
* *
* @example * @example
* $(document).ready(function() { * $(document).ready(function() {

@ -1,23 +1,26 @@
/** /**
* When doing some heavy processing of your own (for example using fnOpen with * When doing some heavy processing of your own (for example using fnOpen with
* data loading from the server) it can be useful to make use of the * data loading from the server) it can be useful to make use of the
* 'processing' indicator built-into DataTables. This plug-in function * 'processing' indicator built-into DataTables. This plug-in function exposes
* exposes the internal DataTables function so it can be used for exactly this. * the internal DataTables function so it can be used for exactly this.
* *
* @name fnProcessingIndicator * @name fnProcessingIndicator
* @summary * @summary Show and hide the DataTables processing element through the API.
* @author Allan Chappell * @author Allan Chappell
* *
* @param {boolean} [onoff=true] Show (`true`) or hide (`false`) the processing
* element.
*
* @example * @example
* oTable.fnProcessingIndicator(); // On * var table = $('#example').dataTable();
* oTable.fnProcessingIndicator(false); // Off * table.fnProcessingIndicator(); // On
* table.fnProcessingIndicator(false); // Off
*/ */
jQuery.fn.dataTableExt.oApi.fnProcessingIndicator = function ( oSettings, onoff ) jQuery.fn.dataTableExt.oApi.fnProcessingIndicator = function ( oSettings, onoff )
{ {
if( typeof(onoff) == 'undefined' ) if ( onoff === undefined ) {
{ onoff = true;
onoff=true;
} }
this.oApi._fnProcessingDisplay( oSettings, onoff ); this.oApi._fnProcessingDisplay( oSettings, onoff );
}; };

@ -1,19 +1,36 @@
/** /**
* By default DataTables only uses the sAjaxSource variable at initialisation * By default DataTables only uses the sAjaxSource variable at initialisation
* time, however it can be useful to re-read an Ajax source and have the table * time, however it can be useful to re-read an Ajax source and have the table
* update. Typically you would need to use the fnClearTable() and fnAddData() * update. Typically you would need to use the `fnClearTable()` and
* functions, however this wraps it all up in a single function call. * `fnAddData()` functions, however this wraps it all up in a single function
* call.
*
* DataTables 1.10 provides the `dt-api ajax.url()` and `dt-api ajax.reload()`
* methods, built-in, to give the same functionality as this plug-in. As such
* this method is marked deprecated, but is available for use with legacy
* version of DataTables. Please use the new API if you are used DataTables 1.10
* or newer.
* *
* @name fnReloadAjax * @name fnReloadAjax
* @summary * @summary Reload the table's data from the Ajax source
* @author [Allan Jardine](http://sprymedia.co.uk) * @author [Allan Jardine](http://sprymedia.co.uk)
* @deprecated
*
* @param {string} [sNewSource] URL to get the data from. If not give, the
* previously used URL is used.
* @param {function} [fnCallback] Callback that is executed when the table has
* redrawn with the new data
* @param {boolean} [bStandingRedraw=false] Standing redraw (don't changing the
* paging)
* *
* @example * @example
* var table = $('#example').dataTable();
*
* // Example call to load a new file * // Example call to load a new file
* oTable.fnReloadAjax( 'media/examples_support/json_source2.txt' ); * table.fnReloadAjax( 'media/examples_support/json_source2.txt' );
* *
* // Example call to reload from original file * // Example call to reload from original file
* oTable.fnReloadAjax(); * table.fnReloadAjax();
*/ */
jQuery.fn.dataTableExt.oApi.fnReloadAjax = function ( oSettings, sNewSource, fnCallback, bStandingRedraw ) jQuery.fn.dataTableExt.oApi.fnReloadAjax = function ( oSettings, sNewSource, fnCallback, bStandingRedraw )

@ -1,9 +1,15 @@
/** /**
* Enables filtration delay for keeping the browser more responsive while * Enables filtration delay for keeping the browser more responsive while
* searching for a longer keyword. * searching for a longer keyword.
*
* This can be particularly useful when working with server-side processing,
* where you wouldn't typically want an Ajax request to be made with every key
* press the user makes when searching the table.
*
* @name fnSetFilteringDelay * @name fnSetFilteringDelay
* @summary * @summary Add a key debouce delay to the global filtering input of a table
* @author [Zygimantas Berziunas](http://www.zygimantas.com/), [Allan Jardine](http://www.sprymedia.co.uk/) and _vex_ * @author [Zygimantas Berziunas](http://www.zygimantas.com/),
* [Allan Jardine](http://www.sprymedia.co.uk/) and _vex_
* *
* @example * @example
* $(document).ready(function() { * $(document).ready(function() {
@ -26,7 +32,7 @@ jQuery.fn.dataTableExt.oApi.fnSetFilteringDelay = function ( oSettings, iDelay )
sPreviousSearch = null, sPreviousSearch = null,
anControl = $( 'input', _that.fnSettings().aanFeatures.f ); anControl = $( 'input', _that.fnSettings().aanFeatures.f );
anControl.unbind( 'keyup' ).bind( 'keyup', function() { anControl.unbind( 'keyup search input' ).bind( 'keyup', function() {
var $$this = $this; var $$this = $this;
if (sPreviousSearch === null || sPreviousSearch != anControl.val()) { if (sPreviousSearch === null || sPreviousSearch != anControl.val()) {

@ -1,21 +1,20 @@
/** /**
* This function will restore the order in which data was read into a * This function will restore the order in which data was read into a DataTable
* DataTable (for example from an HTML source). Although you can set * (for example from an HTML source). Although you can set aaSorting to be an
* aaSorting to be an empty array ([ ]) in order to prevent sorting during * empty array (`[ ]`) in order to prevent sorting during initialisation, it can
* initialisation, it can sometimes be useful to restore the original order * sometimes be useful to restore the original order after sorting has already
* after sorting has already occurred - which is exactly what this function * occurred - which is exactly what this function does.
* does.
* *
* @name fnSortNeutral * @name fnSortNeutral
* @summary * @summary Change ordering of the table to its data load order
* @author [Allan Jardine](http://sprymedia.co.uk) * @author [Allan Jardine](http://sprymedia.co.uk)
* *
* @example * @example
* $(document).ready(function() { * $(document).ready(function() {
* var oTable = $('#example').dataTable(); * var table = $('#example').dataTable();
* *
* // Sort in the order that was originally in the HTML * // Sort in the order that was originally in the HTML
* oTable.fnSortNeutral(); * table.fnSortNeutral();
* } ); * } );
*/ */

@ -1,15 +1,21 @@
/** /**
* Redraw the table (i.e. fnDraw) to take account of sorting and filtering, * Redraw the table (i.e. `fnDraw`) to take account of sorting and filtering,
* but retain the current pagination settings. * but retain the current pagination settings.
* *
* DataTables 1.10+ provide the `dt-api draw()` method which has this ability
* built-in (pass the first parameter to the function as `false`). As such this
* method is marked deprecated, but is available for use with legacy version of
* DataTables. Please use the new API if you are used DataTables 1.10 or newer.
*
* @name fnStandingRedraw * @name fnStandingRedraw
* @summary * @summary Redraw the table without altering the paging
* @author Jonathan Hoguet * @author Jonathan Hoguet
* @deprecated
* *
* @example * @example
* $(document).ready(function() { * $(document).ready(function() {
* var oTable = $('.dataTable').dataTable() * var table = $('.dataTable').dataTable()
* oTable.fnStandingRedraw(); * table.fnStandingRedraw();
* } ); * } );
*/ */

@ -1,15 +1,30 @@
/** /**
* When DataTables removes columns from the display (bVisible or * When DataTables removes columns from the display (bVisible or fnSetColumnVis)
* fnSetColumnVis) it removes these elements from the DOM, effecting the index * it removes these elements from the DOM, effecting the index value for the
* value for the column positions. This function converts the visible column * column positions. This function converts the visible column index into a data
* index into a data column index (i.e. all columns regardless of visibility). * column index (i.e. all columns regardless of visibility).
*
* DataTables 1.10+ has this ability built-in through the
* `dt-api column.index()` method. As such this method is marked deprecated, but
* is available for use with legacy version of DataTables.
* *
* @name fnVisibleToColumnIndex * @name fnVisibleToColumnIndex
* @summary * @summary Convert a column visible index to a data index.
* @author [Allan Jardine](http://sprymedia.co.uk) * @author [Allan Jardine](http://sprymedia.co.uk)
* @deprecated
*
* @param {integer} iMatch Column data index to convert to data index
* @returns {integer} Visible column index
* *
* @example * @example
* * var table = $('#example').dataTable( {
* aoColumnDefs: [
* { bVisible: false, aTargets: [1] }
* ]
* } );
*
* // This will show 2
* alert( 'Visible Column 1 data index: '+table.fnVisibleToColumnIndex(1) );
*/ */
jQuery.fn.dataTableExt.oApi.fnVisibleToColumnIndex = function ( oSettings, iMatch ) jQuery.fn.dataTableExt.oApi.fnVisibleToColumnIndex = function ( oSettings, iMatch )

@ -1,20 +1,38 @@
/** /**
* Jump to data * It can be quite useful to jump straight to a page which contains a certain
* piece of data (a user name for example). This plug-in provides exactly that
* ability, searching for a given data parameter from a given column and
* immediately shifting the paging of the table to jump to that point.
*
* If multiple data points match the requested data, the paging will be shifted
* to show the first instance. If there are no matches, the paging will not
* change.
*
* Note that unlike the core DataTables API methods, this plug-in will
* automatically call `dt-api draw()` to redraw the table with the current page
* shown.
* *
* @name page.JumpToData() * @name page.JumpToData()
* @summary * @summary Jump to a page by searching for data from a column
* @author [Allan Jardine](http://sprymedia.co.uk) * @author [Allan Jardine](http://sprymedia.co.uk)
* @requires DataTables 1.10+ * @requires DataTables 1.10+
* *
* @param {*} data Data to search for
* @param {integer} column Column index
* @returns {Api} DataTables API instance
*
* @example * @example
* var table = $('#example').DataTable();
* table.page.jumpToData( 0, "Allan Jardine" ); * table.page.jumpToData( 0, "Allan Jardine" );
*/ */
jQuery.fn.dataTable.Api.register( 'page.jumpToData()', function ( column, data ) { jQuery.fn.dataTable.Api.register( 'page.jumpToData()', function ( data, column ) {
var pos = this.column(column, {order:'current'}).data().indexOf( data ); var pos = this.column(column, {order:'current'}).data().indexOf( data );
if ( pos >= 0 ) { if ( pos >= 0 ) {
var page = Math.floor( pos / this.page.info().length ); var page = Math.floor( pos / this.page.info().length );
this.page( page ).draw( false ); this.page( page ).draw( false );
} }
return this;
} ); } );

@ -1,13 +1,31 @@
/** /**
* Sum the values in a data set. * Fairly simply, this plug-in will take the data from an API result set
* and sum it, returning the summed value. The data can come from any data
* source, including column data, cells or rows.
* *
* @name sum() * @name sum()
* @summary * @summary Sum the values in a data set.
* @author [Allan Jardine](http://sprymedia.co.uk) * @author [Allan Jardine](http://sprymedia.co.uk)
* @requires DataTables 1.10+ * @requires DataTables 1.10+
* *
* @returns {Number} Summed value
*
* @example * @example
* // Simply get the sum of a column
* var table = $('#example').DataTable();
* table.column( 3 ).data().sum(); * table.column( 3 ).data().sum();
*
* @example
* // Insert the sum of a column into the columns footer, for the visible
* // data on each draw
* $('#example').DataTable( {
* drawCallback: function () {
* var api = this.api();
* api.table().footer().to$().html(
* api.column( 4, {page:'current'} ).data().sum()
* );
* }
* } );
*/ */
jQuery.fn.dataTable.Api.register( 'sum()', function () { jQuery.fn.dataTable.Api.register( 'sum()', function () {

Loading…
Cancel
Save