DataTable.Editor.pairs()

Since: Editor 1.4

Obtain label / value paired data from objects and arrays.
Please note - this property requires the Editor extension for DataTables.

Description

Often when working with forms you will encounter selectable data where the user has to select one or more options from a list (for example select, checkbox and radio input types). This usually takes the form of a label / value pair set of data where the user sees the label, but the server sees the value in the submitted data (the label and value might also be the same as each other!).

This method is provided for field type plug-in authors to provide a common method to get these label / value pairs of data. It is used internally by Editor for the select, checkbox and radio options, but it can also be used by external plug-ins and applications as required.

Type

`DataTable.Editor.pairs( data, props, fn )`

Obtain label / value pairs of data from a data source, be it an array or object, for use in an input that requires label / value pairs such as select, radio and checkbox inputs.

Parameters:

	Name	Type	Optional
1	`data`	`object`, `array`	No
	An object or array of data to iterate over getting the label / value pairs.
2	`props`	`object`	No
	When an array of objects is passed in as the data source by default the label will be read from the `label` property and the value from the `value` property of the object. This option can alter that behaviour. Can be `null` or `undefined` to use the default behaviour.
3	`fn`	`function`	No
	Callback function. Takes the following parameters: `string` Label `string` Value `number` Iterator index `object` Attribute object - this is optional and might be undefined depending on the input data. Since 1.6.2. No return value is expected or used.

Examples

Simple array:

var data = [2012, 2013, 2014, 2015];

DataTable.Editor.pairs(data, null, function (value, label, i) {
	console.log('Label: ' + label + '  - Value: ' + value + '  - Count: ' + i);
});

/* Output: 
	Label: 2012  - Value: 2012  - Count: 0
	Label: 2013  - Value: 2013  - Count: 1
	Label: 2014  - Value: 2014  - Count: 2
	Label: 2015  - Value: 2015  - Count: 3
*/

Array of objects:

var data = [
	{ label: 'Edinburgh', value: 51 },
	{ label: 'London', value: 76 }
];

DataTable.Editor.pairs(data, null, function (value, label, i) {
	console.log('Label: ' + label + '  - Value: ' + value + '  - Count: ' + i);
});

/* Output: 
	Label: Edinburgh  - Value: 51  - Count: 0
	Label: London  - Value: 76  - Count: 1
*/

Array of objects with custom properties:

var data = [
	{ name: 'Edinburgh', id: 51 },
	{ name: 'London', id: 76 }
];

DataTable.Editor.pairs(
	data,
	{ label: 'name', value: 'id' },
	function (value, label, i) {
		console.log('Label: ' + label + '  - Value: ' + value + '  - Count: ' + i);
	}
);

/* Output: 
	Label: Edinburgh  - Value: 51  - Count: 0
	Label: London  - Value: 76  - Count: 1
*/