Fast Autocompleter¶ ↑

A wicked fast Scriptaculous Autocompleter and an extended multi value text field autocompleter.

Developed and used on zendesk.com for selecting users.

Description¶ ↑

Fast Autocompleter is a small JavaScript library that can help you get more responsive autocompleting text fields in your web application.

Autocompleting text fields normally send an AJAX request every time you change the value of the text field to get the suggested values from the server. Sending all these AJAX requests is slow, and if there is one thing you expect from an autocomplete feature it is that it must be fast. Sam Stephenson from 37signals showed us how to speed things up like he did on the search-for-a-person feature of Highrise. Fast Autocompleter is an implementation of what 37signals has shared.

Major props to 37signals for sharing!

Features¶ ↑

Autocompleter.Json. A modified version of the Scriptaculous Autocompleter, that takes it’s data from a function. This is more flexible than the Ajax.Autocompleter and Autocompleter.Local that comes with Scriptaculous.
Autocompleter.Cache. A caching layer for Autocompleter.Json, with local cache searching. This is where the speed comes from.
Optional “fuzzy” search like the Command-T file search feature of TextMate. This enables you to search for Mick Staugaard by typing “mist” or “ms”.
Autocompleter.MultiValue. An Apple Mail and Facebook inspired form element for entering more than one value into a text field.

Setting up Autocompleter.Json¶ ↑

Autocompleter.Json works a lot like the autocompleters that come with Scriptaculous, so you set up your markup and CSS in the same way:

<form>
  <p>
    <input type="text" id="autocomplete" name="name"/>
    <div id="autocomplete_choices" class="autocomplete"></div>
    <input type="submit" value="OK">
  </p>
</form>

Where Autocompleter.Json is different, is that you have to implement your own function for looking up suggestions and pass that as an argument to the Autocompleter.Json constructor:

<script type="text/javascript" charset="utf-8">
  function lookup(searchString, suggest) {
    new Ajax.Request('/users/autocomplete', { parameters: {name: searchString, rand: (new Date()).getTime()},
                                              onSuccess: function(response) {
                                                suggest(response.responseJSON);
                                              } });
  }

  new Autocompleter.Json("autocomplete", "autocomplete_choices", lookup, {});
</script>

The lookop function is expected to call the suggest function with an plain old Array of Strings.

The above example is a very simple AJAX implementation that expects the server to respond with JSON data in the right format. Autocompleter.Json will call the lookup function whenever it needs some suggestions for a value. Autocompleter.Json will pass two arguments to the lookup function, the first being the text that has been typed into the text area and the second being a function that should be called whenever the suggestions are ready. So you don’t have to return anything in the lookup function, but you must call the suggest function if you have any suggestions for the value being entered.

Options¶ ↑

The last constructor argument of Autocompleter.Json is an options hash you can use to customize its behavior. Ontop of the options defined in Autocompleter.Base (from Scriptaculous), Autocompleter.Json takes another option:

choices: the maximum number of suggestions to show on the screen. Defaults to 10.

So where is the benefit? Well the only benefit is that it is easy to implement you own custom lookup function, and that we easily can proxy the lookup function with Autocompleter.Cache.

Speeding it up with client side caching¶ ↑

You want to reduce the number of hits on your server, so sending an AJAX request every time a user hits a key is a really bad idea. Especially if the browser already has the information it needs. Autocompleter.Cache is a simple client side caching layer you can slap onto your own autocomplete lookup function:

<script type="text/javascript" charset="utf-8">
  function lookup(searchString, suggest) {
    new Ajax.Request('/users/autocomplete', { parameters: {name: searchString, rand: (new Date()).getTime()},
                                              onSuccess: function(response) {
                                                suggest(response.responseJSON);
                                              } });
  }

  var cachedBackend = new Autocompleter.Cache(lookup, {choices: 10});
  var cachedLookup = cachedBackend.lookup.bind(cachedBackend);

  new Autocompleter.Json("autocomplete", "autocomplete_choices", cachedLookup, {});
</script>

In the above example, cachedLookup is a function that behaves just like the lookup function except that it caches the responses.

