Notes on the Bassistance jQuery Autocomplete plugin
This plugin has some key features we employ, that I’ve yet to find in others, so we’ve stuck with it. But, it also has some bugs or idiosyncrasies that have made it quite frustrating at times. These notes are now my catalog of these issues.
Some of the reasons we’re using this plugin vs. others:
- returned results can contain HTML to affect a style
- returned results can include data, not just the matching text to put in the field. This allows us to match an item, and then inject other data that we need into the DOM. For example, matching a city, it lets us store the city’s ID, its state, and country, in hidden form fields, so that we can send that data to a third party site if needed (e.g. metasearch). This reason alone prevents using any other plugin I’ve seen (including the new autocomplete in jQuery UI 1.8).
- it supports must match. This has been a pro and con. It has some bugs, but is useful. You could implement this yourself with other controls.
We typically disable caching, because we limit the number of returned results. With limited results, it means that we need to re-search for a more refined query string, because there may now be results that would match that weren’t originally returned. Example, for cities, typing in “San” would yield about 120 cities, and we don’t want to return or show all those, so we only send back 10 or so. But, then, refining that search would fail to find 110 cities if caching were used.
A bug in the plugin occurs where caching will be used, even if you specify cacheLength:1, unless you also explicitly specify multiple:false. Unknown why.
One can get incorrect results due to AJAX race conditions. As you type a query, each letter (or some amount – depends on the delay setting) will issue another AJAX query. But there is no guarantee on the order in which these async AJAX queries come back. So, when you finally stop typing, you may wind up with the results from the very first query you initiated, which would be wrong.
To solve this, need to use an AJAXqueue. Bassistance supports the jQuery ajaxqueue out of the box. jQuery 1.3 broke the ajaxqueue plugin, but another guy updated it for 1.3 and later, and that now works. That code is available here
However, the ajaxqueue breaks when mustMatch:true is used with the autocomplete. The behavior is that the text field will get cleared out as AJAX requests get aborted, but then the autocomplete will show up at the end when you’re done typing (yet you’ll have an empty field). To fix that, changed the mode from “abort” to “query” in the Bassistance plugin. We did this for all cases, but you could special case it so it only did this when mustMatch was in use. But, the other downside of using “abort” mode, is that you don’t see intermediate results. i.e. the user doesn’t see autocomplete matches occurring as they type. You may or may not care about that.
The “mustMatch” option is very useful if you want to only allow using known choices. However, it has some problematic behaviors:
- you need to explicitly set the “multiple” option to false with this, otherwise it just doesn’t work.
- When the user selects an autocomplete item from the list, the autocomplete control sends that text back as another search. I don’t understand why, as the user has just made a choice, there’s no reason to do so again. This may be more of an event type of bug (e.g. new text has gone in, so it’s doing a search because a “change” event happened or something). Regardless, this is a huge problem if the text that you return as result text, is not sourced from the same thing you search on, because then this second search will fail, and thus wipe out the text you had just selected. Example: you are searching on cities. You search a database table of city names, but the text you return includes the state and/or country to help disambiguate the choice to the user. e.g. the user types in Portland, and you return “Portland, OR” and “Portland, ME”. The user picks “Portland, OR”, and that text will briefly go into the control, but then get sent as another search. The search will fail, because “Portland, OR” is not the pure name of a city. With the failed search, the control then wipes out the text. To remedy this, what we’ve had to do is look for such situations, and for example, remove all text from the comma on when receiving a query.