Selectorablium

Make huge <select> elements lighter by caching out all the options to localStorage, and easier to browse with options filtering.

Features:

• Loads data as JSON via an XHR call and caches it inside localStorage
• Makes extra XHR calls if queries are over a threshhold value in length
• Filters options via an input element
• Matches option's text
• Matching ignores accented characters
• Sorts matched options
• Highlights query in option's text
• Keyboard navigation works as expected
• Fast

Installation

$ npm install @skroutz/selectorablium

or

$ bower install selectorablium

Warning: Bower is deprecated!

Dependencies

• jQuery

Compatibility

Selectorabllium depends on the localStorage object. If localStorage is not supported in the browser, it uses an included shim which does not persist. So if you run it in an old browser, the JSON data will be fetched every time.

Setup

Include jQuery, the plugin and its css:

<link rel="stylesheet" href="css/selectorablium.css">
<script src="jquery.js"></script>
<script src="selectorablium.js"></script>

Then initialize the plugin:

<select class="selectorablium" name="my_name"></select>

<script>
  $('.selectorablium').selectorablium({
      app_name: 'my_app', //required, for namespacing purposes
      url: 'some_url',    //required, where the XHR will be fetched from
      query: 'q',         //required, GET param name for the XHR queries
      name: 'shops'       //required, name of specific instance
  })
</script>

The <select> element should include no options.

Usage

The plugin can be configured by passing it some options. See next chapter for detailed options listing.

The options can be passed with two ways:

Options object on initialization:

$('.selectorablium').selectorablium({
    app_name: 'my_app',
    url: 'some_url',
    query: 'q',
    name: 'shops',
    default_value: -1,
    default_text: 'some_text'
})

Data-attributes on <select> element:

<select class="selectorablium" name="my_name" data-app_name="test_app" data-url="some_url"></select>

Options passed on initialization have precedence over the data-attribute options.

Options

Name	Required	Value	Default	Description
app_name	yes	string	-	The name of the app. It is used for namespacing the data inside the localStorage.
url	yes	string	-	The url where the XHRs will point to.
query	yes	string	-	the GET param key for the query URL.
name	yes	string	-	the name of the specific Selectorablium instance. It is used for namespacing the data inside the localStorage.
default_value	no	string|number	0	The value for the default <option>.
default_text	no	string|number	'Please select an option'	The text for the default <option>.
selected_id	no	string|number	null	On initialization, search the localStorage and create an <option> with this as value and the text the localStorage returns.
minCharsForRemoteSearch	no	number	3	When the query is longer than this number make query XHRs.
localCacheTimeout	no	number	604800000 (one week)	Milliseconds after which the localStorage is considered as invalid and needs refreshing.
XHRTimeout	no	number	650	Milliseconds to wait before making an XHR query call.
maxResultsNum	no	number	10	The number of results printed
list_of_replacable_chars	no	array	[['ά', 'α'],...]	An array with accented characters and their unaccented counterpart. This is used to make smart matching on accented names even if non accented characters are used in the query

XHR Communications

The response JSON must be an array with objects, with each object having an id and a name key-value:

[{
    "id": "text_or_number1",
    "name":"text_or_number1"
},{
    "id": "text_or_number2",
    "name":"text_or_number2"
}]

On first initialization or when the localStorage needs to be refreshed, an XHR will be made to the url option. The response is expected to be the full list of <option> data.

As the user searches for results by typing a query string on an input, and after the query is longer than the minCharsForRemoteSearch option, an XHR will be made.

If, for example, the url option is 'http://some_url', the query option is 'q', and the query the user has typed in is 'testtest' an XHR will be made to: http://some_url?q=testtest

API

The instance object of each initialized <select> element can be referenced through .data('Selectorablium'):

var instance = $('.selectorablium').first().data('Selectorablium')

.then(success_callback, error_callback)

A then method is exposed so that the instance can be seen as a thenable.

The success_callback is executed after:

• the localStorage gets initialized
• any selected_item gets activated.

On error, the error_callback is executed.

.add(value, text)

Persist to localStorage the passed data. Subsequent searches will find and show that data If value is already present in the localStorage, then the text is not updated.

.set(value[, text])

Manually create an <option> element with the params passed for value and text.

If only the value param is passed, the text is searched in the localStorage.

.reset()

Reset the <select>'s element option to the default value and text.

.cleanup()

Resets the <select> element the the previous state. It completely removes the plugins HTML elements, its internal event handlers and stops any XHR activity.

Updating Bower package

Just execute

$ grunt publish:<type>

with type being the semver values:

• patch
• minor
• major

Authors

Bill Trikalinos (billtrik)

License

This software is released under the MIT License.