How to use

You need to call the jsMultipleSelect() class and add some HTML markup. Here is how:

The Javascript

Add mootools core and the jsMultipleSelect.js to your website.
The simplest way to use it is to just call

window.addEvent('domready',function(){

  new jsMultipleSelect();

});

An have the right HTML in the page.

If you want to customize it you can use the follwing options:

window.addEvent('domready',function(){

  new jsMultipleSelect({
    highlightColor:'#cccccc',
    removeButton: new Element('a',{'html':'remove'}),
    removeButtonClass: 'remove'
  });

});

• Options

  • highlightColor The color which will be used to highlight the selection destination when a element gets added
    (default: #cedee6)
  • removeButton The remove button which will be add to the all options in the destination box
    (default: new Element('a',{'html':'×','href':'#'}))
  • removeButtonClass The class which will be add to the remove button
    (default: remove)

• Events

  • select will be fired on the destination box when an option is selected. The event function will get the following parameters:

    • value the value of the selected option
    • name the name of the input field of the selected option
    • clone a reference to the <li> element in the destination box
    • option a reference to the <li> element in the option box
    • optionBox a reference to the option box where the option was coming from

  • remove will be fired on the destination box when an option is removed. The event function will get the following parameters:

    • value the value of the selected option
    • name the name of the input field of the selected option
    • clone a reference to the <li> element in the destination box
    • option a reference to the <li> element in the option box
    • optionBox a reference to the option box where the option was coming from

  • parsed will be fired on the destination box when the predefined selections inside the destination box are parsed. (You have to add a Eventlistener to the destination box BEFORE you call the jsMultipleSelect class, otherwise you won't catch the event) The event function will get the following parameters:

    • value the value of the selected option
    • name the name of the input field of the selected option
    • clone a reference to the <li> element in the destination box
    • option a reference to the <li> element in the option box
    • optionBox a reference to the option box where the option was coming from

The Html Markup

You need at least one option box <ul> element with the class "jsMultipleSelect"
and one destination box <ul> element with the class "jsMultipleSelectDestination".

Each option li stores a reference to their clone and visa versa. Just call clone.retrieve('option') or option.retrieve('clone') and you get the li in the option boxes or the li in the destination box.

The option boxes <ul> elements

<ul class="jsMultipleSelect" data-name="myInputFieldName" data-type="duplicates" data-jsMultipleSelect="1">
    <li class="filter"><input type="text" placeholder="Type here to filter"></li>

    <li class="jsMultipleSelectOption" data-value="myValue1">Value Name 1></li>
    <li class="jsMultipleSelectOption" data-value="myValue2">Value Name 2></li>
    <li class="jsMultipleSelectOption" data-value="myValue3" data-type="remove">Removeable Value Name 3></li>
</ul>

• The <ul> element Attributes

  • data-name this is the name attribute which will be add to the hidden input fields, which are created when adding a selection to the destination box.
  • data-jsMultipleSelect the id which connects your option box(es) with your destination box.
  • data-type
  • "remove" removes the options when selected.
  • "duplicates" allows to add options multiple times to the destination box.
  • don't add this attribute, if you want that the options stay in the box but can be added only once to the destination box (default).

• The <li> elements Attributes

  • class each option li must have the class "jsMultipleSelectOption"
  • data-value the value which will be add to the hidden input fields, created when selecting this value.
  • data-type you can also add the data-type attribute only/also to the option <li> elements to specify their behavior.

To add a Filter add the follwoing li element to your option boxes: <li class="filter"><input type="text" placeholder="Type here to filter"></li>.

To customize, you can add what ever you want in the inner part of the <li> elements, like images and text elements. It will all be transfered to the destination box when the option is selected.

thistexthelpstomakealinbreakaftertheimage

The destination box <ul> element

<ul class="jsMultipleSelectDestination" data-jsMultipleSelect="1">
    <li data-value="myValue1" data-name="myInputFieldName" data-number="1"></li>
    <li data-value="myValue1" data-name="myInputFieldName" data-number="2"></li>
    <li data-value="myValue2" data-name="myInputFieldName"></li>
    <li data-value="myValue3" data-name="myInputFieldName"></li>
</ul>

• The <ul> element Attributes

  • data-jsMultipleSelect the id which connects your option box(es) with your destination box.

• The <li> elements Attributes

  • data-value the value which the already selected option will have.
  • data-name the name attribute of the input field which this option has.
  • data-number (optional) you can specify a specific number which this option will have, this number will be add to the text and also to the elements storage. If you leavie this attribute, then the number will be spcified automatically, starting at 1.

• The <li> option data

  • each li has the number number, value and name stored, you can retrieve this by calling $$('#anIdToMyDestinationBox > li.jsMultipleSelectOption').retrieve('number');, ...retrieve('value'); or retrieve('name');.
  • You can also just take the data-... properies, like: $$('#anIdToMyDestinationBox > li.jsMultipleSelectOption').getProperty('data-number'); etc..

Selections

The destination box ul stores a reference to two arrays. The removedOptions and the selectedOptions array. You can retrieve them by calling $('anIdToMyDestinationBox').retrieve('selectedOptions'); etc.

• selectedOptions An array with the currently selected options (a referenz to the option li within the destination box)
• removedOptions An array with all the currently removed options within the option boxes, (when any of the options or option boxes have the attribute data-type="remove")

Clear selection

You can place a <a href="#" class="clearJsMultipleSelect" data-jsMultipleSelect="1">Clear Selection</a> somewhere with the right data-jsMultipleSelect ID attribute, to clear the corresponding destination box.

The Output

If you're wrapping the above elements with a <form> element and send this form to a PHP site you get the following $_POST/$_GET array: (example)

Array
(
['myInputFieldName'] => Array
    (
        [0] => 'myValue2'
        [1] => 'myValue3'
    )
)

Screenshots

Discuss

A note on comments here: These comments are moderated. No comments will show up until they are approved. Comments that are not productive (i.e. inflammatory, rude, etc) will not be approved.

Found a bug in this plugin? Please report it this repository's Github Issues.