Continuing from my last post.

Some notes:

• You can give a wrapped set as a second argument to a selector such as: $(’p', wrappedSet). This is the same as wrappedSet.find(’p').
• The CSS selector ‘> *’ returns direct descendants of an element. For example, $(’> *’, $(’ul.fred’)) would bring back the list elements of any list with class ‘fred’.
• The JS function window.clearInterval() will clear a timeout set with window.setTimeout().
• What’s fascinating for me about this plugin is the size of it, it’s very small. Now I realize that it doesn’t do that much but the kernel is there. See this post for a discussion of different jQuery autocomplete plugins. The author of the bassistance autocomplete plugin (Jorn) has an interesting first comment.

What’s nice about this plugin is that it’s event driven. Sometimes that makes it hard to follow, but if you keep in mind to “just follow the events”, it’s not that hard. So, here are the events we need to follow:

These are the main input (autocomplete input text box) events:

• keyup Main input event that sets up the typing timeout (delay to autocomplete).
• keypress Main input event that
• autocomplete This is the event that triggers the autocomplete on an input control. See the autocomplete binding method for the behavior. Sets up a ‘one’ binding for the updateList event that does most the work.
• updateList This event updates the list and starts the autocomplete on the input after setting up the container (opt.wrapper element). This calls autocompleteMode which does the work.

These are the autocompleteMode events:

• activate.autocomplete This event is when the highlighted autocomplete list item is selected; either via the enter key or via a mouse click. Note line 51: active && input.trigger(”activate.autocomplete”, [$.data(active[0], “originalObject”)]); the input element does not have an actiavate.autocomplete handler on it but one can be added an dwill be called. This is the same for the cancel.autocomplete and itemSelected.autocomplete events.
• cancel.autocomplete This cancels the autocomplete, either from an escape key or from a click on the window object.
• off.autocomplete Does the work of actually turning off the autocomplete.
• itemSelected.autocomplete Triggered on input when autolist item is selected.
• keydown.autocomplete Straightforward; handles special keys (ESC, RETRUN, UP, DOWN, TAB).
• click.autocomplete Click handler.
• mouseover Mouseover handler.

The key event handlers are on the input element and the mouse event handlers are on the container (wrapper) element and the body/window.

Another thing to have in mind are the data contents for the elements:

• autocompleteMode (document.body) holds the current state of autocomplete on the current control; true if the autocomplete list is showing, false otherwise. Note that a global is all that’s needed since only one control is active at a time.
• suppressKey (document.body) if set, keypress on input element is cleared and returns ignoring key. This suppresses the up/down keypress when navigating the autocomplete list from clearing the autocomplete. This is not necessary since IE does not have a keydown/up keypress event; unfortunately, this suppresses valid keys in IE. See discussion here.
• originalObject (single element of autocomplete list, i.e. opt.template) this is set on every list (or opt.template) element in the matching autocomplete list. This is not state but rather a way to get back to the original object when an autocomplete item is selected.
• typingTimeout (input) the return from the setTimeout function so we can clear the timeout later. Not state.

Some other notes:

• I like how container is created around the autocomplete list and to remove you just have to do container.remove().
• I metioned the namespaced events in previous post, but this plugin makes nice use of them.
• The filter and map on list (lines 164-170) is very perlish/lispy; I love it.

I’m using a modified version with these changes:

• Fixed console in autocomplete.html for IE7.
• Fix suppressKey for IE (see above).
• Fix pressing tab/down/up before typingTimeout. (Not setting/clearing typeTimeout data on same element.)
• Bring down autocomplete list immediately on arrow up/down.
• Update autocomplete list on backspace and delete.
• Added a few comments prefixed with [B]

If you want it, I’ve zipped it up here:
jquery.autocomplete-0.7.1

Postscript: I know the detail is way too much on last few posts unless you are studying these in depth. But I needed to go though these and these are my notes. So … whatever :)

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.

I wanted to take a look at the templating plugin included in the jQuery distribution (for some reason, there is no documentation of it on jquery.com, this is the same templating plugin included in ReinH/Katz autocomplete plugin here). It’s not the best documented plugin but it’s short so should be quick to figure out.

Basically, what this plugin does is take a block of text and interprets it as a template. What is a template? Well, for this plugin, think about JSP or ASP. I.e., executable code between special characters interspersed with HTML. So for example:

23       <% $(arr).each(function() { %>
24         <a href="<%= this.url %>"><%= this.text %></a>
25       <% }); %>

