iterator()
Iterate over a result set of table, row, column or cell indexes.
Description
When working with collections of DataTables indexes (such as those placed into the result set by tables()
, rows()
, columns()
and cells()
) you often wish to loop over the indexes and perform some kind of operation on the element that each index points to. While this can easily be accomplished with a for
loop or two, this method can help to simplify and reduce the code by performing those loops for you.
Important: Please note that if you are working with rows()
, columns()
and cells()
, as of DataTables 1.10.6 you may wish to use the rows().every()
, columns().every()
and cells().every()
methods to iterate over each row, column or cell with the context set to that table element, as those methods can simply your code beyond what is possible with this iterator()
method for the majority of cases.
There are a number of loop types available (specified by the type
parameter), and these loop types also effect the parameters that are passed into the callback function:
table
- loop over the context's (i.e. the tables) for the instance- Table settings object
- Loop counter
columns
- loop over each item in the result set- Table settings object
- Result set item
- Loop counter
column
- loop over each table and column in the result set- Table settings object
- Column index
- Table counter (outer)
- Column counter (inner)
column-rows
- loop over each table, column and row in the result set applyingselector-modifier
.- Table settings object
- Column index
- Table counter (outer)
- Column counter (inner)
- Row indexes
rows
- loop over each item in the result set- Table settings object
- Result set item
- Loop counter
row
- loop over each table and row in the result set- Table settings object
- Row index
- Table counter (outer)
- Row counter (inner)
cell
- loop over each table and cell in the result set- Table settings object
- Row index
- Column index
- Table counter (outer)
- Cell counter (inner)
The return from the callback effects the return value from this method:
- If
returns
parameter is set totrue
, a new API instance will be returned with the results contained in its result set. - Otherwise, or
returns
isfalse
:- If the callback returns values a new API instance will be returned
- Otherwise the original instance will be returned for chaining.
This is slightly complex to ensure backwards compatibility which DataTables versions which did not have a returns
parameter and attempted to automatically determine if a new API instance was required or not. To simplify, always set returns
to true
if your method returns a value.
Note as of the callback function is executed in the scope of a DataTables API instance that as the context of only the table described by the first parameter passed into the function. This can make accessing API method for that specific table much easier.
Type
function iterator( [flatten,] type, callback [, returns ] )
- Description:
Iterate over a result set of table, row, column or cell indexes
- Parameters:
Name Type Optional 1 flatten
Yes - default:false If
true
the result set of the returned API instance will be a 1D array (i.e. flattened into a single array). Iffalse
(or not specified) each result will be concatenated to the instance's result set. Note that this is only relevant if you are returning arrays from the callback.2 type
No Iterator type - see above for the options
3 callback
No Callback function that is executed on each iteration. For the parameters passed to the function, please refer to the documentation above. As of this is executed in the scope of an API instance which has its context set to only the table in question.
4 returns
Yes - default:false . Indicate if the callback function will return values or not. If set to
true
a new API instance will be returns with the return values from the callback function in its result set. If not set, orfalse
the original instance will be returned for chaining, if no values are returned by the callback method.- Returns:
Original API instance if the callback returns no result (i.e.
undefined
) or a new API instance with the result set being the results from the callback, in order of execution.
Example
Add a class to each row in a table:
table.rows().iterator('row', function (context, index) {
$(this.row(index).node()).addClass('lowlight');
});