tags

Since: Editor 2.4

Tags input with search support.
Please note - this property requires the Editor extension for DataTables.

Description

Editor's built-in tags input type is a cross between a select list and an autocomplete field. It allows the end user to select from a searchable list of values, while having distinct values and labels for each option (i.e. ideal for a join) and the ability to have multiple values selected.

This type of input is particularly useful for cases when you might have a large list of options that you want the end user to select from, and when you want to provide a concise and simple multi-value input.

The input functions by showing an "Add" button when additional values can be selected, and when activated (by click or keyboard) shows the list of options available, and / or a search box.

The options shown can be static (i.e. 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.

Options

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

`ajax`

Type: DataTable.AjaxOptions|string|boolean
Default: Unset

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 search 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.

`display`

Type: function
Default: Unset

Function used to customise the display 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:

The object for the option
The value for the option

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

`escapeLabelHtml`

Type: boolean
Default: true

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

`i18n`

Type: object
Default: Unset

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

addButton - The text shown in the "add" button when a new option can be added to the field. Defaults to the addButton property of i18n.field.tags value if not provided.
inputPlaceholder - The text shown as the placeholder in the input search box. Defaults to the inputPlaceholder property of i18n.field.tags value if not provided.
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.tags value if not provided.
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.
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.tags is not provided. Can be set to be an empty string to hide the placeholder.
removeIcon (since 2.5.0) - The text that is shown for a tag's remove icon. Defaults to the removeIcon property of i18n.field.tags value if not provided.

`limit`

Type: number|null
Default: null

This option is used to set the max number of options that can be selected for the field. Note that it has some overlap with the multiple configuration option. If multiple is set to false, the limit will automatically be 1 and cannot be overridden.

`multiple`

Type: boolean
Default: true

Sets if the field should allow multiple values, or just a single one.

Note that this property effects the value of the field (both for getting and setting). If true then an array of values will be used. If false a single scalar value will be used.

`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`

Type: string|boolean
Default: Unset
Since: 2.5.0

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.

`separator`

Type: null|string
Default: null

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

`unique`

Type: boolean
Default: true

If enabled then the user may not select the same option multiple times. If disabled, then an option can be added to the value array multiple times.

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: 'tags'
	}],
	// ...
})

Setting a limit of 4 tags:

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

Specifying a static list of options and a single value:

new DataTable.Editor({
	fields: [{
		label: 'City:',
		name: 'city',
		type: 'tags',
		multiple: false,
		options: [
			{ label: 'Beijing', value: 1 },
			{ label: 'London', value: 2 },
			{ label: 'New York', value: 3 },
			{ label: 'Paris', value: 4 },
			{ label: 'Rome', value: 5 },
			{ label: 'Sydney', value: 6 }
		]
	}],
	// ...
})

Ajax search, using the address specified by Editor:

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

Ajax search while user types, using a specified route:

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

Ajax search with extra data:

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