checkbox

Since: Editor 1.0

List of checkbox input controls.
Please note - this property requires the Editor extension for DataTables.

Description

List of checkbox input controls (<input type="checkbox">) which the end user can check as required.

Options

This field type supports the following options (in addition to the default options):

`options`

Type: array|object
Default: Unset
Since: 1.3

The values and labels to be used in the list of checkbox inputs. This can be given in a number of different forms:

object - Name / value pairs, where the property name is used as the label and the value as the field value. For example: { "Edinburgh": 51, "London": 76, ... }.
array - An array of objects with the properties label and value defined. For example: [ { label: "Edinburgh", value: 51 }, { label: "London", value: 76 } ].
array - An array of values (e.g. numbers, strings etc). Each element in the array will be used for both the label and the value. For example: [ "Edinburgh", "London" ].

Note: in v1.3 and earlier this was called ipOpts which is still supported for backwards compatibility.

`optionsPair`

Type: object
Default: {label:'label', value:'value'}
Since: 1.4

If options is given as an array of objects, by default Editor will read the information for the label and value properties of the checkbox list from the label and value properties of the data source object. This option provides the ability to alter those parameters by giving it as an object containing the properties label and value itself, the values of which indicate the properties that should be read from the data source object. For example you might use { label: 'name', value: 'id' } - see below for a complete example.

`separator`

Type: null|string
Default: null

By default the values selected from checkboxes are submitted to the server as an array of values, but you might wish to simply store the selected values in a text field. For this, set a value for the separator parameter (typically a pipe, | or a comma) and Editor will implode the values of the array into a string. It will also read multiple values from a similarly formatted string.

`unselectedValue`

Type: string|integer
Default: undefined
Since: 1.6.0

When there are no checkboxes selected, a checkbox field has no value, however there are times when you might wish to use a single checkbox as a boolean toggle (presenting a single checkbox to a user rather than the dual inputs that a radio input would require). This option provides the ability to assign a value to the field when there are no checkboxes selected.

Note that you will typically wish to use the separator option with this parameter if you want to create a boolean field (so the value is a scalar rather than a vector) - see the example below.

Methods

This field type supports the following methods (in addition to the default methods):

`field().update( options [, append ] )`

Update the options in the list of checkboxes with the options passed in as the first parameter to the function.

Note that the existing options will be entirely replaced by the options given to this method unless the append option is set to be true.

Optionally, each object in an array given as the options to display can have an attr option. This should be an object of key value pairs which will be applied to the option element created for the option, providing a way to add additional data and information to the object. Since 1.6.2.

Parameters:

	Name	Type	Optional
1	`options`	`array`, `object`	No
	Options to display. The data structure given should match that used by the `options` parameter when the field was first configured.
2	`append`	`boolean`	Yes - default:false
	Since 1.6: Flag to indicate if the new options should be appended to the existing list of options, or if they should entirely replace the current list (which is the default action).

Returns:

DataTable.Editor.Field:
The field instance is returned to allow method chaining.

Examples

Basic initialisation (array data source):

editor.add({
	type: 'checkbox',
	label: 'Years:',
	name: 'years',
	options: [2012, 2013, 2014, 2015]
});

Use an array of objects with default label and value properties:

editor.add({
	type: 'checkbox',
	label: 'Locations:',
	name: 'locations',
	options: [
		{ label: 'Edinburgh', value: 51 },
		{ label: 'London', value: 76 }
	]
});

Use an array of objects with specified label and value properties:

editor.add({
	type: 'checkbox',
	label: 'Locations:',
	name: 'locations',
	options: [
		{ name: 'Edinburgh', id: 51 },
		{ name: 'London', id: 76 }
	],
	optionsPair: {
		label: 'name',
		value: 'id'
	}
});

Use an object data source and set a separator option:

editor.add({
	type: 'checkbox',
	label: 'Locations:',
	name: 'locations',
	options: {
		Edinburgh: 51,
		London: 76
	},
	separator: ','
});

Update the options available using the update() method.:

editor.field('locations').update({
	Edinburgh: 51,
	London: 76,
	Paris: 4,
	'New York': 32
});

Using unselectedValue to allow a boolean selection:

editor.add({
	label: 'Status:',
	name: 'done',
	type: 'checkbox',
	options: [{ label: 'Done', value: 1 }],
	separator: '',
	unselectedValue: 0
});