laktek/jquery-smart-auto-complete

AutoComplete plugin with smart defaults and flexibility to customize

jQuery Smart Auto Complete plugin

Requirements

jQuery 1.5 or above

Usage

In the header section of your page, add two script tags referencing to core jQuery and smart autocomplete plugin. It should look similar to code below:

<script src="jquery.js" type="text/javascript"></script>
<script src="jquery.smart_autocomplete.js" type="text/javascript"></script>

To activate the plugin call smartAutoComplete method with options on target jQuery object.

<script type="text/javascript">
$(function(){

 $(target).smartAutoComplete({options})

});
</script>

Options

minCharLimit (integer)

default: 1

Sets the minimum characters user have to type before invoking the autocomplete

maxCharLimit (integer)

default: unlimited

Sets the maximum character range auto-complete will offer suggestions. Useful in free-form fields.

maxResults (integer)

default: null (means unlimited)

Sets the maximum number of results to return.

delay (integer)

default: 0

Sets the number of miliseconds plugin should wait, before calling the filter function.

disabled (boolean)

default: false

Sets whether autocomplete is disabled on the field.

forceSelect (boolean)

default: false

If set to true, field will be always filled with best matching result, without leaving the custom input. Better to enable this option, if you want autocomplete field to behave similar to a HTML select field. (Check Example 2 in the demo)

typeAhead (boolean)

default: false

If set to true, it will offer the best matching result in grey within the field; that can be auto-completed by pressing the right arrow-key or enter. This is similar to behaviour in Google Instant Search's query field (Check Example 3 in the demo)

source (string/array)

Defines the list of items to be filtered. You can give a hardcoded array or a string containing a URL, which will return a JSON array, as the source.

Note: Your can omit this option or provide a different object, if you are defining your own filter method.

filter (function)

parameters available: term, source

Define a custom function that would return the matching items for the term (this will override the default filtering algorithm) Function should return an array or a Deferred object (ajax call)

resultFormatter (function)

parameters available: result

The function you supply here will be called to format the output of an individual result. Function should return a string

resultsContainer (selector)

Define to which element(s) the results should be appended.

resultElement (selector)

References the result elements collection. It should be a jQuery selector which could capture all result elements within the results container (e.g. li, div.result).

Events

Following custom events will be available to the element which has smartAutoComplete activated. You can bind handlers to these events like other jQuery events and also cancel the default handler by calling event.preventDefault().

Note: Make sure you bind the handlers, only after smartAutoComplete is activated on the field. Otherwise context data could get overriden.

To learn more about the default behaviour of the events, please refer to the specs at spec/core/jquery.smart_autocomplete_spec.js.

keyIn

parameters: query

Fires when user type something in the field

resultsReady

parameters: results

Fires when results are ready (returned from the filter function)

showResults

parameters: results

Fires after results are added to the results container

noResults

Fires if filter function returned no results

lostFocus

Fires when autocomplete field loses focus by user clicking outside of the field or focusing on another field. Also, this event is fired when a value is selected

itemSelect

paramters: item

Fires when user selects an item from the result list

itemFocus

paramters: item

Fires when user focuses on an item in results list with mouse or arrow keys

itemUnfocus

paramters: item

Fires when an item in results list looses focus

Styling

Following classes will be used to reference elements added by jQuery Smart Autocomplete plugin.

smart_autocomplete_container - A ul element containing the results.

smart_autocomplete_highlight - This class will be added to a result element when it's focused.

smart_autocomplete_type_ahead_field - If typeAhead option is enabled, additional field will be added behind the autocomplete enabled text field.

Learn More

Introducing jQuery Smart AutoComplete

Demo

Basic Examples

GitHub Instant Search Example

Copyright (c) 2011 Lakshan Perera (laktek.com)

