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
  1. Table settings object
  2. Loop counter
• columns - loop over each item in the result set
  1. Table settings object
  2. Result set item
  3. Loop counter
• column - loop over each table and column in the result set
  1. Table settings object
  2. Column index
  3. Table counter (outer)
  4. Column counter (inner)
• column-rows - loop over each table, column and row in the result set applying selector-modifier.
  1. Table settings object
  2. Column index
  3. Table counter (outer)
  4. Column counter (inner)
  5. Row indexes
• rows - loop over each item in the result set
  1. Table settings object
  2. Result set item
  3. Loop counter
• row - loop over each table and row in the result set
  1. Table settings object
  2. Row index
  3. Table counter (outer)
  4. Row counter (inner)
• cell - loop over each table and cell in the result set
  1. Table settings object
  2. Row index
  3. Column index
  4. Table counter (outer)
  5. Cell counter (inner)

The return from the callback effects the return value from this method:

• If returns parameter is set to true, a new API instance will be returned with the results contained in its result set.
• Otherwise, or returns is false:
  • 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

Example

table.rows().iterator('row', function (context, index) {
	$(this.row(index).node()).addClass('lowlight');
});