Selectioner: A JavaScript repository from hrudham

#Selectioner

A jQuery-based enhancement for HTML select boxes.

You can view the live demo here: http://hrudham.github.io/

Introduction

What it works in

Tested in Google Chrome, Firefox, Safari (for Windows), Opera 12, Internet Explorer 8, 9 and 10.

How to use it

Make sure that you've included the following in your project:

jQuery
selectioner.min.js (or the development version)
selectioner.css
- You'll probably want to edit this to suit your website's look and feel.

What features it has

The pop-up always attempts to make sure it appears on the screen; it will try (but not guarantee) not to cause any overflow.
It stays in sync with it's underlying element and preserves element IDs, so the correct information is sent when a POST occurs.

Single-select

This will create a control that will allow you to select a single item.

<select id="MySingleSelect"> ... </select>
<script>
	$('#MySingleSelect').singleSelect();
</script>

Multi-select

This will create a control that will allow you to select multiple items.

<select id="MyMultiSelect" multiple="multiple"> ... </select>
<script>
	$('#MyMultiSelect').multiSelect();
</script>

Combo-select

This will create a control that will allow you to select a single item, or enter your own text.

It assumes that you have a select element followed by an input type="text" element.

<select id="MyComboSelect">
	<option></option> <!-- an empty option is required -->
	...
</select>
<input type="text" id="MyComboText" placeholder="Select an option" />
<script>
	$('#MyComboSelect').comboSelect();
</script>

Auto-complete

This will create a control that will allow to select an item, or enter your own. The items displayed will be filtered based upon what you type, and limited to a maximum of five items.

It assumes that you have a select element followed by an input type="text" element.

Please note that this does not support optgroup elements in the underlying select element.

<select id="MyAutoCompleteSelect">
	<option></option> <!-- an empty option is required -->
	...
</select>
<input type="text" id="MyAutoCompleteText" placeholder="Select an option" />
<script>
	$('#MyAutoCompleteSelect').autoComplete();
</script>

Date-select

This is a very basic date select control, and was created purely to illustrate the versatility of the Selectioner. Most modern browsers have solved this problem already.

Notice that it targets an input type="date" instead of a select element this time.

<input type="date" id="DateInput" placeholder="Choose a date"/>
<script>
	$(function(){
		$('#DateInput').dateSelect();
	});
</script>

Build your own!

You can write custom Selectioner controls quite easily, and even chop-and-change what parts are shown. You are not limited to targetting just select elements either, as the date-select illustrates.

Read the comments in the following example to see how this is done:

<select id="CustomSelect">
	...
</select>
<span id="CustomButtons" style="border-top: 1px dotted #CCC; text-align: right; display: block;">
	<a href="javascript:;" class="button">Close</a>
</span>
<script>
	$(function(){
		var staticDialogCss = 'font-style: italic; color: #999; text-align: center; margin-top: 4px; border-bottom: 1px dotted #CCC;'
		var staticDialogHtml = '<div style="' + staticDialogCss + '">Base Colour</div>';
	
		// Build the custom selectioner.
		var customSelectioner = new Selectioner
			(
				// This is the obect that the Selectioner will target as it's 
				// underlying element. This is usually an input, select or textarea.
				$('#CustomSelect'), 	
				
				// This is what displays what is currently selected to the user. 
				// You can make your own by inheriting from Selectioner.Core.Display.
				new Selectioner.Display.ListBox(),	
				
				// This is either a single Dialog, or an array of them. Dialogs are what
				// appear in the popup. You can either create static dialogs that are
				// unaware of the rest of the Selectioner, or add objects that inherit from
				// Selectioner.Core.Dialog that will update whenever the selected value 
				// changes. In this example, only the SingleSelect() dialog does this.
				[
					staticDialogHtml,
					new Selectioner.Dialog.SingleSelect(),
					'#CustomButtons'
				],
				{	
					// Add custom options here. This overrides Selectioner.DefaultSettings.
				}
			);
		
		// Hook up an event handler to the button's click event.
		// To clarify, events that are set up before the selectioner 
		// is created will continue to work in cases like this as well.
		$('#CustomButtons .button').on('click', function() { customSelectioner.display.popup.hide(); });
	});
</script>

General Settings

The following global settings will affect all Selectioners on your page. These are their defaults:

Selectioner.DefaultSettings =
	{
		cssPrefix: 'select-',
		noSelectionText: 'Select an option',
		emptyOptionText: 'None',
		noOptionText: 'No options available',
		noMatchesFoundText: 'No matches found',
		typeToSearchText: 'Type to search',
		filteredSelect:
			{
				maxItems: 5,
				minFilterLength: 1,
				enterOneMoreCharacterText: 'Enter 1 more character',
				enterNumberMoreCharactersText: 'Enter {{number}} more characters',
			}
	};

Some of these are editable per-control with the following overrides:

noSelectionText

Add a data-placeholder attribute to the underlying select element.

Alternatively, in the case of Combo-selects and other controls that support it, you can set the placeholder attribute on that control instead. This can be overridden by a data-placeholder attribute however.

Development

How it's built

Built in a modular pattern with prototyping in mind.
RequireJS has been used in order to allow for build optimizations (still a work in progress).
The build process uses NodeJS with Grunt to build the project. This includes:
- JSHint to detect errors and problems within the source code.
- RequireJS Optimizer. The dependency on this is removed however, but the project output is still AMD compatible.
- UglifyJS2 to minify the JavaScript.
- LESS to build it's LESS files into CSS files.
- Clean-css to minify the generated CSS.
The project has written in strict mode.

How you can build it

If you've never built the project before, download nodejs.org, and make sure that you have the Node Packet Manager (NPM) installed (this usually comes bundled with Node).

Once that's done, you're going to need Grunt. You can obtain this with NPM via the following command:

	$ npm install -g grunt-cli

Thereafter, build the solution from the project's root directory with the following command:

	$ grunt

If the RequireJS task refuses to work for some reason, run the following:

	$ npm install grunt-contrib-requirejs --save-dev

hrudham/Selectioner