<?xml version="1.0" encoding="UTF-8" ?>
<dt-option group="columns">
	<name>columns.render</name>
	<summary>Render (process) the data for use in the table</summary>
	<since>1.10</since>

	<type type="integer">
		<description>
			Treated as an array index for the data source. This is the default that DataTables uses (incrementally increased for each column).
		</description>
	</type>
	<type type="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 `dt-init columns.render` rather than `dt-init columns.data` as it is much simpler to use as a renderer.
		</description>
	</type>
	<type type="object">
		<description>
			Use different data for the different data types requested by DataTables (`string filter`, `string display`, `string type` or `string 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 `dt-init columns.render` normally does.

			Note that an `string _` 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 `string _` option has not been specified, the data pointed to by the `dt-init columns.data` option will be used.

			As an example you might use:

			```js
			"data": "phone",
			"render": {
				"_": "plain",
				"filter": "filter",
				"display": "display"
			}
			```
		</description>
	</type>
	<type type="function">
		<signature>render( data, type, row, meta )</signature>
		<parameter type="*" name="data">
			The data for the cell (based on `dt-init columns.data`)
		</parameter>
		<parameter type="string" name="type">
			The type call data requested. This is used for [DataTables' orthogonal data support](https://datatables.net/manual/data/orthogonal-data). This value will be one of:

			* `-string filter`: Get the value that DataTables should use for filtering on this cell.
			* `-string display`: The value to display in the table.
			* `-string type`: Value to use for type detection. This should normally match the `-string sort` value - see [type detection plug-in documentation](https://www.datatables.net/manual/plug-ins/type-detection).
			* `-string 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](https://www.datatables.net/manual/plug-ins/sorting). Note that this value is `-string sort` for legacy reasons (rather than being `order` which would be more consistent with the rest of the API).
			* `-type undefined`: Get the original data for the cell (i.e. unmodified).
			* Custom value: It is possible for plug-ins such as Responsive (through its `-init responsive.orthogonal` option) and Buttons (`-api 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 `-api cell().render()` method which can be used to execute the given rendering method at any arbitrary time.
		</parameter>
		<parameter type="*" name="row">
			The full data source for the row (not based on `dt-init columns.data`)
		</parameter>
		<parameter type="object" name="meta" 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 `dt-api row().index()`.
			* `col` - The column index for the requested cell. See `dt-api column().index()`.
			* `settings` - The `dt-type DataTables.Settings` object for the table in question. This can be used to obtain an API instance if required.
		</parameter>
		<returns>
			The return value from the function is what will be used for the data requested.
		</returns>
		<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.
		</description>
		<scope>HTML table element</scope>
	</type>

	<description>
		<![CDATA[
		< ## General overview
		<
		< The documentation below is a technical reference (nitty-gritty details). For a more general overview of renderers in DataTables, including discussion of the built in renderers, please refer to the [DataTables manual on this topic](https://datatables.net/manual/data/renderers).

		This property will modify the data that is used by DataTables for various operations as it is read from the data source. `dt-init columns.render` can be considered to be the the read only companion to `dt-init columns.data` which is read / write (and therefore more complex). Like `dt-init 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 `dt-init 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](//datatables.net/manual/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 `dt-init columns.render` can resolve to:

		* `-type undefined` - the `dt-init columns.defaultContent` value will be used. If there is no default content specified, an error will be given.
		* `-type null` - the `dt-init columns.defaultContent` value will be used. If there is no default content specified, for display data an empty sting will be used. `-type null` will be used for all other data types.
		* `-type function` - the function will be executed and the returned value used. As of DataTables <span class="since">1.10.1</span> 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:

		```js
		"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 `-string 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`.
		]]>
	</description>

	<example title="Create a comma separated list from an array of objects"><![CDATA[
$('#example').dataTable( {
  "ajaxSource": "sources/deep.txt",
  "columns": [
    { "data": "engine" },
    { "data": "browser" },
    {
      "data": "platform",
      "render": "[, ].name"
    }
  ]
} );
]]></example>

	<example title="As an object, extracting different data for the different types"><![CDATA[
// 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"
    }
  } ]
} );
]]></example>

	<example title="As above, with the `phone` information as an object"><![CDATA[
// 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"
    }
  } ]
} );
]]></example>

	<example title="Use as a function to create a link from the data source"><![CDATA[
$('#example').dataTable( {
  "columnDefs": [ {
    "targets": 0,
    "data": "download_link",
    "render": function ( data, type, row, meta ) {
      return '<a href="'+data+'">Download</a>';
    }
  } ]
} );
]]></example>

	<example title="Show ellipsis for long strings"><![CDATA[
$('#example').dataTable( {
  "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;
    }
  } ]
} );
]]></example>


	<example title="Using an object instance as the data source for the row"><![CDATA[
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();
} );
]]></example>

	<related type="option">columns.data</related>
</dt-option>