Ajax Bootstrap Select

Getting Started
License

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 label Currently 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
    });

ajax-bootstrap-select