Selectable

Selectable is a standard select-boxes replacement that can hold any html content in the options list. It can work both ways as a multi or as a single-select box.

Get the latest version right here

All the source code of the project is available under terms of the MIT license

http://github.com/rightjs/rightjs-ui/tree/master/src/selectable/

For some standard usage examples see the demo page

Index

top ↑Features List

Our selectables have the following features

  • Provides both multi and single selectboxes
  • Can work as a standalone widget
  • Can be assigned to work as a part of a form
  • Can automatically replace SELECT tags
  • Everything is in a tiny (3.5k gzipped) file, including the basic styles
  • Easy and flexible use with many of options

top ↑Usage Basics

First of all you need to include one of the files above onto your page. After that you can just generate your selectables programmatically in JavaScript

new Selectable({
options: ['one', 'two', 'three', 'four', 'five']
}).insertTo('the-container');

You also can prepare an HTML structure and then initialize your selectable on it, like this

<ul id="my-selectable">
<li>One</li>
<li>Two</li>
<li>Three</li>
<li>Four</li>
</ul>

new Selectable('my-selectable', {
selected: 2,
disabled: [1,3]
});

Or, as usual, you can just assign the rui-selectable css-class onto your element and it will get automatically initialized when the page is loaded.

<ol class="rui-selectable">
<li>One</li>
<li>Two</li>
</ol>

Yes, that’s right you can use both UL or OL tags, and, as usual, you can specify an HTML5 like attribute called data-selectable with your options in a JSON format.

And you also can make the script automatically generate selectables out of standard selectboxes. Just add the rui-selectable css-class and our script will automatically find it, generate a selectable widget equivalent and hide the original. That way the form the original selectbox belongs to won’t notice anything

<select name="boo" class="rui-selectable">
<option value="1"><b>F</b>first</option>
<option value="2"><b>S</b>econd</option>
....
</select>

top ↑Various Variants

To let the script know that you want a simple single-select box you have two options: add the rui-selectable-single css-class to your element, or use the multiple: false option in any available way.

<ul class="rui-selectable right-selectable-single">
....
</ul>

<ul class="rui-selectable" data-selectable="{multiple:false}">
...
</ul>

You also can create selectables with groups of options. For that case use the standard dl/dt/dd tags structure like that

<dl class="rui-selectable">
<dt>First Group</dt>
<dd>
<ul>
<li>One</li>
<li>Two</li>
</ul>
</dd>
<dt>Second Group</dt>
<dd>
<ul>
<li>Three</li>
<li>Four</li>
</ul>
</dd>
</dl>

You can use the list with groups with the single-select boxes as well.

top ↑Assigned To Inputs

Our selectables can be easily used as a part of forms by assigning them to hidden input elements. You can do that by using the assignTo() method or with the update option, like that

<form ...>
<input id="the-value" type="hidden" />

// programmatically
new Selectable({...}).assignTo('the-value');

// with automatic initialization
<ul class="rui-selectable"
data-selectable="{update: 'the-value'}">
....
</ul>

</form>

NOTE: those assignments work both ways, when you change the selectbox it will change the input field value, and when you change the input field, it will change the selectbox.

There are several ways you can specify the actual values to be used for the output. If you use a flat list of options, or simple LI tags, the script will use the indexes of the options in the list.

var selectable = new Selectable({
options: ['one', 'two', 'three'],
select: [0,1]
});

// or in HTML
<ul>
<li>one</li>
<li>two</li>
<li>three</li>
</ul>

selectable.getValue(); // -> [0, 1]

But if you had used a hash of options with key->value pairs, or id attributes for your LI elements, then those keys or ID values will be used as the values

var selectable = new Selectable({
options: {
one: 'First',
two: 'Second',
three: 'Third'
},
selected: [0,1]
});

// or with html like this
<ul>
<li id="one">First</li>
<li id="two">Second</li>
<li id="three">Third</li>
</ul>

selectable.getValue(); // -> ['one', 'two']

In case if you have the keys/IDs in a some sort of sequential way, like thing-1, thing-2, thing-3, you also can specify the parseIds option as true and then the script will automatically parse out the numerical part of the IDs to be used as the result value.

var selectable = new Selectable({
options: {
'thing-1': 'First',
'thing-2': 'Second',
'thing-3': 'Third'
},
selected: [0,1],
parseIds: true
});

// эквивалентный HTML
<ul>
<li id="thing-1">First</li>
<li id="thing-2">Second</li>
<li id="thing-3">Third</li>
</ul>

selectable.getValue(); // -> [1, 2]

top ↑Options List

You can use any of those options in an options hash with the Selectable class constructor, or in a JSON formatted hash inside your custom data-selectable attribute.

NameDefaultDescription
optionsnulla hash of key-value pairs or an array of options
selectednullan array of selected item indexes
disablednullan array of disabled item indexes
multipletruea flag if it should be a multi-select or a single select widget
fxName‘slide’the drop-down options list fx-name (null, ‘slide’, ‘fade’)
fxDuration‘short’the drop-down options list fx-duration
updatenulla field to be assigned to
parseIdsfalseif it should parse integer ids out of the keys
limitnullthe maximum number of items the user can choose on the list
hCont’&bull;’content for the single-select handle element

top ↑Events List

There is the following list of events the Selectable instances will handle by default

NameDescription
changethe value was changed
selectan item was selected
unselectan item was unselected
disablean item was disabled
enablean item was enabled
hoveran item was hovered with the cursor
leavean item was left by the cursor
showthe drop-down menu was displayed
hidethe drop-down menu was closed

top ↑API-Reference

There are several handy methods in the public API of the Selectable unit

NameDescription
initialize([element,] Object options)basic constructor
setValue(value)sets the value
getValue()returns the current value
select(item)selects the item(s)
unselect(item)unselects the item(s)
selected(item)checks if the item(s) are selected
disable(item)disables the item(s)
enable(item)enables the item(s)
disabled(item)checks if the item(s) are disabled
assignTo(element)assigns the widget to work with the input element

NOTE: the item related methods, like select, unselect, etc, can receive several types of arguments, it might be numerical indexes in the items list, it can be keys/ids of the options, or the list item elements by themselves. You also can send either arrays or single items, works both ways.

You also can call those methods without any arguments, in which case the script will assume that you want select/unselect/disable/enable/check all the items on the list.

top ↑Style Alterations

The elements structure will be left intact pretty much as it described in the usage basics chapter. The script will also use the rui-selectable-selected and rui-selectable-disabled css-classes for selected and disabled list items respectively.

<ul class="rui-selectable">
<li class="rui-selectable-selected">Selected item</li>
<li class="rui-selectable-disabled">Disabled item</li>
<li>Another item</li>
</ul>

For the single-select boxes, it will add the rui-selectable-single class to the list element, and insert a simple structure like that, right before the list.

<div class="rui-selectable-container">
<div class="rui-selectable-handle">&bull;</div>
<ul class="rui-selectable-display">
<li>Selected item</li>
</ul>
</div>

That will work as the select-box visible element and the LI element will be cloned out of the currently selected item on the options list.