DataTables logo
≡

autocomplete

Since: Editor 2.4

Autocomplete text input.
Please note - this property requires the Editor extension for DataTables.

Description

The autocomplete field type in Editor provides a regular text input element to allow freeform text input, but also shows a list of values that can be entered below the input. These can be selected by the end user to complete the value they are entering, allowing faster data entry for repetitive data. The list of options is automatically filtered as the end user types into the input.

The options shown below the input can be static (e.g. similar to a select), or for larger data sets can be populated by Ajax (see the ajax option below). The options are populated using the same methods as select, datatable, and others - e.g.: field().update(), the options property for the field, or the options object of the JSON loaded into the DataTable.

It is important to keep in mind that the autocomplete field does allow free text entry. If a restriction on the values entered is needed, either use select, radio, tags (or similar), or a validator at the server-side.

Equally, be aware that autocomplete does not use a separate value and label. What is shown in the text box will be the value that is submitted. If you need the form to submit a different value from what is submitted, please use tags, select, or similar.

Options

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

ajax

This parameter can be used to indicate that the data for the options should be loaded by Ajax while the end user types into the input (i.e. the filtering is done on the server-side). This is particularly useful when working with large data sets.

Setting true will cause the Ajax address to inherit from Editor's Ajax configuration (ajax). The provided libraries for Editor will automatically detect and handle such data requests. Alternatively, if you need to send the request to a custom address, provide it as a string here.

As of Editor 3, it is also possible to provide an Ajax configuration object (DataTable.AjaxOptions) that can be used to provide fine control for the Ajax request.

ajaxData

  • Type: object
  • Default: Unset
  • Since: 2.4.1

This option can be used to provide extra data parameters to send as part of the Ajax request. Each key / value pair in the object is added to the data object that is sent. It is also possible to give a value as a function which is executed at the time the Ajax request is built and the returned value used for the submission value.

attr

Set HTML attributes on the input 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.

display

Function used to customise the display of each label. The default is to simply show the label parameter from the options object, passing it though DataTable.util.escapeHtml() to help prevent XSS attacks (that action can be disabled using the escapeLabelHtml option below).

If you wish to show extra information, or add HTML to each label, this function makes that possible. It takes two parameters:

  1. The object for the option
  2. The value for the option

It must return a string, which will then be displayed to the end user in the options list.

escapeLabelHtml

Indicate if HTML entities in the text shown in the label should be escaped or not.

i18n

This object can be used to define the language strings that autocomplete. The following properties can be set:

  • noResults - This text is shown when a filter is applied and no options are found to match. Defaults to the noResults property of i18n.field.autocomplete value if not provided.
  • placeholder - The placeholder is shown when there are is no search term and no options have been loaded. Defaults to the placeholder property of i18n.field.autocomplete is not provided. Can be set to be an empty string to hide the placeholder.
  • title - Text shown at the top of the dropdown. Can be useful to provide information about the field to the end user. Defaults to an empty string, which causes the title not to be shown.

options

  • Type: array
  • Default: Unset

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

  • 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" ].

optionsOrder

The options given in the list will be ordered alphabetically (or numerically if numeric data) in ascending order. This option provides the ability to control that behaviour.

  • false - no ordering is applied. The options are shown in the order they were loaded.
  • asc - options displayed in ascending order
  • desc - options displayed in descending order.

Methods

This field type does not support any additional methods over the default methods.

Examples

Basic initialisation - options from DataTables JSON:

new DataTable.Editor({
	fields: [{
		label: 'Countries:',
		name: 'country',
		type: 'autocomplete'
	}],
	// ...
})

Specifying a static list of options:

new DataTable.Editor({
	fields: [{
		label: 'City:',
		name: 'city',
		type: 'autocomplete',
		options: [
			'Beijing',
			'London',
			'New York',
			'Paris',
			'Rome',
			'Sydney'
		]
	}],
	// ...
})

Ajax search while user types, using Editor's ajax route:

new DataTable.Editor({
	ajax: '/api/data',
	fields: [{
		label: 'Countries:',
		name: 'country',
		type: 'autocomplete',
		ajax: true
	}],
	// ...
})

Ajax search while user types, using a specified route:

new DataTable.Editor({
	ajax: '/api/data',
	fields: [{
		label: 'Countries:',
		name: 'country',
		type: 'autocomplete',
		ajax: '/api/autocomplete'
	}],
	// ...
})

Ajax search with extra data:

new DataTable.Editor({
	ajax: '/api/data',
	fields: [{
		label: 'Countries:',
		name: 'country',
		type: 'autocomplete',
		ajax: '/api/autocomplete',
		ajaxData: {
			region: 'Europe'
		}
	}],
	// ...
})