Here is an example of what you will get when you use SOL
You may also use the up and down arrow key to navigate to a certain item and toggle the selection state by hitting the space bar.
First of all you need to have jQuery included in your HTML, then you simply include the SOL js file and the SOL stylesheet.
That's all you need to get started. Let's dive directly into the examples.
The most basic usage is to initialize the plugin without any parameters using an existing <select> element:
This will produce the following result:
The selected entry will be shown on top of the HTML element. When you open the option list, you will see, that all the options are shown with a radio button in front of it. That's because the original select was a single selection element.
So how do we allow selecting more than one entry?
Well, how do you allow selecting multiple options in a regular <select>? Right, simply add the multiple="multiple" attribute!
Let's try it out:
That was easy, wasn't it? How about we add some complexity? What about <optgroup>? Are they supported? Well yes of course they are:
More data sources
There are more ways to pass the data to SOL than to use an existing select.
Initialize empty select with data from array
This example will result in the same SOL as the optgroup example:
Here is the proof:
Note, that SOL now stretches over the full width of the content area. This is because we used a block element (div) to initialize SOL. SOL automatically uses the same width the original element had.
Initialize empty select with data returned from a function
If you need more control you may also pass in a function which then has to return the data to initialize SOL. This enables you to process data retrieved from an url before passing it on to SOL
Initialize empty select from a remote URL
If you provide an url the data will be loaded from that url via an ajax.get call. The data returned from that URL must be in the same format as in the example before.
Sometimes you might want to load the data from a remote URL but that data is not in valid SOL format. In that case you might want to add a converter function which then converts the data to proper SOL format like this:
SOL comes with a couple of options with which you can customize its behaviour. All available options are documented on the configuration page.
Limiting the height of the selection container
When there are a lot of possible options available, the selection container might get really long. With the maxHeight option, you can set a maximum height the container will reach. If the content is longer than that limit, the selection will be scrollable:
Allowing to (de-)select all at once
On a multiple select box it can be very tedious to click every single entry when you actually want to select everything at once. Luckily SOL has the showSelectAll option. Set this option to true and the SOL selection container will show two links at the top do select and deselect all entries.
When you have single select box and you want to give the user to opportunity to select nothing at all, you can simply set the allowNullSelection option to true.
See the difference for yourself
Overriding the default labels
The texts used in SOL are completely customizable. You may set the texts for all SOL elements globally or on a per element basis.
Proper positioning of the option popup
Note: this is an advanced technique you most propably won't ever need. But if you ever need it, you might want to take a closer look at the internal structure of SOL to know which elements exist in the this scope.
The position of the option popup needs to be recalculated every time the popup is opened or the position of the searchable option list changes (e.g. when scrolling). This is due to the fact, that the popup needs to be positioned fixed on the screen to break out of parent containers. If the popup wasn't to be positioned like that, half of it could be cut off due to the container constraints.
Here is an example to show you what I mean: The red border is a parent container with a fixed height (for example it could be a modal popup). For the SOL popup to break out of the container and display itself beyond the parent's bounds, we need to position it fixed on the screen:
Click any SOL to see the difference
Unfortunately fixed elements can not automatically be positioned relative to another object so we have to take care of the ourselves. Most of the time the default implementation of the positioning algorithm should suit your needs but in some cases you might have to override it and position the popup yourself.
You do that in the onScroll event which gets called whenever the set scrollTarget is scrolled. The default scrollTarget to listen for scroll elements is the browser window $(window) but you could also set it to your content area in the options like this: