Another Select replacement. This one loves mustache.
JavaScript HTML CSS
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
demo
dist
lib
shims
test
.editorconfig
.eslintignore
.eslintrc
.gitignore
.travis.yml
CHANGE_LOG.md
Gruntfile.js
LICENSE
README.md
bower.json
karma.conf-integration.js
karma.conf-saucelabs-legacyselleckt.js
karma.conf-saucelabs.js
karma.conf-travis.js
karma.conf.js
package.json
update-bower-version.js

README.md

Selleckt

A select replacement, using mustache.js for templating.

Build Status

Sauce Test Status

Sauce Browser Matrix

Running the demos

Pull down the repo then execute:

npm start

and open http://localhost:8282/demo

Running the tests

The tests are run using Karma as the test runner. For convenience and consistency between local dev environments and CI (Travis), it's recommended to use grunt to run the tests.

npm test will start the test suite, and attempt to run the tests in Safari, Firefox and Chrome.

The test suites themselves are written using Mocha. To view the mocha tests, press the debug button at the top right of the browser window (that you wish to debug in) when it spawns after npm test is executed.

To target a single browser run:

karma start karma.conf.js --browsers=Chrome --single-run=false

Valid browser names would include any of Chrome, Safari or Firefox. The addition of --single-run=false will stop the spawned window from closing when the test run completes.

NB: to run karma from the terminal you'll need to install Karma's CLI tool with

npm install -g karma-cli

various integration test suites are available, and can be accessed using npm run-script. They use the built distribution of Selleckt. view package.json to see what suites there are.

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 See below for default templates
itemTemplate string See below for default templates
popupTemplate string 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.
defaultSearchTerm string '' If enableSearch is true, prefill search input with defaultSearchTerm.
hideSelectedItem boolean false set to `true` if you want currently selected items to not show in the `SellecktPopup`
maxHeightPopupPositioning boolean false set to `true` if you want selleckt to evaluate `SellecktPopup` position based on its max height (e.g. remote search).

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.
unselectItemClass string unselect 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

Selleckt uses mustache templates in order to render. There are 3 separate templates used in SingleSelleckt instances, and 4 in MultiSelleckt instances. The templates are explained in the following table:

Name Usage Description
mainTemplate SingleSelleckt and MultiSelleckt

This template is the 'trigger' or 'opener' element for the selleckt popup. It's what you see in the DOM instead of the original `select` element.

There's defaults for this template in `TEMPLATES.SINGLE` and `TEMPLATES.MULTI`

itemTemplate SingleSelleckt and MultiSelleckt

This template is used to render a single item in the `SellecktPopup`. It represents an `option` element from the original `select`

There's defaults for this template in `TEMPLATES.SINGLE_ITEM` and `TEMPLATES.MULTI_ITEM`

popupTemplate SingleSelleckt and MultiSelleckt

This template is used to render the `SellecktPopup` - this element is attached to the `body` of the document and positioned absolutely.

There's a default for this template in `TEMPLATES.ITEMS_CONTAINER`

selectionTemplate MultiSelleckt

This template is used to render a single selected item in the MultiSelleckt. The items are attached to the DOM above the replaced `select` element so you can see which items have been selected.

There's a default for this template in `TEMPLATES.MULTI_SELECTION`

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.
itemUnselected The item that the user has unselected from a Triggered each time an option is deselected 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.
onPopupCreated The SellecktPopup instance Triggered when a popup instance is created. Useful to bind to events triggered by both the `SellecktPopup` itself, or its DOM element (`popup.$popup`)
itemsUpdated
  • `items` - all the items
  • `newItems` - items that were added
  • `removedItems` - items that were removed
  • `selectedItems` - all items that are now selected
Triggered when the `option` elements in the replaced select element change . Uses a Mutation Observer under the hood

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.on('itemSelected', function onItemSelected(item){
    console.log('Item selected: ', item);
});

Versioning

Versioning is done through npm by running npm version [<newversion> | major | minor | patch]. For documentation visit npm.