jQuery Autocomplete Plugin
Some notes from looking at Yehuda Katz and Rein Henrichs autocomplete plugin:
- I don’t understand when authors of provide no documentation. Programmers don’t really like doing documentation but this would get many more people to use the plugin.
- It took me a while to figure out what events like ‘click.autocomplete’ were. Turns out that jQuery has a mechanism where you can namespace your events. Here is another writeup about it. Nice idea.
- Getting the key in a event callback in a cross browser manner can be done succinctly like: var k = e.which || e.keyCode; I already knew about this as I know that many others do but it’s nice to note. You would think that jQuery would hide this detail. Also, I always wondered why jQuery didn’t have a map for the common keycodes. I guess you have to do it yourself: var KEY = { ESC: 27, RETURN: 13,…};
- Note that the version from the site above works on IE, the one in the svn jQuery source base doesn’t.
The plugin is very succinct and I wanted to study it; these are my notes.
The plugin is split up into 2 files: jquery.ui.autocomplete.js and jquery.ui.autocomplete.ext.js. The ext file is optional, but if you are going to use it, include it before the main plugin file. I’m actually not sure why it’s optional and I would just include it in the main plugin. It has 2 methods: ajax and templateText (in the $.ui.autocomplete.ext namespace). In the main plugin, the ext methods are used like this:
112 if($.ui.autocomplete.ext) { 113 for(var ext in $.ui.autocomplete.ext) { 114 if(opt[ext]) { 115 opt = $.extend(opt, $.ui.autocomplete.ext[ext](opt)); 116 delete opt[ext]; 117 } 118 } }
This goes through all items in $.ui.autocomplete.ext (the 2 methods) and merges them iff the options already include those methods (line 114). It merges them (line 115) by calling the method in ext with the opt hash as the parameter and merges in the return value which is a hash; this is why the ext methods take opt as the parameter and return a hash that replaces some methods in the original opt hash. Note that it deletes the opt hash element for the ext value (line 116). This is the first time I’ve seen this type of extension mechanism. Hmm, a little obscure; I’ll reserve judgement for now.
Note how these are used in the HTML file (autocomplete.html):
29 ajax: "list", 32 templateText: "<li>Hey: <%= text %></li>" 53 templateText: "<li><%= pre_match %><span class='matching' ><%= match %></span><%= post_match %></li>" 57 ajax: "list", 60 templateText: "<li>Hey: <%= text %></li>"
It should be pretty obvious what the ext methods do (jquery.ui.autocomplete.ext.js):
18 $.ui.autocomplete.ext.ajax = function(opt) { 19 var ajax = opt.ajax; 20 return { getList: function(input) { 21 if (input.val().match(/^\s*$/)) return false; 22 $.getJSON(ajax, "val=" + input.val(), function(json) { input.trigger("updateList", [json]); }); 23 } }; 24 }; 25 26 $.ui.autocomplete.ext.templateText = function(opt) { 27 var template = $.makeTemplate(opt.templateText, "<%", "%>"); 28 return { template: function(obj) { return template(obj); } }; 29 };
Oh, it would probably help if you knew what the options actually were:
- timeout: integer The timeout in ms after user typing idle and autocomplete list appears.
- getList: function(input) Function called on main input element to show the autocomplete list.
- template: function(str) Returns a single autocomplete list line for a match.
- insertText: function(str) Returns the autocomplete text for a single line.
- match: function(str) Return true or false, whether the typed str matches an autocomplete item.
- wrapper: string The wrapper (pair of HTML elements) to wrap the autocomplete list in.
The default option values (jquery.ui.autocomplete.js):
103 opt = $.extend({}, { 104 timeout: 1000, 105 getList: function(input) { input.trigger("updateList", [opt.list]); }, 106 template: function(str) { return "<li>" + opt.insertText(str) + "</li>"; }, 107 insertText: function(str) { return str; }, 108 match: function(typed) { return this.match(new RegExp(typed)); }, 109 wrapper: "<ul class='jq-ui-autocomplete'></ul>" 110 }, opt);
That should be enough to give you an idea of how to get the plugin working. And now we are ready to roll up our sleeves and see how the plugin actually works. That will have to wait for the next post.
2 Comments