From fa79071454d06c006898b42cef7cd2b380c88434 Mon Sep 17 00:00:00 2001 From: Allan Jardine Date: Thu, 31 May 2012 18:49:19 +0100 Subject: [PATCH] Add API methods from DataTables plug-ins page (dropping the ones which are now provided for by the built in methods (mainly $ and _). Some examples still needed and possibly summaries --- api/fnAddDataAndDisplay.js | 54 ++++++++++++++++++++++++++++++ api/fnAddTr.js | 41 +++++++++++++++++++++++ api/fnColumnIndexToVisible.js | 17 ++++++++++ api/fnDataUpdate.js | 17 ++++++++++ api/fnDisplayRow.js | 41 +++++++++++++++++++++++ api/fnDisplayStart.js | 25 ++++++++++++++ api/fnFakeRowspan.js | 60 +++++++++++++++++++++++++++++++++ api/fnFilterAll.js | 34 +++++++++++++++++++ api/fnFilterClear.js | 45 +++++++++++++++++++++++++ api/fnFilterOnReturn.js | 30 +++++++++++++++++ api/fnFindCellRowIndexes.js | 47 ++++++++++++++++++++++++++ api/fnFindCellRowNodes.js | 46 ++++++++++++++++++++++++++ api/fnGetAdjacentTr.js | 47 ++++++++++++++++++++++++++ api/fnGetColumnData.js | 50 ++++++++++++++++++++++++++++ api/fnGetColumnIndex.js | 25 ++++++++++++++ api/fnGetHiddenNodes.js | 26 +++++++++++++++ api/fnGetTd.js | 46 ++++++++++++++++++++++++++ api/fnGetTds.js | 54 ++++++++++++++++++++++++++++++ api/fnLengthChange.js | 40 ++++++++++++++++++++++ api/fnMultiFilter.js | 42 ++++++++++++++++++++++++ api/fnPagingInfo.js | 29 ++++++++++++++++ api/fnProcessingIndicator.js | 21 ++++++++++++ api/fnReloadAjax.js | 62 +++++++++++++++++++++++++++++++++++ api/fnSetFilteringDelay.js | 42 ++++++++++++++++++++++++ api/fnSortNeutral.js | 35 ++++++++++++++++++++ api/fnStandingRedraw.js | 27 +++++++++++++++ api/fnVisibleToColumnIndex.js | 16 +++++++++ 27 files changed, 1019 insertions(+) create mode 100644 api/fnAddDataAndDisplay.js create mode 100644 api/fnAddTr.js create mode 100644 api/fnColumnIndexToVisible.js create mode 100644 api/fnDataUpdate.js create mode 100644 api/fnDisplayRow.js create mode 100644 api/fnDisplayStart.js create mode 100644 api/fnFakeRowspan.js create mode 100644 api/fnFilterAll.js create mode 100644 api/fnFilterClear.js create mode 100644 api/fnFilterOnReturn.js create mode 100644 api/fnFindCellRowIndexes.js create mode 100644 api/fnFindCellRowNodes.js create mode 100644 api/fnGetAdjacentTr.js create mode 100644 api/fnGetColumnData.js create mode 100644 api/fnGetColumnIndex.js create mode 100644 api/fnGetHiddenNodes.js create mode 100644 api/fnGetTd.js create mode 100644 api/fnGetTds.js create mode 100644 api/fnLengthChange.js create mode 100644 api/fnMultiFilter.js create mode 100644 api/fnPagingInfo.js create mode 100644 api/fnProcessingIndicator.js create mode 100644 api/fnReloadAjax.js create mode 100644 api/fnSetFilteringDelay.js create mode 100644 api/fnSortNeutral.js create mode 100644 api/fnStandingRedraw.js create mode 100644 api/fnVisibleToColumnIndex.js diff --git a/api/fnAddDataAndDisplay.js b/api/fnAddDataAndDisplay.js new file mode 100644 index 0000000..a19048d --- /dev/null +++ b/api/fnAddDataAndDisplay.js @@ -0,0 +1,54 @@ +/** + * 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 + * with the added TR element and it's index in aoData such that you 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 + * 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). + * @name fnAddDataAndDisplay + * @author Allan Jardine + * + * @example + * $(document).ready(function() { + * var oTable = $('#example').dataTable(); + * oTable.fnAddDataAndDisplay( [ 1, 2, 3, 4, 5, ... ] ); + * } ); + */ + +$.fn.dataTableExt.oApi.fnAddDataAndDisplay = function ( oSettings, aData ) +{ + /* Add the data */ + var iAdded = this.oApi._fnAddData( oSettings, aData ); + var nAdded = oSettings.aoData[ iAdded ].nTr; + + /* Need to re-filter and re-sort the table to get positioning correct, not perfect + * as this will actually redraw the table on screen, but the update should be so fast (and + * possibly not alter what is already on display) that the user will not notice + */ + this.oApi._fnReDraw( oSettings ); + + /* Find it's position in the table */ + var iPos = -1; + for( var i=0, iLen=oSettings.aiDisplay.length ; i= 0 ) + { + oSettings._iDisplayStart = ( Math.floor(i / oSettings._iDisplayLength) ) * oSettings._iDisplayLength; + this.oApi._fnCalculateEnd( oSettings ); + } + + this.oApi._fnDraw( oSettings ); + return { + "nTr": nAdded, + "iPos": iAdded + }; +}; diff --git a/api/fnAddTr.js b/api/fnAddTr.js new file mode 100644 index 0000000..8a9d66e --- /dev/null +++ b/api/fnAddTr.js @@ -0,0 +1,41 @@ +/** + * Take a TR element and add it to a DataTables table. Useful for maintaining + * custom classes and other attributes. + * @name fnAddTr + * @author Allan Jardine + * + * @example + * + */ + +$.fn.dataTableExt.oApi.fnAddTr = function ( oSettings, nTr, bRedraw ) { + if ( typeof bRedraw == 'undefined' ) + { + bRedraw = true; + } + + var nTds = nTr.getElementsByTagName('td'); + if ( nTds.length != oSettings.aoColumns.length ) + { + alert( 'Warning: not adding new TR - columns and TD elements must match' ); + return; + } + + var aData = []; + for ( var i=0 ; iAllan Jardine + * + * @example + * + */ + +$.fn.dataTableExt.oApi.fnColumnIndexToVisible = function ( oSettings, iMatch ) +{ + return oSettings.oApi._fnColumnIndexToVisible( oSettings, iMatch ); +}; diff --git a/api/fnDataUpdate.js b/api/fnDataUpdate.js new file mode 100644 index 0000000..895d7e3 --- /dev/null +++ b/api/fnDataUpdate.js @@ -0,0 +1,17 @@ +/** + * Update the internal data for a TR element based on what is used in the + * DOM. You will likely want to call fnDraw() after this function. + * @name fnColumnIndexToVisible + * @author Lior Gerson + * + * @example + * + */ + +$.fn.dataTableExt.oApi.fnDataUpdate = function ( oSettings, nRowObject, iRowIndex ) +{ + $(nRowObject).find("TD").each( function(i) { + var iColIndex = oSettings.oApi._fnVisibleToColumnIndex( oSettings, i ); + oSettings.oApi._fnSetCellData( oSettings, iRowIndex, iColIndex, $(this).html() ); + } ); +}; diff --git a/api/fnDisplayRow.js b/api/fnDisplayRow.js new file mode 100644 index 0000000..a512f26 --- /dev/null +++ b/api/fnDisplayRow.js @@ -0,0 +1,41 @@ +/** + * Take a TR element and alter the table's paging to show the TR in question. + * @name fnDisplayRow + * @author Allan Jardine + * + * @example + * $(document).ready(function() { + * // Display the 21st row in the table + * var oTable = $('#example').dataTable(); + * oTable.fnDisplayRow( oTable.fnGetNodes()[20] ); + * } ); + */ + +$.fn.dataTableExt.oApi.fnDisplayRow = function ( oSettings, nRow ) +{ + // Account for the "display" all case - row is already displayed + if ( oSettings._iDisplayLength == -1 ) + { + return; + } + + // Find the node in the table + var iPos = -1; + for( var i=0, iLen=oSettings.aiDisplay.length ; i= 0 ) + { + oSettings._iDisplayStart = ( Math.floor(i / oSettings._iDisplayLength) ) * oSettings._iDisplayLength; + this.oApi._fnCalculateEnd( oSettings ); + } + + this.oApi._fnDraw( oSettings ); +}; diff --git a/api/fnDisplayStart.js b/api/fnDisplayStart.js new file mode 100644 index 0000000..da36e9f --- /dev/null +++ b/api/fnDisplayStart.js @@ -0,0 +1,25 @@ +/** + * Set the point at which DataTables will start it's display of data in the + * table. + * @name fnDisplayStart + * @author Allan Jardine + * + * @example + * + */ + +$.fn.dataTableExt.oApi.fnDisplayStart = function ( oSettings, iStart, bRedraw ) +{ + if ( typeof bRedraw == 'undefined' ) + { + bRedraw = true; + } + + oSettings._iDisplayStart = iStart; + oSettings.oApi._fnCalculateEnd( oSettings ); + + if ( bRedraw ) + { + oSettings.oApi._fnDraw( oSettings ); + } +}; diff --git a/api/fnFakeRowspan.js b/api/fnFakeRowspan.js new file mode 100644 index 0000000..768e559 --- /dev/null +++ b/api/fnFakeRowspan.js @@ -0,0 +1,60 @@ +/** + * 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. + * Note - this plug-in currently only operates correctly with + * server-side processing. + * @name fnFakeRowspan + * @author Fredrik Wendel + * + * @example + * $('#example').dataTable().fnFakeRowspan(3); + */ + +$.fn.dataTableExt.oApi.fnFakeRowspan = function ( oSettings, iColumn, bCaseSensitive ) { + /* Fail silently on missing/errorenous parameter data. */ + if (isNaN(iColumn)) { + return false; + } + + if (iColumn < 0 || iColumn > oSettings.aoColumns.length-1) { + alert ('Invalid column number choosen, must be between 0 and ' + (oSettings.aoColumns.length-1)); + return false; + } + + var oSettings = oSettings, + iColumn = iColumn, + bCaseSensitive = (typeof(bCaseSensitive) != 'boolean' ? true : bCaseSensitive); + + oSettings.aoDrawCallback.push({ "fn": fakeRowspan, "sName": "fnFakeRowspan" }); + + function fakeRowspan () { + var firstOccurance = null, + value = null, + rowspan = 0; + jQuery.each(oSettings.aoData, function (i, oData) { + var val = oData._aData[iColumn], + cell = oData.nTr.childNodes[iColumn]; + /* Use lowercase comparison if not case-sensitive. */ + if (!bCaseSensitive) { + val = val.toLowerCase(); + } + /* Reset values on new cell data. */ + if (val != value) { + value = val; + firstOccurance = cell; + rowspan = 0; + } + + if (val == value) { + rowspan++; + } + + if (firstOccurance !== null && val == value && rowspan > 1) { + oData.nTr.removeChild(cell); + firstOccurance.rowSpan = rowspan; + } + }); + } + + return this; +}; diff --git a/api/fnFilterAll.js b/api/fnFilterAll.js new file mode 100644 index 0000000..c44936a --- /dev/null +++ b/api/fnFilterAll.js @@ -0,0 +1,34 @@ +/** + * Apply the same filter to all DataTable instances on a particular page. The + * function call exactly matches that used by fnFilter() so regular expression + * and individual column sorting can be used. + * @name fnFilterAll + * @author Kristoffer Karlström + * + * @example + * $(document).ready(function() { + * var oTable = $(".dataTable").dataTable(); + * + * $("#search").keyup( function () { + * // Filter on the column (the index) of this element + * oTable.fnFilterAll(this.value); + * } ); + * }); + */ + +$.fn.dataTableExt.oApi.fnFilterAll = function(oSettings, sInput, iColumn, bRegex, bSmart) { + if ( typeof bRegex == 'undefined' ) { + bRegex = false; + } + + if ( typeof bSmart == 'undefined' ) { + bSmart = true; + } + + for (var i in this.dataTableSettings) { + jQuery.fn.dataTableExt.iApiIndex = i; + this.fnFilter(sInput, iColumn, bRegex, bSmart); + } + + jQuery.fn.dataTableExt.iApiIndex = 0; +}; diff --git a/api/fnFilterClear.js b/api/fnFilterClear.js new file mode 100644 index 0000000..8d53b7f --- /dev/null +++ b/api/fnFilterClear.js @@ -0,0 +1,45 @@ +/** + * Remove all filtering that has been applied to a DataTable, be it column + * based filtering or global filtering. + * @name fnFilterClear + * @author Allan Jardine + * + * @example + * $(document).ready(function() { + * var oTable = $('#example').dataTable(); + * + * // Perform a filter + * oTable.fnFilter('Win'); + * oTable.fnFilter('Trident', 0); + * + * // Remove all filtering + * oTable.fnFilterClear(); + * } ); + */ + +$.fn.dataTableExt.oApi.fnFilterClear = function ( oSettings ) +{ + /* Remove global filter */ + oSettings.oPreviousSearch.sSearch = ""; + + /* Remove the text of the global filter in the input boxes */ + if ( typeof oSettings.aanFeatures.f != 'undefined' ) + { + var n = oSettings.aanFeatures.f; + for ( var i=0, iLen=n.length ; iJon Ranes + * + * @example + * $(document).ready(function() { + * $('.dataTable').dataTable().fnFilterOnReturn(); + * } ); + */ + +jQuery.fn.dataTableExt.oApi.fnFilterOnReturn = function (oSettings) { + var _that = this; + + this.each(function (i) { + $.fn.dataTableExt.iApiIndex = i; + var $this = this; + var anControl = $('input', _that.fnSettings().aanFeatures.f); + anControl.unbind('keyup').bind('keypress', function (e) { + if (e.which == 13) { + $.fn.dataTableExt.iApiIndex = i; + _that.fnFilter(anControl.val()); + } + }); + return this; + }); + return this; +}; diff --git a/api/fnFindCellRowIndexes.js b/api/fnFindCellRowIndexes.js new file mode 100644 index 0000000..81caa7d --- /dev/null +++ b/api/fnFindCellRowIndexes.js @@ -0,0 +1,47 @@ +/** + * Search through a table looking for a given string (optionally the search + * can be restricted to a single column). The return value is an array with + * the data indexes (from DataTables' internal data store) for any rows which + * match. + * @name fnFindCellRowIndexes + * @author Allan Jardine + * + * @example + * $(document).ready(function() { + * var oTable = $('#example').dataTable(); + * + * var a = oTable.fnFindCellRowIndexes( '1.7' ); // Search all columns + * + * var b = oTable.fnFindCellRowIndexes( '1.7', 3 ); // Search only column 3 + * } ); + */ + +$.fn.dataTableExt.oApi.fnFindCellRowIndexes = function ( oSettings, sSearch, iColumn ) +{ + var + i,iLen, j, jLen, + aOut = [], aData; + + for ( i=0, iLen=oSettings.aoData.length ; iAllan Jardine + * + * @example + * $(document).ready(function() { + * var oTable = $('#example').dataTable(); + * + * var a = oTable.fnFindCellRowNodes( '1.7' ); // Search all columns + * + * var b = oTable.fnFindCellRowNodes( '1.7', 3 ); // Search only column 3 + * } ); + */ + +$.fn.dataTableExt.oApi.fnFindCellRowNodes = function ( oSettings, sSearch, iColumn ) +{ + var + i,iLen, j, jLen, + aOut = [], aData; + + for ( i=0, iLen=oSettings.aoData.length ; iAllan Jardine + * + * @example + * $(document).ready(function() { + * var oTable = $('#example').dataTable(); + * + * var n1 = $('#example tbody tr:eq(2)')[0]; + * var nNext = oTable.fnGetAdjacentTr( n1 ); + * var nPrev = oTable.fnGetAdjacentTr( n1, false ); + * } ); + */ + +$.fn.dataTableExt.oApi.fnGetAdjacentTr = function ( oSettings, nTr, bNext ) +{ + /* Find the node's position in the aoData store */ + var iCurrent = oSettings.oApi._fnNodeToDataIndex( oSettings, nTr ); + + /* Convert that to a position in the display array */ + var iDisplayIndex = $.inArray( iCurrent, oSettings.aiDisplay ); + if ( iDisplayIndex == -1 ) + { + /* Not in the current display */ + return null; + } + + /* Move along the display array as needed */ + iDisplayIndex += (typeof bNext=='undefined' || bNext) ? 1 : -1; + + /* Check that it within bounds */ + if ( iDisplayIndex < 0 || iDisplayIndex >= oSettings.aiDisplay.length ) + { + /* There is no next/previous element */ + return null; + } + + /* Return the target node from the aoData store */ + return oSettings.aoData[ oSettings.aiDisplay[ iDisplayIndex ] ].nTr; +}; diff --git a/api/fnGetColumnData.js b/api/fnGetColumnData.js new file mode 100644 index 0000000..b2cc88d --- /dev/null +++ b/api/fnGetColumnData.js @@ -0,0 +1,50 @@ +/** + * Return an array of table values from a particular column, with various + * filtering options. + * @name fnGetColumnData + * @author Benedikt Forchhammer + * + * @example + * + */ + +jQUery.fn.dataTableExt.oApi.fnGetColumnData = function ( oSettings, iColumn, bUnique, bFiltered, bIgnoreEmpty ) { + // check that we have a column id + if ( typeof iColumn == "undefined" ) return []; + + // by default we only wany unique data + if ( typeof bUnique == "undefined" ) bUnique = true; + + // by default we do want to only look at filtered data + if ( typeof bFiltered == "undefined" ) bFiltered = true; + + // by default we do not wany to include empty values + if ( typeof bIgnoreEmpty == "undefined" ) bIgnoreEmpty = true; + + // list of rows which we're going to loop through + var aiRows; + + // use only filtered rows + if (bFiltered == true) aiRows = oSettings.aiDisplay; + // use all rows + else aiRows = oSettings.aiDisplayMaster; // all row numbers + + // set up data array + var asResultData = new Array(); + + for (var i=0,c=aiRows.length; i -1) continue; + + // else push the value onto the result data array + else asResultData.push(sValue); + } + + return asResultData; +}; diff --git a/api/fnGetColumnIndex.js b/api/fnGetColumnIndex.js new file mode 100644 index 0000000..0182f40 --- /dev/null +++ b/api/fnGetColumnIndex.js @@ -0,0 +1,25 @@ +/** + * Maintenance of web-sites can often cause unexpected headaches, particularly + * if the hardcoded index of an array (the columns in a DataTables instance) + * needs to change due to an added or removed column. This plug-in function + * will match a given string to the title of a column in the table and return + * the column index, helping to overcome this problem. + * @name fnGetColumnIndex + * @author Michael Ross + * + * @example + * + */ + +$.fn.dataTableExt.oApi.fnGetColumnIndex = function ( oSettings, sCol ) +{ + var cols = oSettings.aoColumns; + for ( var x=0, xLen=cols.length ; xAllan Jardine + */ + +$.fn.dataTableExt.oApi.fnGetHiddenNodes = function ( oSettings ) +{ + /* Note the use of a DataTables 'private' function thought the 'oApi' object */ + var anNodes = this.oApi._fnGetTrNodes( oSettings ); + var anDisplay = $('tbody tr', oSettings.nTable); + + /* Remove nodes which are being displayed */ + for ( var i=0 ; i