This code uses JSP like syntax where executable code is between ‘<%’ and ‘%>’ tags. And variable expansion uses the ‘<%=’ and ‘%>’; this means that the code inside the variable expansion gets expanded to the value in place (see this.url and this.text in example above.) Where does the arr variable come from? This is passed in as a context parameter to the completed template. Whoa, last 2 sentences need to be explained a little more. Look at the full HTML example distributed in the plugin itself:

 1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 2 <html>
 3   <head>
 4     <meta http-equiv="Content-type" content="text/html; charset=utf-8">
 5     <title>Templating</title>
 6     <script src="../jqueryjs/jquery/dist/jquery.js"></script>
 7     <script src="../jqueryjs/plugins/templating/jquery.templating.js"></script>
 8     <script type="text/javascript">
 9       jQuery(function($) {
10         $.pageTemplates = {};
11         $("script[type=text/x-jquery-template]").each(function() {
12           $.pageTemplates[this.title] = $.makeTemplate(this.innerHTML, "<%", "%>");
13           $("body").append($.pageTemplates["template1"]({arr: 
14             [{url: "http://www.yehudakatz.com", text: "Yehuda's site"},
15              {url: "http://www.gweezlebur.com", text: "Ivey's site"}]
16           }));
17         });
18       });
19     </script>
20   </head>
21   <body>
22     <script type="text/x-jquery-template" title="template1">
23       <% $(arr).each(function() { %>
24         <a href="<%= this.url %>"><%= this.text %></a>
25       <% }); %>
26     </script>
27     <a href="foo" rel="#myTemplate" class="updateTemplate">Click</a>
28   </body>
29 </html>

You can see the template itself in lines 22-26 cleverly embedded inside a script tag with a custom type attribute. Now look at the lines 11-17. Line 12 takes the template text itself and creates a template function. Yes, $.makeTemplate, the public templating plugin method, returns a function. That function is then called with a context parameter (a hash) and the template is evaluated. Note that the arr variable is passed into the template function on line 13.

