select

Since: Editor 1.0

Select list.
Please note - this property requires the Editor extension for DataTables.

Description

This is one of the simplest field types in Editor, presenting a standard select element in the form.

Keyboard accessibility

Using a keyboard to navigate a form can make data entry and modification much faster than navigation with a mouse. The select input type helps to facilitate this by supporting the following keyboard options:

Submitting the form:
- Press the return key
Show options list:
- Windows: Press alt + up or down arrow keys
- Mac: Press up or down keys when focused on the select element
Select option:
- When the options list is shown, press space bar to select an option
- Windows: Press up and down arrow keys to move between options without showing the options list
- Mac: Press left or right arrow keys to move between options without showing the options list.

Please note that the platform variations are due to browser implementation, confirming to the UI paradigm of the host platform.

Options

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

`attr`

Type: object
Default: Unset

Set HTML attributes on the select element. This is an object of attribute name / value pairs that are applied to the input element for the field. This makes it possible to set attributes such as maxlength and required.

`multiple`

Type: boolean
Default: false
Since: 1.5.1

Indicate if the end user should be able to select multiple options from the select list. The value will be treated as an array by default (see also the separator option).

`options`

Type: array|object
Default: Unset
Since: 1.3

The values and labels to be used in the select list. 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 select input 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.

`placeholder`

Type: string
Default: undefined
Since: 1.5.4

It can often be useful to have a default pseudo value shown in a select list so there isn't an actual value that is pre-selected, but rather a label indicating to the end user what the field can be used for (or even just an empty string).

This configuration parameter can be used to insert such a placeholder as the first item in the list of options. The value used is the label that the end user will see in the select list.

`placeholderDisabled`

Type: boolean
Default: true
Since: 1.5.4

Typically you won't wish to let an end user select the placeholder value, but on occasion this behaviour can be useful (for example selecting an empty value to indicate no join when used with a joined table). This option can be used to allow user selection of the placeholder by setting its value to false.

`placeholderValue`

Type: string
Default: Empty string
Since: 1.5.4

The value of the placeholder can be submitted to the server if the user submits the form without selecting a value or the placeholderDisabled option is set to false. This configuration parameter controls what that value is.

Keep in mind that you should always use validation at the server-side - i.e. if that placeholder value is not a valid input, ensure that the validation will reject it.

`separator`

Type: null|string
Default: null
Since: 1.5.1

When the multiple option is enabled values selected from the select list 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.

Methods

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

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

Update the options in the select list 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.

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. 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.
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: 'select',
	label: 'Title:',
	name: 'title',
	options: ['Mr', 'Ms', 'Mrs', 'Miss', 'Dr']
});

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

editor.add({
	type: 'select',
	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: 'select',
	label: 'Locations:',
	name: 'locations',
	options: [
		{ name: 'Edinburgh', id: 51 },
		{ name: 'London', id: 76 }
	],
	optionsPair: {
		label: 'name',
		value: 'id'
	}
});

Allow multi-item selection with comma separated values:

editor.add({
	type: 'select',
	label: 'Locations:',
	name: 'locations',
	multiple: true,
	separator: ',',
	options: [
		{ label: 'Edinburgh', value: 51 },
		{ label: 'London', value: 76 }
		// etc
	]
});

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

editor.field('title').update(['Mr', 'Ms', 'Mrs', 'Miss', 'Dr', 'Captain']);