brandwatchltd/selleckt

Another Select replacement. This one loves mustache.

Selleckt

A select replacement, using mustache.js for templating.

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.

selleckt's Issues

Add grunt task to create uglified selleckt.min.js

Selleckt seems to really want to always select the first item in a list

give me a shout if you want me to demonstrate, but out of the box it seems to be difficult to get selleckt to not default to the first real item in the list (not the Please Select part). If you turn it onto multiple mode, it selects every item in the list in turn and you end up with the last item selected.

Support for option groups

Selleckt error when removing selected item - multiple classes with selectionItemClass property problem

I've found that if you pass multiple classes to selectionItemClass when coming to remove a selected item it stumbles here:

var $item = $(e.target).closest('.'+selectionItemClass);

https://github.com/BrandwatchLtd/selleckt/blob/master/lib/MultiSelleckt.js#L185

As you can it will never match. I know it probably wasn't designed to handle multiple classes but wondering whether we should improve this to split into an array and then construct the appropriate class string?

Happy to put in a PR if you're happy with this, can probably update this in a few other locations also.

update on jquery append to multiselect

Thanks so much. This is really nice.

Using the demo $('#demo-3'), I dynamically append an element

$('#demo-3')
          .append($('<option>',{"value" : "5"}).text("TestAdd"))

Is there an update method for selleckt, or should I do the hack?

$($('#demo-3').data('selleckt').$items).parent().remove();
$('#demo-3').removeData();
$('#demo-3').selleckt();

If I just rerun selleckt() without the remove and removeData, the newly appended option does not show.

Just wanted to make sure I was not missing something.

Search errors out in IE 8

When entering a character in the search box on the demo page the follwoing error gets thrown

Member not found. jquery-1.10.1.js, line 5454 character 9

when jquery tries to set e.cancelBubble = true; in stopPropagation()

CSS implementation

There are various css rules that Selleckt depends on (eg to show/hide the options list etc). These should be applied either directly by the plugin or via a base.css file that can be dropped in.

Mimick normal <select>

I think we should leave all options in the menu, even the currently selected one. That would be consistent with the <select> tag.

Add 'onOpened', 'onClosed' and 'onRendered' events

We should expose the above events from Selleckt so that implementors have more flexibility.

Add helpful warnings for templates

There are (admittedly few) dependencies on templates, e.g. items having a data-value with the option value.

Implement console.warn notifications to help implementors.

The distribution should not be included in the repo

I think it's a bit of an anti-pattern as the distribution needs to be occasionally updated in a commit that's interleaved with actual development, adding noise to the commit history.
I can think of two options:

1. creating a dist branch that can be used when importing the package in e.g. bower.json
2. Only publishing the artifacts on bower and npm

Either way the work should be done automatically with each change to master with a build task.