The auto-complete AJAX helpers create a system that monitors an input text box and provides the user with a drop-down list of results that match the user's input as they type. The user can then select from the list the item they are searching for. Note that for version 2.0 of Rails, auto-complete will not be included with the default Rails installation. However, it will still be available as a separate plug-in.

For Rory's application, we will create an auto-complete function for the company name search system. To do this he makes the following modifications:

auto_complete_for :company, :name

<%= text_field_with_auto_complete :company, :name %>

In the figure above, the letter p was typed and a list of the three company names appeared in a drop-down list below the text box. On entering an l, the list reduced by one (the company with a name that did not contain "pl"). Once selected with a mouse click, the chosen complete company name is automatically entered into the text box.

There is one more modification for Rory to make to companies_controller. At the moment the search method is waiting for a "term" to be returned in the HTML header. However,

text_field_with_auto_complete :company, :name

...will return the data in a field entitled company[name]. If Rory were to look at the new URL for the search view, he can see that ?company%5Bname%5D= plus the search string is appended to the companies/search URL on submission of the form. %5B and %5D are hexadecimal representation of the HTML characters [ and] respectively. To access the data in the HTML header field company[name], Rails uses the following construct— params[:company][:name]. Therefore, the search controller method needs to be updated to use this construct instead of params[:term]. At the same time Rory can rearrange the start of the method so that the params statement is only required once. This will make it easier to modify this element as required. Rory also uses an if statement to catch instances where no name data is passed to the search method.

Rory's modified search method is shown below. The code first gathers the name passed from the auto_complete form, checks that data has been passed and is not an empty string, and then passes the name to a paginated company find method. The method uses the index view to display the resulting subset of companies that match the search criteria and a search specific page title is created by including the searched for string in @page_title.

def search
name = params[:company][:name]
if name and name.length > 0
@paginator, @companies = paginate :company,
:per_page => 10,
:order => 'name',
:conditions => ["UCASE(name) like UCASE(?)", prep_for_like(name)]
@page_title = "List of companies with names that contain '#{name}'"
render :action => 'index'
else
redirect_to :action => 'index'
end
end

So in three lines of code and a small modification to the search method, auto-complete has been implemented. It is so simple to implement that I think it is worth commenting on just how complex the underlying tasks are that Rory has just enabled.

In fact just the following two lines enable all of that functionality. The controller code:

auto_complete_for :company, :name

...and the view code:

<%= text_field_with_auto_complete :company, :name %>

Consider this example. We have a table, listing the names of children and another table, listing the names of adults. We want to offer the users a search box for them to use to search through the surnames of adults, for surnames that match those in the table of children. The basic solution would be to raise the auto-complete on :adult and :surname. Then as the user started to enter text into the search box, they would be prompted with a list of existing adult surnames. However, the list would contain surnames that did not match names in the child surname list, but only appeared in the adult list.

An alternative approach would be to raise the auto-complete on :child and :surname, and then use the resulting params[:child][:surname] to build a query of the adults table. Both auto_complete_for :child, :surname and the handling of params[:child][:surname] would appear in the adult controller. That way, users will be prompted to select surnames that actually match the existing child surnames.

My first reaction on implementing auto-complete was "Wow!". Most people who I demonstrated it to were similarly impressed. In the next few days I went through the application I was working on and added auto-complete to various text boxes; after all, it was only a few lines of code and did not take long to add.

Over the following weeks I became more familiar with auto-complete and as I did, I found myself slowly removing the auto-complete occurrences. I now use it sparingly in a few key instances. There were certain issues I had with using the Rails Auto-complete helper. They are as follows:

It is now clear to me that much of the reason I had problems with auto-complete was that I was adding it because it was a cool feature. I was not adding it because its features addressed a specific problem or requirement of the application. If not used appropriately, auto-complete simply adds complications and its own set of issues to the application.