columns.render

Since: DataTables 1.10

Render (process) the data for use in the table.

Description

This property will modify the data that is used by DataTables for various operations as it is read from the data source. Like columns.data this option can be given in a number of different ways to affect its behaviour as described below.

The data that is returned by the columns.render option (regardless of if it is used as a function, integer or string) is what DataTables will use for the requested data type (this is called the resolved data). DataTables ability to request different data for its different operations is referred to as orthogonal data and allows different forms of the same data to be used for different operations (for example, a date might be given formatted for an end user for display and search, but in an integer form for ordering).

There are four special values that columns.render can resolve to:

undefined - the columns.defaultContent value will be used. If there is no default content specified, an error will be given.
null - the columns.defaultContent value will be used. If there is no default content specified, for display data an empty string 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. See the examples below for how to use an instance with DataTables.
node 2.0 - when requesting the display data type, you may return a DOM node to be displayed in the cell for the table. It is important to note that all other data types should return a string or numeric value so DataTables can operate on them (e.g. search, order and type detection need data other than a DOM node!).

Array access

When used as a string (see below), this option can be used to obtain multiple data points from an array or access specifically just one element in an array. It is important to understand the difference between the two forms if you wish to access array based data inside a row's data object.

Use one or more properties from an array - use [] notation
Obtain a single element from the array only - use dotted notation - e.g. .0 to access the first element in the array.

Consider for example this data structure:

"access": [
  { "id": "1", "name": "Printer" },
  { "id": "3", "name": "Desktop" },
  { "id": "4", "name": "VMs" }
]

To display the name property from the objects in the array, in a single cell, use access[, ].name - this will concatenate the names separated by , - e.g. in this case the result would be Printer, Desktop, VMs.

To access a single property from an array use .{index}. Using the above JSON again, to display just the first name from the access array use access.0.name - e.g. in this case the result would be Printer.

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 an object property 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 you can use 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. See above for further information on array access.
() - 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 columns.render rather than columns.data as it is much simpler to use as a 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.render normally does.

Note that an _ option can optionally be specified. This is the default value to use if you haven't specified a value for the data type requested by DataTables. If there is no option for the data type requested that the _ option has not been specified, the data pointed to by the columns.data option will be used.

As an example you might use:

"data": "phone",
"render": {
    "_": "plain",
    "filter": "filter",
    "display": "display"
}

array

Description:

DataTables has a number of built in helper rendering functions that can be used to perform basic formatting. These helpers can be accessed from $.fn.dataTable.render and will resolve to a function (see below) that will be used for the data rendering. This works very well when you define the columns in pure Javascript, but if you wish to define them with JSON, since there is no ability to define functions in JSON we need a different method - the array values provide that ability.

The first element of the array should be a string that contains the rendering function's name. The remaining elements of the array are then passed to the specified rendering function.

As an example you might use the formatting to access the number formatting function:

'data': 'cost',
'render': ['number', ',', '.', 0, '$']

which is the same as:

data: 'cost',
render: DataTable.render.number( ',', '.', 0, '$' )

function render( data, type, row, meta )

Description:

If a function is given, it will be executed whenever DataTables needs to get the data for a cell in the column. Note that this function might be called multiple times, as DataTables will call it for the different data types that it needs - sorting, filtering and display.

Parameters:

	Name	Type	Optional
1	`data`	`Any`	No
	The data for the cell (based on `columns.data`)
2	`type`	`string`	No
	The type call data requested. This is used for DataTables' orthogonal data support. This value will be one of: `filter`: Get the value that DataTables should use for filtering on this cell. `display`: The value to display in the table. `type`: Value to use for type detection. This should normally match the `sort` value - see type detection plug-in documentation. `sort`: Get the data to use for sorting on this cell - the value returned should typically be numeric or a string, but custom plug-ins can be used - see the plug-in documentation. Note that this value is `sort` for legacy reasons (rather than being `order` which would be more consistent with the rest of the API). `undefined`: Get the original data for the cell (i.e. unmodified). Custom value: It is possible for plug-ins such as Responsive (through its `responsive.orthogonal` option) and Buttons (`buttons.exportData()`) to request custom data types specified by the developer. This can be useful in cases where you want send certain data to a particular extension. See also the `cell().render()` method which can be used to execute the given rendering method at any arbitrary time.
3	`row`	`Any`	No
	The full data source for the row (not based on `columns.data`)
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 what will be used for the data requested.

Examples

Create a comma separated list from an array of objects:

new DataTable('#myTable', {
	ajaxSource: 'sources/deep.txt',
	columns: [
		{ data: 'engine' },
		{ data: 'browser' },
		{
			data: 'platform',
			render: '[, ].name'
		}
	]
});

As an object, extracting different data for the different types:

// This would be used with a data source such as:
//   { "phone": 5552368, "phone_filter": "5552368 555-2368", "phone_display": "555-2368", ... }
// Here the `phone` integer is used for sorting and type detection, while `phone_filter`
// (which has both forms) is used for filtering for if a user inputs either format, while
// the formatted phone number is the one that is shown in the table.
new DataTable('#myTable', {
	columnDefs: [
		{
			targets: 0,
			data: null, // Use the full data source object for the renderer's source
			render: {
				_: 'phone',
				filter: 'phone_filter',
				display: 'phone_display'
			}
		}
	]
});

As above, with the phone information as an object:

// This would be used with a data source such as:
//   "phone": { "plain": 5552368, "filter": "5552368 555-2368", "display": "555-2368" }
new DataTable('#myTable', {
	columnDefs: [
		{
			targets: 0,
			data: 'phone',
			render: {
				_: 'plain',
				filter: 'filter',
				display: 'display'
			}
		}
	]
});

Use as a function to create a link from the data source:

new DataTable('#myTable', {
	columnDefs: [
		{
			targets: 0,
			data: 'download_link',
			render: function (data, type, row, meta) {
				return '<a href="' + data + '">Download</a>';
			}
		}
	]
});

Show ellipsis for long strings:

new DataTable('#myTable', {
	columnDefs: [
		{
			targets: 4,
			data: 'description',
			render: function (data, type, row, meta) {
				return type === 'display' && data.length > 40
					? '<span title="' + data + '">' + data.substr(0, 38) + '...</span>'
					: data;
			}
		}
	]
});

Using an object instance as the data source for the row:

function Person(name, age, position) {
	this._name = name;
	this._age = age;
	this._position = position;

	this.name = function () {
		return this._name;
	};

	this.age = function () {
		return this._age;
	};

	this.position = function () {
		return this._position;
	};
}

$(document).ready(function () {
	var table = $('#example').DataTable({
		columns: [
			{ data: null, render: 'name' },
			{ data: null, render: 'age' },
			{ data: null, render: 'position' }
		]
	});

	table.row.add(new Person('Airi Satou', 33, 'Accountant'));
	table.row.add(
		new Person('Angelica Ramos', 47, 'Chief Executive Officer (CEO)')
	);
	table.row.add(new Person('Ashton Cox', 66, 'Junior Technical Author'));
	table.draw();
});

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

Options

columns.data

columns.render

Description

Array access

Types

integer

string

object

array

function render( data, type, row, meta )

Examples

Related

DataTables