1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
|
<?xml version="1.0" encoding="UTF-8" ?>
<dt-api group="utility">
<name>iterator()</name>
<summary>Iterate over a result set of table, row, column or cell indexes</summary>
<since>1.10</since>
<type type="function">
<signature>iterator( [flatten,] type, callback [, returns ] )</signature>
<description>Iterate over a result set of table, row, column or cell indexes</description>
<parameter name="flatten" type="boolean" default="false">If `true` the result set of the returned API instance will be a 1D array (i.e. flattened into a single array). If `false` (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.</parameter>
<parameter name="type" type="string">Iterator type - see above for the options</parameter>
<parameter name="callback" type="function">Callback function that is executed on each iteration. For the parameters passed to the function, please refer to the documentation above. As of <span class="since">1.10.3</span> this is executed in the scope of an API instance which has its context set to only the table in question.</parameter>
<parameter name="returns" type="boolean" default="false"><span class="since">1.10.4</span>. 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, or `false` the original instance will be returned for chaining, if no values are returned by the callback method.</parameter>
<returns type="DataTables.Api">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.</returns>
</type>
<description>
When working with collections of DataTables indexes (such as those placed into the result set by `dt-api tables()`, `dt-api rows()`, `dt-api columns()` and `dt-api cells()`) you often wish to loop over the indexes an 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 `dt-api rows()`, `dt-api columns()` and `dt-api cells()`, as of DataTables 1.10.6 you may wish to use the `dt-api rows().every()`, `dt-api columns().every()` and `dt-api 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 `dt-api 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 `dt-type 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 <span class="since">DataTables 1.10.3</span> 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.
</description>
<example title="Add a class to each row in a table"><![CDATA[
table.rows().iterator( 'row', function ( context, index ) {
$( this.row( index ).node() ).addClass( 'lowlight' );
} );
]]></example>
</dt-api>
|
