jQuery.lhcombo

A jQuery plugin that turns a text input into a combo box with auto-complete and pull-down select. Combines auto-completion with drop-down selection. Input is not restricted to items on the drop-down/auto-completion list.

Try a demo here.

Usage

HTML

<input type="text" name="foo">

jQuery

Data from backend:

$('[name="foo"]').lhcombo({source: 'data.pl'});

Data from frontend:

$('[name="foo"]').lhcombo({source: ["Ada", "Larry", "Richard"]});

Description

If you type ahead in the input box, a list of matching items will drop down, and you can select the desired one using arrow keys or mouse. If instead you click the drop-down button, the full list of choices will be shown.

Input is not restricted to items in the list.

API

The lhcombo method may be called with the following arguments:

|Arguments |Description| |----------------------|-----------| |OBJECT |Create lhcombo's. Barfs if a DOM object in the jQuery collection is already a lhcombo.| |'destroy' |Revert lhcombo's to normal inputs. Ignore DOM objects that are not lhcombo's.| |'created', |Is object a lhcombo?| |'options', |Get options as an object.| |'options', OBJECT |Set options as an object.| |'options', NAME |Get named option.| |'options', NAME, VALUE|Set named option.|

Options

source

Source for selection and auto-completion list. May be:

• An URL to use in Ajax request. If source is a string, it is assumed to be the URL of a data source. The URL is requested with argument t=term where term is the search term.

• A JavaScript array. If source is an array, that will be used as the data source. The elements of the array is filtered to match the search term.

• A function. The function is called with arguments (term, response, delay) where term is the search term and response is a function to call with the resulting list. The argument delay specifies a delay when function is called for auto-completion.

source is the only mandatory option.

button

Show drop-down button. Default: true.

preview

Preview mode.

When true:

• arrow keys change contents of input
• escape closes drop down and reverts input

When false:

• arrow keys just moves highlight in list
• escape just closes drop down

Default: false.

listMax

Maximum number of elements in auto-completion list. If list length is below this limit, it is opened automatically. Otherwise it it may be opened by hitting the down key.

Some Ajax auto-completers try to minimize the auto-complete list by by requiring a minimal length of the input string before sending an Ajax request. lhcombo takes another approach. It sends an Ajax request (if source is an URL) regardless of the length of the input string, but it only shows the result if it is no longer than listMax. This approach is chosen because with reasonable fast backend, the time showing a long list is not spend at getting data from the backend and formatting it, but at the browser setting up the list.

To have no maximal list length, specify listMax as null.

Default: 100.

delay

Number of milliseconds to wait after an input character is typed before sending an Ajax request (if source is an URL).

Default: 150.

regexp

Function returning a regular expressing based on a search term.

Defaults to

function (term) {return new RegExp('(' + RegExp.escape(term) + ')', 'gi');}

matchFct

Function returning a match function based on a search term.

Note that matchFct(term)(string) must be transitive: If matchFct(s1)(s2) and matchFct(s2)(s3) are true, then matchFct(s1)(s3) must be true.

Defaults to

function (term, options) {
   if (!term) return function (string) {return string;};
   var re = options.regexp(term);
   return function (string) {
      re.lastIndex = 0;
      return re.test(string);
   };
}

matchFct is not used if source is a function.

renderFct

Function returning a rendering function based on a search term.

cache

Function to use as a cache prototype. Is called with the options object as argument. The object created must have methods

add: function (term, list)

and

get: function (term)

To turn off the default cache, specify cache as null.

DOM manipulation

When an input element

   <input ...>

is turned into a lhcombo, it is wrapped in the following way:

   <div class="lhcombo-wrapper">
      <div class="lhcombo-input lhcombo-button">
         <input ...><button type="button"></button>
      </div>
      <div class="lhcombo-list"></div>
   </div>

The wrapping is removed if the destroy method is called.

Changelog

1.0.2:

• Avoid form submit when list is shown.
• Simplify usage of classes.
• Better imitation of native firefox look.

1.0.1:

• Wrap input and button in separate div and give it css attribute display: inline-flex.

1.0.0:

• Initial release.