jQuery: QuickSelect

The QuickSelect plugin allows you to create a text input with a list of specified options, and as you type, those options show up in a list below the input box. You can choose to have it auto-fill the top result into the input box as you type, or select an option using the arrow keys.

There are a few special powers of this plugin:

1. QuickSilver selection mode: As you type, it will use quicksilver ranking mode, and the top result will automatically be selected when you exit the field.
2. Select/Options transformation: If you run .quickselect() on a select element, the data from the options will be stored and the select will be turned into an input box of the same id and className(s), and a hidden input of the same name. That way, instead of using a select, the user can simply type what they want and choose from the list. Just render your HTML page with a select and options, and run this plugin to turn it into a quickselect.
3. Multiple-field update: Send a jquery object containing multiple input elements, and include a corresponding number of values in the results data, and each input element will be updated with its corresponding value from the data when an item is selected from the drop-down list.

Installation

1. Include the jquery library in your project.
2. Then you’ll need the following files for this plugin:
   • quicksilver.js
   • OR fuzzy-string.js
   • jquery.quickselect.js
   • jquery.quickselect.css

Usage

There are several modes in which you can use this plugin…

The simplest may be just transforming a select/options group into a text input with drop-down. $(“select”).quickselect(); will do the trick. Running this on a select element will use default options that work best for this type of quickselect control.

The next mode you might use is ajax. $(“input#city_name_field”).quickselect({url:‘/ajax/cities.json’}); should do the trick.

Try this mode to make a richer application. Same as the ajax, but include more fields in your json data: $(“input#city_name_field”).quickselect({url:‘/ajax/cities.json’, additionalFields:$(“input#zipcode_field”)}); In your json data, instead of just spitting out an array of city names, make each array element be a two-element array, the first element being the city name (for the field you’re typing in), and the second being the corresponding zip code for that city. That way when you select a city, it’ll automatically populate the zipcode too! This also works really well for when you need to select a human-readable label but have the actual value be a resource id. Just make a visible text input into a quickselect but in your additionalFields mention a hidden field, and in your data just include the label and the id.

Note, if you include quicksilver.js or similar.js, quickselect will automatically default to using their pretty smart similarity matching methods.

• Sample simple option selection: $(“input[type=text]#sample1”).quickselect({data : [‘Option 1’, ‘Option 2’, ‘Option 3’]})
• Identical Sample, using data as second argument instead of part of options: $(“input[type=text]#sample1”).quickselect({}, [‘Option 1’, ‘Option 2’, ‘Option 3’])
• Sample Zip selection by city json data: $(“input[type=text]#sample2_zip”).quickselect({data : [{label:‘Jonstown’,value:22781}, {label:‘Hilariton’,value:91287}, {label:‘Chicago’,value:60610}]})
• Sample City & Zip selection by City name: $(“input[type=text]#sample3_city”).quickselect({additionalFields : $(“#sample3_zip”), data : [{label:‘Jonstown’,values:[‘Jonstown’,22781]}, {label:‘Chicago’,values:[‘Chicago’,60610]}]})

Options

Two modes for data: Data, and Ajax.

• data: Include the array of selectable options here, either a flat array: “[‘option 1’, ‘option 2’]” or expanded with item options: “[{label : ‘option 1’, value : ‘value 1’, className : ’type_A’}, {label : ‘option 2’, value : ‘value 2’, className : ’type_B’}]”.
• ajax: if you want to load data via ajax, put the ajax url here. The query text will be appended as ?q=$value.
• ajaxParams: extra parameters for the ajax url if necessary. These will be encoded into a query string, along with the query (‘q’) value.
• additionalFields: (element or array of elements to be updated) one or more fields to update with the extra data. Not honored when converting a select/option group to a quickselect control. For example, you may want to provide quickselect on a zipcode field, but when selected, update the city and state field automatically with the results.
• delay: number of milliseconds after typing that the results are re-evaluated. Make this longer if your ajax is bogging down.
• minChars: the minimum number of characters before triggering the drop-down (and ajax, if applicable).
• matchCase: true/false – specify that the drop-down should be case-sensitive.
• matchMethod: One of ‘quicksilver’, ‘contains’, or ‘startsWith’. If not specified, ‘contains’ is default, unless quicksilver.js or similar.js is auto-detected (String.prototype.score() is defined), then ‘quicksilver’ is default, which matches that the first letter of query and result are equal (case-insensitive), and quicksilver matching on the rest of the query.
• autoSelectFirst: (default: true) always have the first matched item selected until the selection is manually changed; tab or enter will choose the top selection.
• selectSingleMatch: use this if NOT using autoSelectFirst, to make the control automatically select the top item when there is only one matched item left.
• exactMatch: use this if you absolutely need the typed value to end up matching one of the list items in the end. If something is typed but no match is found, the text field and all fields specified in additionalFields instantly get blank values.
• autoFill: true/false – use this if you want the text input to automatically try to finish what you’re typing as you type, based on the top match. This only works with the ‘startsWith’ match method.
• maxVisibleItems: limit the number of items shown in the list at any one time.
• extraOption: optional, add an extra option to always appear at the bottom of the results list.
• formatItem: optional, assign a function that will transform the item list labels. The function is called for each item with three arguments (item, index, total_count), and is expected to return a string.
• cssFlavor: choose one of the built-in flavors. Default is named ‘quickselect’. This causes the next four css classes to be set based on this flavor name, unless you set them explicitly.
• inputClass: css class for styling the text input box. Default options.cssFlavor+’_input’
• loadingClass: css class for styling the text input while loading ajax. Default options.cssFlavor+’_loading’
• resultsClass: css class for styling the drop-down items list. Default options.cssFlavor+’_results’
• selectedClass: css class for styling the currently-selected item in the drop-down list. Default options.cssFlavor+’_selected’
• width: sets the width of the drop-down list. (default: width of the input element)

Credit

http://www.pengoworks.com/workshop/jquery/autocomplete.htm – original starting point

Thank you to Sabretech and Argent for commissioning this project!