Aight! What do you think of that? At first, I was like what the heck? but looking at it a few times now and it’s rather natural. Let’s look at the actual plugin next. It’s only 25 lines of formatted code:

 1 // Copyright Yehuda Katz
 2 // with assistance by Jay Freeman
 3 // You may distribute this code under the same license as jQuery (BSD or GPL)
 4 (function ($) {
 5   $.makeTemplate = function (template, begin, end) {
 6     var rebegin = begin.replace(/([\]{}[\\])/g, '\\$1');
 7     var reend = end.replace(/([\]{}[\\])/g, '\\$1');
 8 
 9     var code = "try { with (_context) {" +
10       "var _result = '';" +
11         template
12           .replace(/[\t\r\n]/g, ' ')
13           .replace(/^(.*)$/, end + '$1' + begin)
14           .replace(new RegExp(reend + "(.*?)" + rebegin, "g"), function (text) {
15             return text
16               .replace(new RegExp("^" + reend + "(.*)" + rebegin + "$"), "$1")
17               .replace(/\\/g, "\\\\")
18               .replace(/'/g, "\\'")
19               .replace(/^(.*)$/, end + "_result += '$1';" + begin);
20           })
21           .replace(new RegExp(rebegin + "=(.*?)" + reend, "g"), "_result += ($1);")
22           .replace(new RegExp(rebegin + "(.*?)" + reend, "g"), ' $1 ')
23           .replace(new RegExp("^" + reend + "(.*)" + rebegin + "$"), '$1') +
24       "return _result;" +
25     "} } catch(e) { return '' } ";
26 
27     return new Function("_context", code);
28   };
29 })(jQuery);

Very nicely written I would have to say.

Lines 6-7 munges the begin and end tags to be regualar expression friendly.

The next statement (lines 9-25) creates the code block. Note that the code block starts with a with (_context) { and returns the code block on line 27 with return new Function(”_context”, code). If you forgot what the with statement in JavaScript does, take a look here. There’s a bunch of regular expressions that I’m sure you can figure out (nothing too difficult), but a quick way to see what this is doing is adding the line ‘alert(code)‘ at line 26. Ahh, should be obvious now.

Doing this for the example, gives the text below and it becomes obvious:

try {
  with (_context) {
    var _result = '';
    _result += '       ';
    $(arr).each(function() {
      _result += '         <a href="';
      _result += ( this.url );
      _result += '">';
      _result += ( this.text );
      _result += '</a>       ';
    });
    _result += '     ';
    return _result;
  }
} catch(e) { return '' }

So to recap a few points:

• You can think of $.makeTemplate as a code generator returning a
  function to run the template with the passed arguments.
• The “code generator” works by creating the code as a string and passing it
  back using the Function constructor.
• The second part of the above, is that a context (hash) is passed to
  actually fill out the template.

How did i find this little gem? I just typed in coupons.com into my url bar. Why not, i thought.
Few interesting points:

• Enter your zip code and tada! coupons for your area. Sounds like someone else’s plan … :)
• Clearly aimed at large retail; try the Business Solutions page for hours of fun!
• Doesn’t work on Mac … at least in my experience.
• Interesting that it’s paired with “Recipes”. Pretty clear what the target demographic is.

Well, happy printing and saving!

Anyway, let’s just show the plugin:

Now the story:

Guillermo Rauch has a very nice mootools script that does a Facebook-like or AppleMail-like input control: thebasic one here and here with autocompletion.  The first thing I noticed is that Guillermo is only 17 years old! If you look at his original code, it’s clean and well written even if he was an industry veteran - amazing!

This plugin is what we’re looking for in our email composer.  Also, I was looking to actually cutting my teeth a little bit in javascript and jQuery (I’m currently reading chapter 3 of the jQ in Action book).  This points at porting this thing so here it is:

Update (10/23): Connect input behavior to submit values; updated example
jq-autobox-plugin-052.zip
Update (10/21): Rename to autobox
jq-autobox-plugin-051.zip
jq.textboxlist.plugin-050.zip

Notes on the port:

• Unlike this prototype port, it’s not a line-by-line port.  I’ve simplified it in some ways and added a few features.
• The biggest simplification is that the mini-input boxes are gone.  I originally ported them, but didn’t really see a use for them.  Since I mostly believe in cutting rather than hiding, that’s what I did.  It also made some of the focus/blur/movement easier.
• The mootools and prototype version are object-oriented style.  My port is more functional program style.  That is, I think it’s more functional programming style since I do not have much experience with functional programming.  I will say though, that what I think is functional programming, is very natural and clear.  Reminds me a bit of my college Scheme programming. That said, the code is not very extensible.
• Javascript programming is a ton of fun.
• I integrated the autocomplete directly into the plugin.  The original extended the textbox list class.  To me, the autocomplete is part of the control and also, to the last point, it wasn’t exactly clear to me the most natural or accepted way to extend the plugin.
• The focus/blur/movements were simplified.
• You can enter a value and press return, which will add that value as an item.
• Actually formatted it and put a few comments.
• There is some focus/blur funkiness that needs to be worked out.
• Tested on IE7 and FF3.
• Validation to be added.

We would love to get feedback on the control!  The release is 0.5.0 (alpha); I’m sure there are problems with it and bug reports would be appreciated as well.  I will release at least a few more versions as they get cooked and I get more familiar with jQuery and Javascript.

Quick instructions to create the demo above:

1. In your HTML, include jQuery, the plugin (jquery.textboxlist.js), and the CSS (jquery.textboxlist.css).
2. Put close.gif in the same directory or else change the css to point to where you put it.
3. The CSS assumes a form with ordered list and list element container.  I.e. the CSS assumes the form as in the example.
4. Below the main input element, in the same list element, add a div element with the ID from above appended by ‘-auto’, this is the autofeed.  See the example.
5. In a script tag, get the ID and call ‘.textboxlist()’ on it to make it a textboxlist.
6. Optionally pre-populate any autofeed elements.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-type" content="text/html; charset=utf-8" />
<title>jQuery TextboxList Demo</title>
<link rel="stylesheet" href="jquery.textboxlist.css" type="text/css" media="screen" title="Test Stylesheet" charset="utf-8" />
<script src="../jqueryjs/jquery/dist/jquery.js" type="text/javascript" charset="utf-8"></script>
<script src="jquery.textboxlist.js" type="text/javascript" charset="utf-8"></script>
<style>img{ height: 100px; float: left; }</style>
</head>
<body>
  <form action="test_submit" method="get" accept-charset="utf-8">
  <ol><li>
      <label>Test input</label>
      <input type="text" value="" id="test-1"/>
      <div id="test-1-auto">
        <div class="default">Type an email or list name</div>
        <ul class="feed">
          <li>fred@foo.bar</li>
          <li>barney@foo.bar</li>
        </ul>
      </div>
    </li></ol>
  </form>
  <script>
    $(function() {
      var tbl = $('#test-1').textboxlist().get(0);
      //tbl.add('added@here.com');
      //tbl.autoFeed('autofeed1@there.com');
      //tbl.autoFeed('autofeed2@there.com');
      //tbl.autoFeed('autofeed3@there.com');
      $.getJSON('json.html', function(json) {
        $.each(json, function(idx,str) { tbl.autoFeed(str); });
      });
    });
  </script>
  <div id="console">
  </div>
</body>
</html>

Initial thoughts? LOVE the multitouch pad. Two fingers to scroll, brilliant. I’m a complete keyboard shortcut fiend, so that part is very important for me … if the robustness of OS shortcuts aren’t there, it’ll be hard for me to drink the entire glass (of kool-aid).

Other than that, I mean - it runs applications, right? You can save and manage files too. Also, when you press a key, the corresponding letter appears in the editor. I guess I don’t ask a lot from my OS.

• jQuery Validation Basic stuff, our baseline (since we use jQuery validation)
• Yahoo Signup Page I’ve always loved how this page does validation (hit submit without filling in any fields)
• 47+ Excellent Ajax Forms Self proclamation
  
• Smashing Magazine Web Form Design Patterns Part 1 and Part 2
• Wufoo Online Form Builder
  
• Best Practices for Form Design by Luke Wroblewski, Wow!

One exception: LinkedIn does a fantastic job of bringing the Java web application discourse forward with presentations (Tech and Practices and Comm Arch for example) and open discussion.  We need more!

By the way, anybody have a list of papers, presentations, and blogs from Java web efforts?