jquery.lhcombo

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
`` html

`

##### jQuery

Data from backend:
` javascript
$('[name="foo"]').lhcombo({source: 'data.pl'});
`
Data from frontend:
` javascript
$('[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
` javascript
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

` javascript
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

` javascript
add: function (term, list)
`
and
` javascript
get: function (term)
`

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

DOM manipulation

When an input element
` html

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


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

1.0.0:
* Initial release.