Guillaume Hébert sent me a note to say thanks for the article, and to point out even local data can be used like this:
If you load the data locally instead of calling an URL, you can do the same
effect by doing:var data = []; data.push( [ company_name, company_id ] );
Thanks Guillaume!
I have a web form where the user has to select from potentially thousands of companies. The normal solution would be to use a drop down list (ala the standard HTML <select> tag). However, this is cumbersome with a large number of entries. Not to mention you suffer a bandwidth penalty to load that full list everytime the page is loaded. A better alternative is an autocomplete type box. A standard text box that shows you a filtered list based on what you have typed in the text box. That list could be Ajax driven to be more dynamic.
While jQuery itself doesn't provide this feature, it is a common enough thing that people have developed plugins to provide autocomplete capabilities via jQuery. Unfortunately, the autocomplete landscape is a little confusing at this time. The problem is that there are a number of different autocomplete plugins, but some have been abandoned, or encorporated into another. This makes it hard to decide which plugin you should be using.
Let's make this clear - the correct autocomplete plugin to be using (at this time at least) is the one developed by J örn Zaefferer and is available at http://bassistance.de/jquery-plugins/jquery-plugin-autocomplete/. This plugin has enhanced the other common autocomplete developed by Dylan Verheul and later enhanced by Dan G. Switzer. These three authors are collaborating and it seems Jörn's plugin is becoming the standard.
The unfortunate side effect of this is that the documentation is a little lacking. So doing anything other than the basics can be frustrating. As in my page where I need the ID of the company database record, but want to display the company name to the end user. This is not covered in the documentation clearly. So, after working it out for myself, I wanted to document what I learned to help out others, and remind myself when I need this again.
Here's the trick.
1. Your server side code should return your results like this:
- company_name|id chr(10)
We use the default "cell separator" of the horizontal line (aka a pipe) to separate related data. We then use a newline character (the chr(10) ) to indicate we are moving onto the next entry. So in short, one entry per line, with the ID separated by a pipe.
2. The autocomplete plugin will handle this input format for you properly on it's own. You do not need to modify anything if you are just using the name portion of your results. But to access the ID, well, that takes a little more.
3. The autocomplete plugin has a .result() method that gets added to our target form element. This method is fired anytime a selection is made from the autocomplete list. The method is passed three parameters - the event object, the raw data of the chosen item, and the formatted text of the chosen item. We can make use of the raw data like this:
$("#mytextbox").autocomplete("clients.php")
.result(function (evt, data, formatted) {
$("#hiddenIDbox").val(data[1]);
});
The magic is that the raw data is in the format of an array. If we know the ID is the second element we defined in our result line (the server side code), then the ID will be the second element of the raw data array. In the sample above, we are simply putting that ID value into a hidden form element for later processing. Of course, we can do whatever we want within the result function - alert it, use the ID to update other elements, etc.
This particular task has been a major stumbling block for me with regards to autocomplete boxes. Most such boxes assume you are only dealing with text and that is all you care about. Jörn's plugin handles the more advanced use of IDs, but the documentation is lacking at this time. (have you seen all the stuff that Jörn is involved in???? - I'm not surprised documentation is a little behind... :) With this trick, I can now easily integrate autocomplete boxes into my applications. I have conversed with Jörn on the jQuery mailing list and know he is looking at addressing this and many more items. In particular he wants to provide an easy way to have the plugin handle the IDs automatically for us developers. I'm most definitely looking forward to his efforts.
And hopefully this post helps out someone as well.