columns.data

Since: DataTables 1.10

Set the data source for the column from the rows data object / array.

Description

This property can be used to read and write data to and from any data source property, including deeply nested objects / properties. data can be given in a number of different ways which affect its behaviour as documented below.

The data that is resolved for a data point (between this option and columns.render) will be used by DataTables for the requested data, with three special cases:

undefined - the same as if not present!
null - If columns.render is used, the data passed to the rendering function will be the original data source for the row. If there is no renderer the columns.defaultContent value will be used. If there is no default content specified, for display data the source object for that row will be used; null will be used for all other data types.
function - the function will be executed and the returned value used. As of DataTables 1.10.1 the function will be executed in the same scope as the data object for the row. The result of this is that an object instance can be used as the data source for a row.

As of DataTables 2, the resolved data can be a DOM node. This is useful for cases when you are working with external frameworks which generate DOM nodes themselves. In such cases, don't use DataTables columns.render option to customise the content of the cells - rather do it with whatever is creating the cells in the first place.

Note that data is both a getter and setter option. If you just require formatting of data for output, you will likely want to use columns.render which is simply a getter and thus much simpler to use!

As of DataTables 1.10.3 this option can be used with a DOM sourced data to instruct DataTables where to write the data read for each column to in a data source object. By default DataTables will store the data in an array, but using this option you can provide object property names which describe the structure of the object to use (example).

Types

integer

Description:: Treated as an array index for the data source. This is the default that DataTables uses (incrementally increased for each column).

string

Description:

Read and write an object property to and from the data source. There are three 'special' options that can be used in the string to alter how DataTables reads the data from the source object:

. - Dotted Javascript notation. Just as you use a . in Javascript to read from nested objects, so to can the options specified in data. For example: browser.version or browser.name. If your object parameter name contains a period, use \\ to escape it - i.e. first\\.name.
[] - Array notation. DataTables can automatically combine data from an array source, joining the data with the characters provided between the two brackets. For example: name[, ] would provide a comma-space separated list from the source array. If no characters are provided between the brackets, the original array source is returned.
() - Function notation. Adding () to the end of a parameter will execute a function of the name given. For example: browser() for a simple function on the data source, browser.version() for a function in a nested property or even browser().version to get an object property if the function called returns an object. Note that function notation is recommended for use in render rather than data as it is much simpler to use as a renderer.

null

Description:

Use the original data source for the row rather than plucking data directly from it. This action has effects on two other initialisation options:

columns.defaultContent - When null is given as the data option and defaultContent is specified for the column, the value defined by defaultContent will be used for the cell.
columns.render - When null is used for the data option and the render option is specified for the column, the whole data source for the row is used for the renderer.

object

Description:

Use different data for the different data types requested by DataTables (filter, display, type or sort). The property names of the object is the data type the property refers to and the value can defined using an integer, string or function using the same rules as columns.data normally does. Note that an _ option must be specified. This is the default value to use if you haven't specified a value for the data type requested by DataTables.

As an example you might use:

"data": {
    "_": "phone",
    "filter": "phone_filter",
    "display": "phone_display"
}

function data( row, type, set, meta )

Description:

The function given will be executed whenever DataTables needs to set or get the data for a cell in the column.

This function might be called multiple times, as DataTables will call it for the different data types that it needs - sorting, filtering and display.

Please note that DataTables will call the function as a setter when a new row is added only when the row's data is read from the DOM (i.e. the table is initialised on a pre-populated HTML table). The function is not called as setter when the data is source from Javascript or Ajax under the assumption that the data is already in the format required.

Parameters:

	Name	Type	Optional
1	`row`	`array`, `object`	No
	The data for the whole row
2	`type`	`string`	No
	The data type requested for the cell. Predefined types are `filter`, `display`, `type` or `sort`.
3	`set`	`Any`	No
	Value to set if the `type` parameter is `set`. Otherwise, `undefined`.
4	`meta`	`object`	No
	Since 1.10.1: An object that contains additional information about the cell being requested. This object contains the following properties: `row` - The row index for the requested cell. See `row().index()`. `col` - The column index for the requested cell. See `column().index()`. `settings` - The `DataTables.Settings` object for the table in question. This can be used to obtain an API instance if required.

Returns:

The return value from the function is not required when 'set' is the type of call, but otherwise the return is what will be used for the data requested.

Default

Takes the index value of the column automatically

Examples

Read table data from objects:

// JSON structure for each row in this example:
//   {
//      "engine": {value},
//      "browser": {value},
//      "platform": {value},
//      "version": {value},
//      "grade": {value}
//   }
new DataTable('#myTable', {
	ajaxSource: 'sources/objects.txt',
	columns: [
		{ data: 'engine' },
		{ data: 'browser' },
		{ data: 'platform' },
		{ data: 'version' },
		{ data: 'grade' }
	]
});

Read information from deeply nested objects:

// JSON structure for each row:
//   {
//      "engine": {value},
//      "browser": {value},
//      "platform": {
//         "inner": {value}
//      },
//      "details": [
//         {value}, {value}
//      ]
//   }
new DataTable('#myTable', {
	ajaxSource: 'sources/deep.txt',
	columns: [
		{ data: 'engine' },
		{ data: 'browser' },
		{ data: 'platform.inner' },
		{ data: 'details.0' },
		{ data: 'details.1' }
	]
});

Read a DOM sourced table into data objects:

$(document).ready(function () {
	$('#example').DataTable({
		columns: [
			{ data: 'name' },
			{ data: 'position' },
			{ data: 'office' },
			{ data: 'age' },
			{ data: 'start_date' },
			{ data: 'salary' }
		]
	});
});

Using data as a function to provide different information for sorting, filtering and display. In this case, currency (price):

new DataTable('#myTable', {
	columnDefs: [
		{
			targets: 0,
			data: function (row, type, val, meta) {
				if (type === 'set') {
					row.price = val;
					// Store the computed display and filter values for efficiency
					row.price_display = val == '' ? '' : '$' + numberFormat(val);
					row.price_filter =
						val == '' ? '' : '$' + numberFormat(val) + ' ' + val;
					return;
				}
				else if (type === 'display') {
					return row.price_display;
				}
				else if (type === 'filter') {
					return row.price_filter;
				}
				// 'sort', 'type' and undefined all just use the integer
				return row.price;
			}
		}
	]
});

Using default content:

new DataTable('#myTable', {
	columnDefs: [
		{
			targets: [0],
			data: null,
			defaultContent: 'Click to edit'
		}
	]
});

Using array notation - outputting a list from an array:

new DataTable('#myTable', {
	columnDefs: [
		{
			targets: [0],
			data: 'name[, ]'
		}
	]
});

The following options are directly related and may also be useful in your application development.

Options

columns.render

columns.data

Description

Types

integer

string

null

object

function data( row, type, set, meta )

Default

Examples

Related

DataTables