SmartTextBox or Facebook-Style Name Picker is a jQuery plugin

Introduction

SmartTextBox is a jQuery plugin that turns text inputs into javascript driven widget that allow navigating the options using keyboard, auto completion and many other features, while being fully customizable. The plugin is inspired by Guillermo Rauch’s TextBoxList, at the time his plugin was only available on mootools. The plugin was originally supposed to be used only on internal projects, but as time passed, I decided to clean it up and to publish it in jQuery plugin’s list.

Current version

The current version of SmartTextBox is 1.2.0-rc1

Demo

A demo page of the most common usages of the SmartTextBox plugin is available here.

Sources

The sources are availables in the WOPU project, hosted by googlecode, there

Download

The plugin is downloadable here. For direct download of the lastest version just click there.

Requirements

SmartTextBox required jQuery 1.2 or higher.

Installation

Just download the plugin, be sure you already have jQuery included on your pages, copy the files, then simply add in the headers :

License

SmartTextBox comes under the GPL license.

Browsers support

SmartTextBox supports all major browser (IE6/7/8, FF2/3, Chrome, Safari, Opera)

Usage

SmartTextBox follows the jQuery principles in terms of usage and accessibility. Creating a SmartTextBox from an input is very easy :

$("#myInput").smartTextBox();

SmartTextBox is fully customizable, and options can be passed as follow :

$("#myInput").smartTextBox({submitKeys : [13], autocomplete : true, separator : ";"});

Options

Here is the list of options usable when creating a SmartTextBox :

key	default	description
autocomplete	true	activate or desactivate the autocompletion feature
minSearchLength	2	min length of text to type to receive autocompletion suggestions
maxResults	10	max number of results to display by autocompletion widget
caseSensitive	false	if true, search will be case sensitiv
highlight	true	highlight matching parts in autocompletion results
fullSearch	true	search at start of values or in all the string
placeholder	see desc.	placeholder text to display when autocomplete widget enter focus. Default to “Please start typing to receive suggestions”
autocompleteValues	[]	List of values to be used as suggestions for autocompletion
autocompleteUrl	null	url to use to load autocomplete values at initialization. The return format must be a simple JSON object with a “values” key containing a list of String
onlyAutocomplete	false	if set to true, boxes can only be created from autocomplete values
uniqueValues	true	if true, values can only be added once
hideEmptyInputs	true	To hide or to display empty inputs on a blurr
editOnFocus	false	When true, box elements will change back to edit mode when focused
editOnDoubleClick	false	When true, box elements will change back to edit mode when double clicked
submitKeys	[13]	List of key codes used to save an input to box (default : enter key)
submitChars	[ ";", ","]	List of chars used to save input to box
containerClass	“smartTextBox”	Base css class used on SmartTextBox containers and elements
separator	“;”	separator character used to split values from original input and serialize it back
updateOriginal	true	If true, the original input value will be updated everytime the SmartTextBox values changes.
debug	false	If true, will output some debug logs to the firebug console (and will make IE crash on the missing console.log object)

Events

SmartTextBox also allow the wiring of custom user events. All events handlers are fired with 2 parameters : the first is the element triggering the event, the second is the SmartTextBox object which the element is attached to. The events are customizable by the following keys in the options :

key	default	description
onElementAdd	null	Fired when a box element is added
onElementRemove	null	Fired when a box element is removed
onElementFocus	null	Fired when an element is focused
onElementBlur	null	Fired when an element looses focus

API

Once created, the SmartTextBox API calls can be accessed through the $(“#myInput”).smartTextBox method :

method	usage	description
add	$(el).smartTextBox("add","a label")	Add a box to the end of the SmartTextBox list
remove	$(el).smartTextBox("remove",labelOrIndex)	Remove a box from the list. Can be used to remove by label or by index
load	$(el).smartTextBox("load", values)	Empty the list, and then add all the specified values. “values” can be a list of string, or a string with the options.separator separator char
clear	$(el).smartTextBox("clear")	Empty the current list
autocomplete	$(el).smartTextBox("autocomplete", values)	Sets the list of values to be used as suggestions for autocompletion. The value can be a list of string, or a string with the options.separator separator char

Changelog

1.2.0-rc1 – 2010-08-14

• New features

- new ‘autocompleteUrl’ option : can now load list of autocomplete values from an json ajax call (one time values load)

- new ‘onlyAutocomplete’ option (default to false). When set to true, The SmartTextBox will only accept labels added from the autocompletion list.

- new ‘uniqueValues’ option (default to true). When set to true, the SmartTextBox will only accept the labels once (that mean a label cannot be added more than once). Also, when this mode is active, the autocompletion will not propose already-added labels.

- autocompletion search mode can now be choosen between ‘start of word’ and ‘full text search’ ( see the ‘fullSearch’ option )

• Changes

- major change in the autocomplete configuration : autocompleteOptions map has been remove. Now autocomplete configuration is made directly in the SmartTextBox options map.

This cause the following options rename :

- minLength renamed to minSearchLength

• Bug fixes

- deleting elements using keyboard now correctly focus previous or next element.

- autocomplete options are now correctly passed to autocomplete instance at SmartTextBox initialization.

- autocomplete results are now correctly highlighted.

1.1.2 – 2010-08-12

• Bug fixes

- backspace key now works back as intended when typing text in boxes

1.1.1 – 2010-08-12

• Bug fixes

- fix plugin for IE6 ( stupid comma… )

- use of backspace key to delete boxes now longer cause the browser to go to last page

1.1 – 2010-08-03

• New features

- added custom event wiring capability

• API Changes

- the method “values” renamed to “load”

• Bug fixes

- the API methods “load” and “autocomplete” can now work with lists as intended

- the API method “remove” can now work with an index as intended