row().child()

Since: DataTables 1.10

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, undefined

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.

Since: 1.10.1

function row().child( showRemove )

Description:

Show or remove and destroy the child rows for the selected row.

Parameters:

Name Type Optional

	Name	Type	Optional
1	`showRemove`	`boolean`	No
	This parameter can be given as `true` or `false`: `true`: Any child rows attached to the parent will be immediately made visible. This is the equivalent of using `row().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 the `row().child.hide()` method, this option removes the rows from DataTables held memory completely. This is the equivalent of using `row().child.remove()`.

showRemove

boolean

This parameter can be given as true or false:

true: Any child rows attached to the parent will be immediately made visible. This is the equivalent of using row().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 the row().child.hide() method, this option removes the rows from DataTables held memory completely. This is the equivalent of using row().child.remove().

Returns:

DataTables.Api

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`	`string`, `node`, `jQuery`, `array`	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 a `tr` element, the `tr` 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 is `tr` 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`	`string`	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 the `tr` 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

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();
});