Ajax Bootstrap Select
Getting Started
Extends existing Bootstrap Select implementations by adding the ability to search via AJAX requests as you type. Originally for CROSCON.
Requirements
Minimum requirements:
- Bootstrap Select 1.6.3+
- A server that can process AJAX requests and send back appropriate JSON data.
Bootstrap Select must either be be initialized with liveSearch
enabled in the passed options or the select
element must have the data-live-search="true"
attribute.
This plugin must be initialized after Bootstrap Select has been initialized. For a more detailed explanation on implementation, see usage example.
Suggested requirements:
Options
Options can be passed via data attributes or through the JavaScript options object. For data attributes, append the option name to the data-abs-
prefix. Options names (and any nested options) are always lower case and separated by -
, such as in data-abs-ajax-url="..."
or data-abs-locale-search-placeholder="..."
.
options.ajaxResultsPreHook
Deprecated: Since version
1.2.0
, see: options.preprocessData.Type:
Function
options.ajax
Required
Type:
Object
Data Attribute:
data-abs-ajax[-*]="..."
The options to pass to the jQuery AJAX request.
{ url: null, // Required. type: 'POST', dataType: 'json', data: { q: '{{{q}}}' } }
options.minLength
Type:
Number
Default:
0
Data Attribute:
data-abs-min-length="..."
Invoke a request for empty search values.
options.ajaxSearchUrl
Deprecated: Since version
1.2.0
, see: options.ajax.Type:
String
options.bindEvent
Type:
String
Default:
"keyup"
Data Attribute:
data-abs-bind-event="..."
The event to bind on the search input element to fire a request.
options.cache
Type:
Boolean
Default:
true
Data Attribute:
data-abs-cache="..."
Cache previous requests. If enabled, the "enter" key (13) is enabled to allow users to force a refresh of the request.
options.clearOnEmpty
Type:
Boolean
Default:
true
Data Attribute:
data-abs-clear-on-empty="..."
Clears the previous results when the search input has no value.
options.clearOnError
Type:
Boolean
Default:
true
Data Attribute:
data-abs-clear-on-error="..."
Clears the select list when the request returned with an error.
options.debug
Deprecated: Since version
1.2.0
, see: options.log.Type:
Boolean
options.emptyRequest
Type:
Boolean
Default:
false
Data Attribute:
data-abs-empty-request="..."
Invoke a request for empty search values.
options.ignoredKeys
Type:
Object
Data Attribute:
data-abs-ignored-keys[-*]="..."
Key codes to ignore so a request is not invoked with bindEvent. The "enter" key (13) will always be dynamically added to any list provided unless the "cache" option above is set to "true".
{ 9: "tab", 16: "shift", 17: "ctrl", 18: "alt", 27: "esc", 37: "left", 39: "right", 38: "up", 40: "down", 91: "meta" }
options.langCode
Type:
String
Default:
null
Data Attribute:
data-abs-lang-code="..."
The language code to use for string translation. By default this value is determined by the browser, however it is not entirely reliable. If you encounter inconsistencies, you may need to manually set this option.
options.locale
Type:
Object
Default:
null
Data Attribute:
data-abs-locale[-*]="..."
Provide specific overrides for locale string translations. Values set here will cause the plugin to completely ignore defined locale string translations provided by the set language code. This is useful when needing to change a single value or when being used in a system that provides its own translations, like a CMS.
locale: { searchPlaceholder: Drupal.t('Find...') }
options.log
Type:
String|Number|Number
Default:
'error'
Data Attribute:
data-abs-log="..."
Determines the amount of logging that is displayed:
- 0, false: Display no information from the plugin.
- 1, 'error': Fatal errors that prevent the plugin from working.
- 2, 'warn': Warnings that may impact the display of request data, but does not prevent the plugin from functioning.
- 3, 'info': Provides additional information, generally regarding the from request data and callbacks.
- 4, true, 'debug': Display all possible information. This will likely be highly verbose and is only recommended for development purposes or tracing an error with a request.
options.mixWithCurrents
Deprecated: Since version
1.2.0
, see: options.preserveSelected.Type:
Boolean
options.placeHolderOption
Deprecated: Since version
1.2.0
, see: locale.emptyTitle.
options.preprocessData
Type:
Function|null
Default:
function(){}
Process the raw data returned from a request. The following arguments are passed to this callback:
- data -
Array
The raw data returned from the request, passed by reference. This callback must return one of the following:Array
- A new array of items. This will replace the passed data.undefined|null|false
- Stops the callback and will use whatever modifications have been made to data.function (data) { var new = [], old = [], other = []; for (var i = 0; i < data.length; i++) { // Add items flagged as "new" to the correct array. if (data[i].new) { new.push(data[i]); } // Add items flagged as "old" to the correct array. else if (data[i].old) { old.push(data[i]); } // Something out of the ordinary happened, put these last. else { other.push(data[i]); } } // Sort the data according to the order of these arrays. return [].concat(new, old, other). }
options.preserveSelected
Type:
Boolean
Default:
true
Data Attribute:
data-abs-preserve-selected="..."
Preserve selected items(s) between requests. When enabled, they will be placed in an
<optgroup>
with the labelCurrently Selected
. Disable this option if you send your currently selected items along with your request and let the server handle this responsibility.
options.preserveSelectedPosition
Type:
String
Default:
'after'
Data Attribute:
data-abs-preserve-selected-position="..."
Place the currently selected options
'before'
or'after'
the options returned from the request.
options.processData
Type:
Function|null
Default:
function(){}
Process the data returned after this plugin, but before the list is built.
options.requestDelay
Type:
Number
Default:
300
Data Attribute:
data-abs-request-delay="..."
The amount of time, in milliseconds, that must pass before a request is initiated. Each time the options.bindEvent is fired, it will cancel the current delayed request and start a new one.
options.restoreOnError
Type:
Boolean
Default:
false
Data Attribute:
data-abs-restore-on-error="..."
Restores the select list with the previous results when the request returns with an error.
options.templates
Type:
Object
Data Attribute:
data-abs-templates[-*]="..."
The DOM templates used in this plugin.
templates: { // The placeholder for status updates pertaining to the list and request. status: '<div class="status"></div>', }
Locale Strings
See: options.locale
locale.currentlySelected
Type:
String
Default:
'Currently Selected'
The text to use for the label of the option group when currently selected options are preserved.
locale.emptyTitle
Type:
String
Default:
'Select and begin typing'
The text to use as the title for the select element when there are no items to display.
locale.errorText
Type:
String
Default:
''Unable to retrieve results'
The text to use in the status container when a request returns with an error.
locale.searchPlaceholder
Type:
String
Default:
'Search...'
The text to use for the search input placeholder attribute.
locale.statusInitialized
Type:
String
Default:
'Start typing a search query'
The text used in the status container when it is initialized.
locale.statusNoResults
Type:
String
Default:
'No Results'
The text used in the status container when the request returns no results.
locale.statusSearching
Type:
String
Default:
'Searching...'
The text to use in the status container when a request is being initiated.
locale.statusTooShort
Type:
String
Default:
'Please enter more characters'
The text used in the status container when the request returns no results.
JSON Results
The plugin expects a certain result structure, an array of objects with the objects following a certain structure, below is an example with every option set:
[ { value: 'string', // Required. text: 'string', // If not set, it will use the value as the text. class: 'string', // The CSS class(es) to apply to the option element. disabled: false, // {Boolean} true|false // NOTE: If "divider" is present as a property, the entire item is // considered a divider and the rest of the item value/data is // ignored. Alternatively, this can be set in the data property as well. divider: true, // Data attributes that you would set on the option tag, these will be // set on the newly created options tags and the selectpicker plugin // will process them accordingly. data: { divider: true, subtext: 'string', icon: 'class-name', // Icon class name ex: icon-glass content: '<div class="custom-class">my value label</div>', } } .... ]
Usage Example
$('.select-picker') .selectpicker({ liveSearch: true }) .ajaxSelectPicker({ ajax: { url: '/server/path/to/ajax/results', data: function () { var params = { q: '{{{q}}}' }; if(gModel.selectedGroup().hasOwnProperty('ContactGroupID')){ params.GroupID = gModel.selectedGroup().ContactGroupID; } return params; } }, locale: { emptyTitle: 'Search for contact...' }, preprocessData: function(data){ var contacts = []; if(data.hasOwnProperty('Contacts')){ var len = data.Contacts.length; for(var i = 0; i < len; i++){ var curr = data.Contacts[i]; contacts.push( { 'value': curr.ContactID, 'text': curr.FirstName + ' ' + curr.LastName, 'data': { 'icon': 'icon-person', 'subtext': 'Internal' }, 'disabled': false } ); } } return contacts; }, preserveSelected: false });
License
Copyright (c) 2019 Adam Heim, contributors.
Released under the MIT license