1
0
mirror of https://github.com/DataTables/DataTables.git synced 2024-12-02 14:24:11 +01:00

New: API method: _ - the underscore function is the compliment to the $ function introduced early in the 1.9 development cycle. While working with DataTables and the $ I've often wanted the data for the nodes that I'm working with, which means a call to fnGetData and an inner look - not itself bad, but it means an area loop in the external code - so this underscore function is basically the same as $, but rathe rhtan returning an jQuery object of nodes it will return an array of the data source objects for the matched TR elements (important to note that - the selector should resolve TR elements only, other elements don't have DataTables controlled data, and thus will be null in the returned array)

This commit is contained in:
Allan Jardine 2012-01-21 11:08:22 +00:00
parent fbab63b7b5
commit 2aea4da8bc
2 changed files with 126 additions and 2 deletions

View File

@ -4728,7 +4728,7 @@
/**
* Perform a jQuery selector action on the table's TR elements (from the tbody) and
* return the resulting jQuery object.
* @param {string} sSelector jQuery selector
* @param {string|node|jQuery} sSelector jQuery selector or node collection to act on
* @param {object} [oOpts] Optional parameters for modifying the rows to be included
* @param {string} [oOpts.filter=none] Select TR elements that meet the current filter
* criterion ("applied") or all TR elements (i.e. no filter).
@ -4832,6 +4832,68 @@
};
/**
* Almost identical to $ in operation, but in this case returns the data for the matched
* rows - as such, the jQuery selector used should match TR elements rather than any
* decendents. The data returned is the original data array/object that was used to create
* the row (or a generated array if from a DOM source).
*
* This method is often useful incombination with $ where both functions are given the
* same parameters and the array indexes will match identically.
* @param {string|node|jQuery} sSelector jQuery selector or node collection to act on
* @param {object} [oOpts] Optional parameters for modifying the rows to be included
* @param {string} [oOpts.filter=none] Select TR elements that meet the current filter
* criterion ("applied") or all TR elements (i.e. no filter).
* @param {string} [oOpts.order=current] Order of the TR elements in the processed array.
* Can be either 'current', whereby the current sorting of the table is used, or
* 'original' whereby the original order the data was read into the table is used.
* @param {string} [oOpts.page=all] Limit the selection to the currently displayed page
* ("current") or not ("all"). If 'current' is given, then order is assumed to be
* 'current' and filter is 'applied', regardless of what they might be given as.
* @returns {array} Data for the matched TR elements. If any elements, as a result of the
* selector, were not TR elements in the DataTable, they will have a null entry in the
* array.
*
* @example
* $(document).ready(function() {
* var oTable = $('#example').dataTable();
*
* // Get the data from the first row in the table
* var data = oTable._('tr:first');
*
* // Do something useful with the data
* alert( "First cell is: "+data[0] );
* } );
*
* @example
* $(document).ready(function() {
* var oTable = $('#example').dataTable();
*
* // Filter to 'Webkit' and get all data for
* oTable.fnFilter('Webkit');
* var data = oTable._('tr', {"filter": "applied"});
*
* // Do something with the data
* alert( data.length+" rows matched the filter" );
* } );
*/
this._ = function ( sSelector, oOpts )
{
var aOut = [];
var i, iLen, iIndex;
var oSettings = _fnSettingsFromNode( this[DataTable.ext.iApiIndex] );
var aTrs = this.$( sSelector, oOpts );
for ( i=0, iLen=aTrs.length ; i<iLen ; i++ )
{
iIndex = _fnNodeToDataIndex( oSettings, aTrs[i] );
aOut.push( iIndex!==null ? oSettings.aoData[iIndex]._aData : null );
}
return aOut;
};
/**
* Add a single new row or multiple rows of data to the table. Please note
* that this is suitable for client-side processing only - if you are using

View File

@ -3,7 +3,7 @@
/**
* Perform a jQuery selector action on the table's TR elements (from the tbody) and
* return the resulting jQuery object.
* @param {string} sSelector jQuery selector
* @param {string|node|jQuery} sSelector jQuery selector or node collection to act on
* @param {object} [oOpts] Optional parameters for modifying the rows to be included
* @param {string} [oOpts.filter=none] Select TR elements that meet the current filter
* criterion ("applied") or all TR elements (i.e. no filter).
@ -107,6 +107,68 @@ this.$ = function ( sSelector, oOpts )
};
/**
* Almost identical to $ in operation, but in this case returns the data for the matched
* rows - as such, the jQuery selector used should match TR elements rather than any
* decendents. The data returned is the original data array/object that was used to create
* the row (or a generated array if from a DOM source).
*
* This method is often useful incombination with $ where both functions are given the
* same parameters and the array indexes will match identically.
* @param {string|node|jQuery} sSelector jQuery selector or node collection to act on
* @param {object} [oOpts] Optional parameters for modifying the rows to be included
* @param {string} [oOpts.filter=none] Select TR elements that meet the current filter
* criterion ("applied") or all TR elements (i.e. no filter).
* @param {string} [oOpts.order=current] Order of the TR elements in the processed array.
* Can be either 'current', whereby the current sorting of the table is used, or
* 'original' whereby the original order the data was read into the table is used.
* @param {string} [oOpts.page=all] Limit the selection to the currently displayed page
* ("current") or not ("all"). If 'current' is given, then order is assumed to be
* 'current' and filter is 'applied', regardless of what they might be given as.
* @returns {array} Data for the matched TR elements. If any elements, as a result of the
* selector, were not TR elements in the DataTable, they will have a null entry in the
* array.
*
* @example
* $(document).ready(function() {
* var oTable = $('#example').dataTable();
*
* // Get the data from the first row in the table
* var data = oTable._('tr:first');
*
* // Do something useful with the data
* alert( "First cell is: "+data[0] );
* } );
*
* @example
* $(document).ready(function() {
* var oTable = $('#example').dataTable();
*
* // Filter to 'Webkit' and get all data for
* oTable.fnFilter('Webkit');
* var data = oTable._('tr', {"filter": "applied"});
*
* // Do something with the data
* alert( data.length+" rows matched the filter" );
* } );
*/
this._ = function ( sSelector, oOpts )
{
var aOut = [];
var i, iLen, iIndex;
var oSettings = _fnSettingsFromNode( this[DataTable.ext.iApiIndex] );
var aTrs = this.$( sSelector, oOpts );
for ( i=0, iLen=aTrs.length ; i<iLen ; i++ )
{
iIndex = _fnNodeToDataIndex( oSettings, aTrs[i] );
aOut.push( iIndex!==null ? oSettings.aoData[iIndex]._aData : null );
}
return aOut;
};
/**
* Add a single new row or multiple rows of data to the table. Please note
* that this is suitable for client-side processing only - if you are using