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.
Usage
HTML
jQuery
Data from backend:
;
Data from frontend:
;
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
whereterm
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)
whereterm
is the search term andresponse
is a function to call with the resulting list. The argumentdelay
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
{return '(' + RegExp + ')' '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
{if !term return {return string;};var re = options;return {relastIndex = 0;return re;};}
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
and
To turn off the default cache, specify cache as null
.
DOM manipulation
When an input element
is turned into a lhcombo, it is wrapped in the following way:
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.