Licensed under the MIT (http://www.opensource.org/licenses/mit-license.php) licenses.

jquery-smart-auto-complete's Issues

Documentation Issue

Just an FYI, your documentation says to listen for the "noMatch" event for when no results are available. This should be "noResults".

lostFocus event can fire twice..

When enter is pressed, the event fires once, but when the item is selected with the enter key, the event fires twice. Fixing temporarily with _.throttle

Pressing enter with no selection resets field

The jQuery Smart AutoComplete is powerful and very useful!

I was wondering if it is possible to configure the Smart AutoComplete so that if someone presses enter without selecting an item in the suggestion list so that the list remains visible and the field is not emptied? What I would like to do is force the user to choose one of the items in the list of suggestions.

Many people have the habit of typing in the search field and hitting the enter key, instead of pressing a button... and they may be frustrated to see that their search is not performed and the criteria they used has disappeared.

I've tried setting forceSelect option to false, but it had no impact.

Thank you in advance for your help!
lbriquet

Working with ids?

With select boxes, the labels and the actual values of the options are decoupled so you can show a nice formatted text to the user and still get an id back to plug directly into the database. I couldn't find an easy way of doing that with your plugin?

forceSelect not working properly

input keeps on being set to null value after hitting enter

my solution ( worked fine ):

$.event.special.itemSelect misses check if forceSelect is enabled or selected_value is set

so line 291 with $(context).val(selected_value);

should become (options.forceSelect || selected_value) && $(context).val(selected_value);

this fix worked just fine for me

Hyperlinks in results?

Is there a way I can implement hyperlinks in results?

Right now it seems that if I click a link in a result item, it's functionality is hijacked by Smart Auto Complete which triggers an ItemSelect event.

IE bug - clearResults not working with itemSelect/itemFocus

Hello,
I've run into a problem with clearResults in IE only. In IE when you submit the form by selecting an item (itemSelect or itemFocus) in IE and then use the browser back button the field is not emptied (still contains the selected text) . This does not happen in FF or other browsers.

IE Click item does not register

Plugin not registering when clicking an item in IE.
Works by pressing enter though.

Tested with IE9

Page click elsewhere to close menu

I have it fixed like this:

$("#goal_name").smartAutoComplete({
    maxResults: 5
    delay: 200
    forceSelect: false
    resultsContainer: $ '#typeahead_search_results'
    filter: (term, source) ->
      $.ajax({
        url: "/goals/find.json",
        type: 'get'
      })
    resultFormatter: (result) ->
      "<li>#{result.name}</li>"
    }).bind({
      blur: (event)->
        # we allow the click event to trigger if one of our LIs was clicked on.
        # 100ms not enough. will 200 be on all machines?
        setTimeout(()->
          $("#goal_name").trigger('lostFocus')
        , 200)
    })

Can you turn on the wiki please?

Boldface typed text in search results

It would be nice if we could boldface the searched text in the results, so for example, if we had typed "cat" into the query field, the results would be:

<ul>
  <li><em>Cat</em>ch-22</li>
  <li><em>Cat</em>cher in the Rye</li>
  <li>The <em>Cat</em> in the Hat</li>
  <li>Felix the <em>Cat</em></li>
</ul>

To turn this one it could be one simple option:

emphasis: true

Great job with this by the way.

error: a.compareDocumentPosition is not a function

Hi, just trying out the plugin, but getting errors... also finding the same errors @ the github_instant demo

tested in firefox3.6, firefox 4.

to reproduce:

load the demo @ http://laktek.github.com/jQuery-Smart-Auto-Complete/demo/github_instant
click into search_field

• error (firebug):
  " a.compareDocumentPosition is not a function jquery.min.js (line 16) "

binding multiple elements

Problems trying binding multiple elements.

$('.produto').smartAutoComplete(
{source: ['Apple', 'Banana', 'Orange', 'Mango']
});

This doesn't works

Sry my english xp

IE Click item

In IE selecting an item by mouse clicking the item was not working.
I changed this code about line 500 FROM:

$(options.resultsContainer).delegate(options.resultElement, 'click.smart_autocomplete', function () {
$(options.context).trigger('itemSelect', [this]);
return false
});

TO
$(options.resultsContainer).delegate(options.resultElement, 'mousedown.smart_autocomplete', function () {
$(options.context).trigger('itemSelect', [this]);
return false
});

Check for multiple instances on one element (problem!)

I add my input fields dynamically to the dom, or if there is already data i have multiple fields given. All of them using the same class. If i now bind the plugin on these elements it cause problems. I like the pattern to use 'data' to check if the plugin already exists on an element.

I did it like this...

return this.each(function(i) {
if($(this).data("smart-autocomplete")){
return something....
} else {
init events.....
}
}

Would be cool to have this, especially for event driven plugins :-)

Possibility to submit with Enter without selecting

For the use case of search suggestions it would be nice to have an option to submit a search with the enter key even if none of the completion suggestions were selected. Right now that doesn't seem to be possible because keyCode 13 is always caught and resets the textfield.

Or am I missing something?

TIA,
bkw

Escape Key Support

I think supporting the loosing of the list-focus through a hit of a button would be nice to have.

right arrow submits when mid-string

I don't know if there's any way to detect cursor position with js, but currently the form will submit if someone goes back and forth to change a typo

Selected items appear again in comma separated list autocomplete

In a comma separated list, with auto-completion, after I have already selected an option it shows up again in autocomplete.

eg. If I have already chosen United States as one of my Favourite countries then it should not show up again in autocomplete but it does appear again.

lack of triggering "change" event

after item form suggested items is selected.

binding to itemSelect returns previous value of input (before setting it to selected item's value)

proposition of fix:

• add option triggerChange:false
• add to <code$.event.special.itemSelect default function options.triggerChange && $(context).trigger('change');

Why set inline styles on the text field?

Specifically, why set "background: #FFF" (line 114)?

Why not capture the original bg color of the text field and use this when clearing the field?

Smart_autocomplete_multi select

Facing following error : Cannot read the property 'query'
while implementing smart_autocomplete_multiselect