Naughty Platypus Memorabilia

    ajax-bootstrap-select

    1.4.5 • Public • Published

    Ajax Bootstrap Select GitHub version Build Status CDNJS Gitter FOSSA Status

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

    License

    Copyright (c) 2019 Adam Heim, contributors.
    Released under the MIT license

    FOSSA Status

    Keywords

    none

    Install

    npm i ajax-bootstrap-select

    DownloadsWeekly Downloads

    11,660

    Version

    1.4.5

    License

    MIT

    Unpacked Size

    3.03 MB

    Total Files

    513

    Last publish

    Collaborators

    • truckingsim