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
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
|
<?xml version="1.0" encoding="UTF-8" ?>
<dt-type group="dt">
<name>row-selector</name>
<summary>Selector options for rows.</summary>
<description>
<![CDATA[
The DataTables `dt-api rows()` and `dt-api row()` (also optionally `dt-api cells()` and `dt-api cell()`) methods provide the ability to select rows from the table. What rows are selected and how the selector actually operates is controlled by this `dt-type row-selector` data type.
### Options
The row selector can be given in a number of different forms, to make it easy to apply to your data and use case:
* No selector - Select all rows
* `dt-type integer` - Row index selector
* `dt-type string` - ID selector
* `dt-type string` - jQuery selector
* `dt-type node` - This may be one of the following:
* `-tag tr` - table row element
* `-tag td` - table cell element (<span class="since">Since: 1.10.11</span>)
* Any element which has a `data-dt-row` attribute assigned to it, or a parent (<span class="since">Since: 1.10.11</span>). This can be used by extensions such as FixedColumns and Responsive to allow easy row selection.
* `dt-type function` - Function selector (<span class="since">Since: 1.10.3</span>)
* `dt-type jQuery` - jQuery object of row nodes
* `dt-type array` - Array containing any combination of the above options
## No selector
If no selector is given (more specifically `dt-type undefined`), then all rows are selected.
###### Get data for all rows in the table:
```js
var table = $('#example').DataTable();
var allData = table.rows().data();
```
## integer
DataTables stores each row internally with a row index for fast look up of row information. When the selector is given as an integer, this value represents a row index (`dt-api rows().indexes()` / `dt-api row().index()`).
###### Row index 0 data:
```js
var table = $('#example').DataTable();
var data = table.row( 0 ).data();
```
###### Find data using row indexes:
```js
var table = $('#example').DataTable();
// Find indexes of rows which have `Yes` in the second column
var indexes = table.rows().eq( 0 ).filter( function (rowIdx) {
return table.cell( rowIdx, 1 ).data() === 'Yes' ? true : false;
} );
// Add a class to those rows using an index selector
table.rows( indexes )
.nodes()
.to$()
.addClass( 'highlight' );
```
## string - #ID
DataTables row selector is optimised for IDs as it is natural to wish to select rows by unique information. This is distinct from a jQuery selector as DataTables can optimise this selector type so as to not involve the DOM - also allowing an id row selector to operate on rows which have not yet had their DOM nodes created (when using `dt-init deferRender` for extra speed).
With dynamically sourced data, the id assigned to the row is identifier using the `dt-init rowId` option. The data used as the id can be of any value, although it must be unique in the table.
To use an id selector, simply prefix the id value for the row you wish to select with a number sign: `#`. The value that follows is taken as the id. Unlike jQuery this value does __not__ need to be escaped - although this means that an id selector must be used alone (e.g. a class name cannot also be used), it does make is much easier to use for complex data.
###### Select a single row by id:
```js
var table = $('#example').DataTable();
var row = table.row('#row-42');
```
###### Select multiple rows by id:
```js
var table = $('#example').DataTable();
var rows = table.rows( [ '#row-42', '#row-51' ] );
```
## string
When the selector is given as a string, it is treated as a [jQuery selector](http://api.jquery.com/category/selectors/) that operates on the `dt-tag tr` elements in the table. For full information about the options available for jQuery selectors, please refer to the [jQuery selector documentation](http://api.jquery.com/category/selectors/).
Note that just like jQuery selector, is it possible to supply multiple selectors using comma separated notation (i.e. just separate by a comma) when the selector is provided as a string.
###### Select rows by class name:
```js
var table = $('#example').DataTable();
var rows = table.rows('.priority');
```
###### Select rows by two class name selectors:
```js
var table = $('#example').DataTable();
var rows = table.rows('.important, .intermediate');
```
## node
`dt-tag tr` DOM elements can be given as a row selector to select a row in the DataTabels API from that DOM element. This can be useful for getting data from a row, or performing other row based operations, when you have only the DOM node for reference, for example in an event handler.
###### Get the data for a row that was clicked upon:
```js
var table = $('#example').DataTable();
$('#example tbody').on( 'click', 'tr', function () {
var rowData = table.row( this ).data();
// ... do something with `rowData`
} );
```
## Function
< # Version requirement
<
< Using a function as a row selector requires DataTables 1.10.3 or newer.
For complete control over which rows are selected, it is possible to provide a function with logic you've defined to perform the selection. That logic can be as simple or as complex as you wish, performing the selection by simply returning `true` if the row should be included in the selected results and `false` if not.
That can be particularly useful for finding rows based on the data contained in the rows, or based on properties of the nodes.
The function receives three parameters:
1. Row index - see `dt-api row().index()`
2. Row data - see `dt-api row().data()`. Note that this is the original data object for the row, not the rendered data if you are using `dt-init columns.render`
3. Row node - see `dt-api row().node()`. Note that this may be `null` if you are using `dt-init deferRender`.
The function is called once for every row that can be selected, based on the `dt-type selector-modifier` options, which also defines the order of the rows for the called function.
###### Get the data for all rows that have a `first_name` starting with `A`:
```js
var table = $('#example').DataTable();
var names = table
.rows( function ( idx, data, node ) {
return data.first_name.charAt(0) === 'A' ?
true : false;
} )
.data();
```
## jQuery
Very similar to the above `node` type (since a jQuery object is an _array-like_ list of DOM nodes), a jQuery instance can be given as a row selector, with any nodes which are selected by jQuery and match those available in the table selected.
###### Get data from rows in a jQuery instance:
```js
var rows = $('tr.immediate');
var table = $('#example').DataTable();
var rowData = table.rows( rows ).data();
```
###### Use jQuery selectors to get the data in the fifth row of the table:
```js
var rowData1 = table.rows( ':nth-child(5)' ).data();
var rowData2 = table.rows( ':eq(4)' ).data();
```
## array
Any combination of the above options can be given as selector together, providing a method to select multiple rows, or to mix selector types, by simply providing the selector options you want in an array.
###### Get the data for two rows, based on id:
```js
var table = $('#example').DataTable();
var data = table.rows( ['#row-42', '#row-91'] ).data();
```
###### Mix `row-selector` types - id and class selector
```js
var table = $('#example').DataTable();
var data = table.rows( ['#row-42', '.important'] ).data();
```
]]>
</description>
</dt-type>
|
