Selleckt

A select replacement, using mustache.js for templating.

Running the demos

Pull down the repo then execute:

./serve.sh

and open http://localhost:8080/demo

Running the tests

Run npm install testem -g testem

Or pull down the repo then execute:

./serve.sh

and open http://localhost:8080/test

Configuration

Selleckt enhances a standard html select element. It respects the 'multiple' attribute and instantiates a multiselleckt if that attribute is set.

The plugin uses mustache templates, so its style is highly customisable.

For example, for a select with id 'foo' to instantiate select simply:

$('#foo').selleckt(options);

The element is enhanced, and selleckt is available via:

var sellecktInstance = $('#foo').data('selleckt');

Options

The following options can be passed to selleckt:

property	type	default value	description
mainTemplate	string or compiled mustacheJs template function	See below for default templates
mainTemplateData	object	-	Custom data to be passed to the main template. The property names must be added as tags to the template for this to take effect.
selectedClass	string	selected	The css class name for the item that triggers the dropdown to show. It should also contain an area to show text (the placeholder, or the text of the current selection.
selectedTextClass	string	selectedText	An element to show text (the placeholder, or the text of the current selection. This should be a child of the element defined in `selectedClass`.
itemsClass	string	items	The css class name for the container in which the available selections are shown.
itemslistClass	string	itemslist	The css class name for the list of individual items.
itemClass	string	item	The css class name for the container for an individual item. This should be a descendent of the `itemslistClass` element.
className	string	dropdown	Css class name for the whole selleckt.
highlightClass	string	highlighted	The css class name for the item currently highlighted via keyboard navigation/mouseover selleckt.
itemTextClass	string	itemText	The css class name for the text container inside the `itemClass` element.
placeholderText	string	Please select...	The text shown inside the selectedClass element when there is no item currently selected.
enableSearch	bool	false	If true, then this is used in conjunction with searchThreshold to determine whether to render a search input used to filter the items.
searchInputClass	string	search	The css class of the search input.
searchThreshold	number	0	If the amount of items is above this number, and enableSearch is true then the search input will render.

For multiselleckts, in addition to the above:

property	type	default value	description
selectionTemplate	string or compiled mustacheJs template function	See below for default templates	The template for rendering the individual selected items
selectionsClass	string	selections	The css class name for the container in which the selected items are shown.
selectionItemClass	string	selectionItem	The css class name for an individual selected item. Should be a descendent of the selectionsClass element
alternatePlaceholder	string	Select another...	Once a single selection is made, the 'placeholder' text will be replaced with this text.
removeItemClass	string	remove	Css class of the element used to trigger removal of a selectionItemClass element from the selectionsClass container.
showEmptyList	bool	false	If true, the multiselect won't be disabled once all options were selected. This is useful when you have a footer in your dropdown and you want it to be accessible at all times.

Templates

An example basic template:

<div class="{{className}}" tabindex=1>
    <div class="selected">
        <span class="selectedText">{{selectedItemText}}</span><i class="icon-arrow-down"></i>
    </div>
    <ul class="items">
        {{#showSearch}}
        <li class="searchContainer">
            <input class="search"></input>
        </li>
        {{/showSearch}}
        {{#items}}
        <li class="item" data-text="{{label}}" data-value="{{value}}">
            <span class="itemText">{{label}}</span>
        </li>
        {{/items}}
    </ul>
</div>

An example template for multiselleckt:

<div class="{{className}}" tabindex=1>
    <ul class="{{selectionsClass}}">
    {{#selections}}
    {{/selections}}
    </ul>
    <div class="selected">
        <span class="selectedText">{{selectedItemText}}</span><i class="icon-arrow-down"></i>
    </div>
    <ul class="items">
        {{#items}}
        <li class="item" data-text="{{label}}" data-value="{{value}}">
            {{label}}
        </li>
        {{/items}}
    </ul>
</div>

An example template for a multiselleckt item:

<li class="{{selectionItemClass}}" data-value="{{value}}">
    {{text}}<i class="icon-remove {{removeItemClass}}"></i>
</li>

Events

The following events are raised by an instance of selleckt:

event name	arguments	description
close	-	Triggered when selleckt's dropdown closes
itemSelected	The item that the user has selected	Triggered each time an option is selected by the user. An item is an object representing an option in the selleckt, consisting of value, label and data properties.
optionsFiltered	The user's search term	Triggered after the list of options has been filtered by the user's search term. The provided search term is an unmodified version of the user's search term. Please note that the option filtering will have been case insensitive.

An example of using an event, where there is a select with id 'foo' to which selleckt has been applied:

var sellecktInstance = $('#foo').data('selleckt');

sellecktInstance.bind('itemSelected', function onItemSelected(item){
    console.log('Item selected: ', item);
});