row().child()
Get / set the child rows of the selected main table row.
Description
DataTables has the ability to show child rows for each row (termed a "parent row" in this documentation to distinguish from the child rows). This child rows are attached to each parent row, and can be used, for example, to provide extra information about the parent row, or an editing form. The child rows will always be placed immediately after a parent row (if the child rows are designated to be visible, using the row().child.show()
method), regardless of ordering, search terms applied to the table etc. If a parent row is not available in the DataTables' current view, the child rows will not be visible either.
The contents of the child rows are entirely independent of the main table (other than their position in the document). Ordering, searching etc applied to the table has no effect on the order of the child rows. Each child row is typically contains a single cell, which has a colspan
attribute set to span the full table width, so the content of the cell covers the full table width. However, it is also possible to pass in a tr
element which has multiple cells (one for each column in the table) to show the child row data in the same column structure as the main table.
A parent row can have one or more child rows attached to it at a time. However, child rows are treated as one entity by the API, which is to say that they can either all be shown, or all hidden.
Additionally, a child row can persist after they have been hidden, allowing them to quickly and easily be shown again in future if required. The act of hiding a row is performed using row().child.hide()
. A Child row can also be destroyed (hidden and its allocated memory released) using row().child.remove()
or this method with false
as the only parameter, if the child row is no longer required.
Note that this method does not automatically make the added child row visible when creating a child row. Use the row().child().show()
chained method (or row().child.show()
as required).
Types
function row().child()
- Description:
Get the child row(s) that have been set for a parent row
- Returns:
jQuery object with the child rows for the parent row in its result set, or
undefined
if there are no child rows set for the parent yet.
function row().child( showRemove )
- Description:
Show or remove and destroy the child rows for the selected row.
- Parameters:
Name Type Optional 1 showRemove
No This parameter can be given as
true
orfalse
:true
: Any child rows attached to the parent will be immediately made visible. This is the equivalent of usingrow().child.show()
.false
: If the parent row has any children currently attached to it (whether shown or not) this method will destroy those child rows, removing them from the DOM if appropriate. Unlike with therow().child.hide()
method, this option removes the rows from DataTables held memory completely. This is the equivalent of usingrow().child.remove()
.
- Returns:
DataTables API instance
function row().child( data [, className ] )
- Description:
Set the data to show in the child row(s). Note that calling this method will replace any child rows which are already attached to the parent row.
- Parameters:
Name Type Optional 1 data
No The data to be shown in the child row can be given in multiple different ways:
string
- As a string, a single child row is create and the data is inserted into a single cell in that child row.node
- As atr
element, thetr
element is used as the child row. This can be useful it you wish to define multiple columns in the child row.jQuery
- A jQuery object with nodes to be added. If there are multiple elements in the jQuery result set, they are added as multiple rows. If the node istr
element it is treated a the child row, otherwise a row and cell are automatically created and the node from the jQuery result set inserted into it.array
- Multiple child rows can be added at a single time by passing any of the above options in as an array. For example you might pass in an array with two string elements in it to create two child rows with the string content used for each.
2 className
Yes - default: Class name that is added to the
td
cell node(s) of the child row(s) when DataTables generates the child row. As of 1.10.1 it is also added to thetr
row node of the child row(s).This is useful to add additional styling information to the child row to indicate that while it is part of the table's data, it is additional information beyond what is normally shown.
Please note that if a
node
, or jQuery object that contains nodes, is given in the first parameter the class name is not automatically added - it is assumed that the existing row is already configured as required.- Returns:
DataTables API instance
Examples
Show / hide a row based on its current state, adding the row content as needed.:
var table = new DataTable('#myTable');
$('#example tbody').on('click', 'td.details-control', function () {
var tr = $(this).parents('tr');
var row = table.row(tr);
if (row.child.isShown()) {
// This row is already open - close it
row.child.hide();
tr.removeClass('shown');
}
else {
// Open this row (the format() function would return the data to be shown)
row.child(format(row.data())).show();
tr.addClass('shown');
}
});
Create multiple child rows for a single row in the table - the first visible row.:
var table = new DataTable('#myTable');
table
.row(':eq(0)')
.child(['First child row', 'Second child row', 'Third child row'])
.show();
Add a child row to all rows, passing in a jQuery created tr
element and show all child rows:
var table = new DataTable('#myTable');
table.rows().every(function () {
this.child(
$(
'<tr>' +
'<td>' +
rowIdx +
'.1</td>' +
'<td>' +
rowIdx +
'.2</td>' +
'<td>' +
rowIdx +
'.3</td>' +
'<td>' +
rowIdx +
'.4</td>' +
'</tr>'
)
).show();
});