Making a first call to cachedLookup with “m” as the searchString, will call the lookup function call the suggest callback function and cache the results. A second call the cachedLookup function with “m” as the searchString will NOT call the lookup function, but serve the results from the previous call to the suggest callback function. But there is more.… Making a call to cachedLookup with “mi” as the searchString will NOT call the lookup function, but will use the result for the “m” searchString as a basis for client side search. These results are also cached so searching for “mic” will use the “mi” results as a basis. This speeds up the lookup function quite significantly, and greatly reduces the number of round trips to your server.

For Autocompleter.Cache to work it is important that your lookup function finds ALL the suggestions for the search string. It is OK to give around a thousand suggestions. So find it all, not just the first 10.

Options¶ ↑

The last constructor argument of Autocompleter.Cache is an options hash you can use to customize its behavior:

choices: The maximum number of suggestions that should be passed to the suggest callback function. Defaults to 10.
fuzzySearch: Specifies if the local client side search should be “fuzzy”. Refer to the description above for a “definition”.

Autocompleter.MultiValue - the autocompleting multi value form element¶ ↑

The original inspiration for this form element comes from Apple Mail and the Facebook message composer. They both have these cool autocompleting fields for entering message recipients. Others have implemented this in JavaScript (including Facebook obviously), but this implementation works perfectly with the speedy Autocompleter.Cache.

The markup needed for this form element to work is just a simple text field:

<form>
  <p>
    <input type="text" id="autocomplete" name="users[]"/>
    <input type="submit" value="OK">
  </p>
</form>

For the output of Autocompleter.MultiValue to make any sense you need to supply e bunch of CSS. Have a look at the autocomplete.css for a good starting point.

Just like Autocompleter.Json you need to implement your own lookup function and pass it to the constructor:

<script type="text/javascript" charset="utf-8">
  function lookup(searchString, suggest) {
    new Ajax.Request('/users/autocomplete', { parameters: {name: searchString, rand: (new Date()).getTime()},
                                              onSuccess: function(response) {
                                                suggest(response.responseJSON);
                                              } });
  }

  new Autocompleter.MultiValue("autocomplete", lookup);
</script>

That’s the simplest working example of a multi value text field with AJAX auto completion. With Autocompleter.MultiValue the suggest function takes an array of name, id pairs as its single argument. So you must call suggest with an argument like [["Mick Staugaard", 1], ["Morten Primdahl", 2], ["Alexander Aghassipour", 3]] when you have suggestions to the value.

The form output of Autocompleter.MultiValue is a series of hidden input fields containing the ids of the selected values, so if you in the above example would choose Mick and Alexander (user id 1 and 3) the form output would be users[]=1&users=3

Speeding up the lookup function with Autocompleter.Cache is just as easy as with Autocompleter.Json:

<script type="text/javascript" charset="utf-8">
  function lookup(searchString, suggest) {
    new Ajax.Request('/users/autocomplete', { parameters: {name: searchString, rand: (new Date()).getTime()},
                                              onSuccess: function(response) {
                                                suggest(response.responseJSON);
                                              } });
  }

  var cachedBackend = new Autocompleter.Cache(lookup, {choices: 10});
  var cachedLookup = cachedBackend.lookup.bind(cachedBackend);

  new Autocompleter.MultiValue("autocomplete", cachedLookup);
</script>

For supporting all your edit views, the Autocompleter.MultiValue constructor takes a third argument i.e. an array of initial values. So again if I wanted Mick and Alexander to be the initial values, I would construct my form field like this:

new Autocompleter.MultiValue("autocomplete", cachedLookup, [["Mick Staugaard", 1], ["Alexander Aghassipour", 3]]);

Just like any other Scriptaculous Autocompleter, the Autocompleter.MultiValue takes a last argument with options and at the moment no extra options are supported than what Autocompleter.Base supports.

Check out multi_value_local_example.html for an example of how this form element can look.

Known issues¶ ↑

Let us know if you find any.

Requirements¶ ↑

Prototype (prototypejs.org)
Scriptaculous (script.aculo.us)

Original code ideas:¶ ↑

LICENSE:¶ ↑

(The MIT License)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

netconstructor / fast-autocompleter Goto Github PK