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. columns.render can be considered to be the the read only companion to columns.data which is read / write (and therefore more complex). 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 three 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 sting 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.

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"
}

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:
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:

$('#example').dataTable( {
  "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.
$('#example').dataTable( {
  "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" }
$('#example').dataTable( {
  "columnDefs": [ {
    "targets": 0,
    "data": 'phone',
    "render": {
      "_": "plain",
      "filter": "filter",
      "display": "display"
    }
  } ]
} );

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

$('#example').dataTable( {
  "columnDefs": [ {
    "targets": 0,
    "data": "download_link",
    "render": function ( data, type, full, meta ) {
      return '<a href="'+data+'">Download</a>';
    }
  } ]
} );

Show ellipsis for long strings:

$('#example').dataTable( {
  "columnDefs": [ {
    "targets": 4,
    "data": "description",
    "render": function ( data, type, full, 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();
} );

Related

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