datatable
DataTable as an input.
Please note - this property requires the Editor extension for DataTables.
Description
This field type uses DataTables to present an interactive table to your end user letting them select from a list of options. It has all the advantages of DataTables including searching, ordering, paging and other optional features such as scrolling and can be used as a direct replacement for select, checkbox or radio. It can also serve as a replacement for a more advanced input control such as Select2 or Selectize and has the benefit of being fully integrated with Editor.
The Select extension is used to let users select rows by a simple click or tap on a row in the table. When the multiple option is disabled (which it is by default) the user may select a single row in the table. When multiple is enabled, the user may use ctrl and shift click combinations to multiple select rows (see Select documentation for details). Note that Select is required for this field type to operate.
Please see the Editor embedded DataTables example for a full set of running examples.
It is possible to access the DataTables API instance for the field's table through the editor.field('name').dt() function.
Options
This field type supports the following options (in addition to the default options):
config
- Type:
object - Default: Unset
A DataTables configuration object that can be used to customise the DataTable shown in the Editor modal. Any of the DataTables options can be used, although keep in mind additional CSS styling might be required to account for the table being shown in a relatively constrained space.
Important: Do not enable server-side processing (serverSide) on the DataTable being used as an input using this option. It can result in data loss if the selected options aren't on the page shown when the form is submitted.
editor
- Type:
DataTable.Editor - Default: Unset
The Editor instance that should be used for the nested table, if it is to be editable.
footer
This option makes it possible to specify a footer for the table that is displayed by this control. It can be given as an array of strings (the length of which should match the number of columns you have) and each entry will be inserted into a th element. Alternatively, you can pass in a string which contains the HTML of the row to use for the footer, or a jQuery instance which contains the tr element to use.
multiple
- Type:
boolean - Default:
false
Indicate if the end user should be able to select multiple options from the select list. If disabled the Select select.style option for the table will be set to single. When enabled it will be set to os.
options
- Type:
array - Default: Unset
The values and labels to be used in the table. This must be an array of objects. By default the control will expect objects that contain label (shown to the end user) and value properties: [ { label: "Edinburgh", value: 51 }, { label: "London", value: 76 } ].
If your data contains different properties, use the optionsPair parameter to tell Editor which property contains the value and also config's columns option to configure your DataTable.
optionsPair
- Type:
object - Default:
{label:'label', value:'value'}
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.
separator
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().dt()
Get the API instance for the DataTable used in this field.
Returns:
DataTable.Api:
DataTable API instance.
field().update( options [, append ] )
Update the options in the DataTable 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 true.
Parameters:
| Name | Type | Optional | |
|---|---|---|---|
| 1 | options | No | |
Options to display. The data structure given should match that used by the | |||
| 2 | append | Yes - default:false | |
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.