pluck()

Since: DataTables 1.10

Create a new API instance with the value of a property from the objects in the current result set.

Description

When working with objects you may often find that you want an array containing just one property of the source object. This typically involves writing a trivial loop to create that array, although here, that loop is performed in this method, reducing the amount of code required to a trivial function call to get the data required.

This method makes use of the fact that DataTables API objects are "array like", in that they inherit a lot of the abilities and methods of the Javascript Array type.

Type

function pluck( property )

Description:

Iterate over the result set of an API instance, creating a new API instance from the values retrieved from the original elements.

Parameters:

Name Type Optional

	Name	Type	Optional
1	`property`	`string`, `integer`	No
	Object property name to use from the element in the original result set for the new result set. This will typically be a string with the target property name, but can also be an array index if working with arrays. As of DataTables 1.12 Javascript dot notation can also be used to read nested JSON data. All of the options offered by `DataTable.util.get()` can get used.

property

string, integer

Object property name to use from the element in the original result set for the new result set. This will typically be a string with the target property name, but can also be an array index if working with arrays.

As of DataTables 1.12 Javascript dot notation can also be used to read nested JSON data. All of the options offered by DataTable.util.get() can get used.

Returns:

DataTables.Api

New API instance with the values in the result retrieved from the source object properties defined by the property being plucked.

Examples

Pluck the name property from the data objects for the table rows:

var table = $('#example').DataTable({
	data: [
		{
			name: 'Tiger Nixon',
			position: 'System Architect',
			salary: '$3,120',
			start_date: '2011/04/25',
			office: 'Edinburgh',
			extn: '5421'
		},
		{
			name: 'Garrett Winters',
			position: 'Director',
			salary: '$5,300',
			start_date: '2011/07/25',
			office: 'Edinburgh',
			extn: '8422'
		},
		{
			name: 'Ashton Cox',
			position: 'Technical Author',
			salary: '$4,800',
			start_date: '2009/01/12',
			office: 'San Francisco',
			extn: '1562'
		}
	],
	columns: [
		{ data: 'name' },
		{ data: 'position' },
		{ data: 'office' },
		{ data: 'extn' },
		{ data: 'start_date' },
		{ data: 'salary' }
	]
});

var names = table
	.rows()
	.data()
	.pluck('name');

Nested data - get the salary data property:

var table = $('#example').DataTable({
	data: [
		{
			name: 'Tiger Nixon',
			hr: {
				position: 'System Architect',
				salary: '$320,800',
				start_date: '2011/04/25'
			}
		},
		{
			name: 'Garrett Winters',
			hr: {
				position: 'Accountant',
				salary: '$170,750',
				start_date: '2011/07/25'
			}
		},
		{
			name: 'Ashton Cox',
			hr: {
				position: 'Junior Technical Author',
				salary: '$86,000',
				start_date: '2009/01/12'
			}
		}
	],
	columns: [{ data: 'name' }, { data: 'hr.position' }]
});

var salaries = table
	.rows()
	.data()
	.pluck('hr.salary');