<?xml version="1.0" encoding="UTF-8" ?>
<dt-option group="columns">
	<name>columns.data</name>
	<summary>Set the data source for the column from the rows data object / array</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 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.
		</description>
	</type>
	<type type="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:
			
			* `dt-init 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.
			* `dt-init 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.
		</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.data` normally does. Note that an `string _` 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:

			```js
			"data": {
				"_": "phone",
				"filter": "phone_filter",
				"display": "phone_display"
			}
			```
		</description>
	</type>
	<type type="function">
		<signature>data( row, type, set, meta )</signature>
		<parameter type="array|object" name="row">
			The data for the whole row
		</parameter>
		<parameter type="string" name="type">
			The data type requested for the cell
		</parameter>
		<parameter type="*" name="set">
			Value to set if the `type` parameter is `-string set`. Otherwise, `-type undefined`.
		</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 not required when 'set' is the type of call, but otherwise the return is what will be used for the data requested.
		</returns>
		<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.
		</description>
		<scope>HTML table element</scope>
	</type>
	<default>
		Takes the index value of the column automatically
	</default>

	<description>
		<![CDATA[
		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 effect its behaviour as documented below.

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

		* `-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` - If `dt-init 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 `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.

		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 `dt-init 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](/examples/advanced_init/object_dom_read.html)).
		]]>
	</description>

	<example title="Read table data from objects"><![CDATA[
// JSON structure for each row in this example:
//   {
//      "engine": {value},
//      "browser": {value},
//      "platform": {value},
//      "version": {value},
//      "grade": {value}
//   }
$('#example').dataTable( {
  "ajaxSource": "sources/objects.txt",
  "columns": [
    { "data": "engine" },
    { "data": "browser" },
    { "data": "platform" },
    { "data": "version" },
    { "data": "grade" }
  ]
} );
]]></example>

	<example title="Read information from deeply nested objects"><![CDATA[
// JSON structure for each row:
//   {
//      "engine": {value},
//      "browser": {value},
//      "platform": {
//         "inner": {value}
//      },
//      "details": [
//         {value}, {value}
//      ]
//   }
$('#example').dataTable( {
  "ajaxSource": "sources/deep.txt",
  "columns": [
    { "data": "engine" },
    { "data": "browser" },
    { "data": "platform.inner" },
    { "data": "details.0" },
    { "data": "details.1" }
  ]
} );
]]></example>

	<example title="Read a DOM sourced table into data objects"><![CDATA[
$(document).ready(function() {
	$('#example').DataTable({
		"columns": [
			{ "data": "name" },
			{ "data": "position" },
			{ "data": "office" },
			{ "data": "age" },
			{ "data": "start_date" },
			{ "data": "salary" }
		]
	});
} );
]]></example>

	<example title="Using `data` as a function to provide different information for sorting, filtering and display. In this case, currency (price)"><![CDATA[
$('#example').dataTable( {
  "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;
    }
  } ]
} );
]]></example>

	<example title="Using default content"><![CDATA[
$('#example').dataTable( {
  "columnDefs": [ {
    "targets": [ 0 ],
    "data": null,
    "defaultContent": "Click to edit"
  } ]
} );
]]></example>

	<example title="Using array notation - outputting a list from an array"><![CDATA[
$('#example').dataTable( {
  "columnDefs": [ {
    "targets": [ 0 ],
    "data": "name[, ]"
  } ]
} );
]]></example>

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