zelect v0.0.9

$('select').zelect()

It's just yet another <select>.

>>> Example <<<

>>> Download <<<

• Small, ~ 300 LOC
• Zero base CSS, roll your own
• Customizable (well, at least workaroundable)
• Handles asynchronous paged loading of large option lists (read: AJAX-ready-and-enabled)
• Initializable in a detached or hidden DOM node
• Programmatically selectable and changeable
• Unit-tested

for opts in $.fn.zelect(opts)

An item is any javascript data structure: String, Object, Array, whatever.

Minimal Setup

If the option list is known on the client, finite and manageable, use HTML:

<select id="select-backed-zelect">
  <option value="first">First Option</option>
  <option value="second">Another Option</option>
  <option value="third" selected="selected">Third option</option>
</select>

$('#select-backed-zelect').zelect()

Asyncronous Paged Setup

If the option list is server-backed, infinite or close to it, use opts.loader:

<select id="async-backed-zelect"></select>

$('#async-backed-zelect').zelect({
  initial: 'Third',
  loader: function(term, page, callback) {
    callback(['First for page '+page, 'Second', 'Third'])
  }
})

Callback expects an array. Elements in the array can be anything that renderItem can handle.

zelect will load the next page of results from opts.loader whenever the option list is scrolled to the bottom. It will stop trying to load more once the callback is called with an empty array.

Subscribing to Changes

These events are triggered on the <select>-element:

In addition:

If the zelect is <select>-backed, $('select').val() will return the value of the currently selected option.

$('select').data('zelect-item') will always return the currently selected item.

Programmatically Changing The Selection

$('select').zelectItem(myNewItemThatIWantToSelectNow, fireChangeEvent) will do that.

Whether a change event fires can be controlled with the fireChangeEvent boolean. The default is true.

Programmatically Refreshing an Externally Updated Item

$('select').refreshZelectItem(myUpdatedItem, function(item) { return item._id }) will replace and rerender the item matching myUpdatedItem._id with the new version.

No change events are fired.

Programmatically Resetting the Zelect

$('select').resetZelect() will reset the query to an empty string, load the first results and select the first item.

A change event will fire.

Styling

zelect comes with no base css. Make your own.

For inspiration, see an example.

Initial Selection

When first rendered, zelect determines the initially selected item in this order:

1. opts.initial if defined
2. <option selected="selected"> if opts.loader not defined
3. Render placeholder text from opts.placeholder if defined
4. Select the first option from the list

Custom Option Item Rendering Example

$('select'.zelect({
  renderItem: function(item, term) {
    return $('<span>').addClass('my-item').text(item.label).highlight(term)
  }
})

Highlights matches of the search term in the option text, by using e.g. jquery.highlight.js.

Ajax Loader Example

$('select'.zelect({
  loader: function(term, page, callback) {
    $.get('/search', { query: term, page: page }, function(arrayOfItems) {
      callback(arrayOfItems)
    }
  }
})

Uses a GET to retrieve paged results from a server.

Convoluted Semi-Real-World Example

$('select').on('ready', function() { $('form').enable() })
$('select').on('change', function(evt, item) { $('form input.id-container').val(item.id) })
$('select').zelect({
  throttle: 150,
  placeholder: $('<i>').text('Which one...'),
  loader: loader,
  renderItem: renderer,
  noResults: noResultser
}

function loader(term, page, callback) {
  $.get('/q', { q:term, p:page }).then(function(items) {
    var result = _(items).map(function(item) {
      return { text:item.content, img:item.imageUrl || 'default.png', id:item.uniqueId }
    }
    callback(result)
  }
}

function renderer(item, term) {
  return $('<div>')
    .append($('<img>').attr('src', item.img))
    .append($('<span>').addClass('content').text(item.label))
}

function noResultser(term) {
  return $('<span>').addClass('no-results').text(term + "didn't hit anything.")
}

Enjoy