Rails, jQuery, auto-complete, and a New Plugin

Update: I've switched which jQuery autocomplete plugin I use for this, see my newer blog entry.

The other day, I made a whole switch from Prototype & Scriptaculous to jQuery. I've had the bug to do this for a while, and this is a new project, so I went for it. I don't have anything against Prototype, so my main impetus for this was a move towards Unobtrusive JavaScript, and also the speed aspect (the site I'm currently working on, if things go accordingly to plan, will do some pretty serious traffic). But, the unobtrusive JavaScript was the key, and really, my switch is more of a philosophy of approach rather than say a dislike for Prototype, etc. And, of course, it's something new to play with :)

Before I go any further, I'll state right now, I am not a JavaScript expert, and I've been using jQuery now for all of a couple hours.

One of the results of my switch however, was that I hacked DHH's auto_complete Rails plugin, to work for jQuery. Simple change. I tweaked the controller macro, and then gutted the JS helpers, as you just don't need those when using jQuery in this way. It does require the jquery-autocomplete plugin for jQuery. I've published my Rails plugin for this on GitHub as auto_complete_jquery.

Circling back around, here's what I did to get all this going. I did run into one issue (see step 10 below) that I'm still tracking down (easy solution in the interim, but I'd like to understand what's happening, so if you have comments, please let me know):

1. Removed the Prototype and Scriptaculous JS files from the public/javascripts dir of my Rails app. You don't have to do this, but I am no longer using them, so saw no need to keep them there, and it helps ensure I don't mistakenly use something from them or include them in the view. This includes: prototype.js, controls.js, dragdrop.js, and effects.js.


2. Removed the prototype-based Rails auto_complete plugin from vendor/plugins.


3. Installed the latest minified jQuery file in public/javascripts/jquery.


4. Installed the JS files for the jquery-autocomplete plugin, and its dependencies: jquery.templating.js, and jquery.ui.autocomplete.js. (see the jquery-autocomplete plugin for these files).


5. Added the jquery.ui.autocomplete.css file to public/stylesheets.


6. Installed my auto_complete_jquery plugin.


7. Put the proper includes for the CSS file and the JS files in my application layout file:
   
   

   
     <%= stylesheet_link_tag 'jquery.ui.autocomplete' %>
     <%= javascript_include_tag 'jquery/jquery.min', 'jquery/jquery.templating', 'jquery/jquery.ui.autocomplete.ext', 'jquery/jquery.ui.autocomplete', :cache => 'jquery' %>
   

   
   Note that I keep my jQuery JS files in a subdir for organizational purposes, but you can modify as needed.


8. Changed my existing auto-complete text fields that used the Rails Prototype based auto_complete plugin's helpers to just be plain old text fields, such as:
   <%= coffee.text_field :drink, :autocomplete =>"off" %>
   This is doing an auto-complete for the "drink" attribute of the Coffee model.


9. I can simply leave any auto_complete_for calls that existed in my controller, as that works the same. If you had custom versions that were based on the code from the Prototype-based Rails plugin, just go look at the code in my plugin to see the differences, it's a simple change.

Add the JavaScript that sets up the auto-complete for the given text field. This will typically look like:


$(document).ready(function() {
  $("input#coffee_drink").autocomplete({ ajax: "auto_complete_for_coffee_drink" })
});


Where does this go? It depends. What I've been liking is using the JavaScript auto-include plugin, which creates a Rails-style convention for JavaScript files that pertain to individual actions, or are controller-wide. So in my case, this code would get placed in public/javascripts/views/coffees/new.js, or likely one directory up, as simply coffees.js (so that I can use it in any CoffeesController action that needs to auto-complete on coffee.drink. Without that plugin, you just put it in whatever JS file is appropriately included for the view you're using it in, etc. You can of course put it directly into the view in a script block, but then you aren't doing the whole Unobtrusive JavaScript thing as rigidly.

10. Finally, what I found is that I had to add a route for this. This is the issue I mentioned above. It sort of makes sense, but what I'm unclear on is, why the prior standard/Prototype-based Rails auto_complete plugin didn't require a route. They both seem to use a GET, define the action the same way, and so on. I'm hoping I'm just missing something obvious. So, the route I added is:
    map.connect ':controller/auto_complete_for_coffee_drink', :action => 'auto_complete_for_coffee_drink', :format => 'json'


A bunch of steps, but pretty simple work. The app I'm doing this on is all of a few days old, so I hadn't gotten into use of much else in Prototype and so on, thus making the wholesale switch easy.

If you'd like to learn more about any of these things, and as a comprehensive set of links:

• jQuery site


• jquery-autocomplete plugin on GitHub


• jquery-autocomplete plugin on jQuery plugins site


• Unobtrusive JavaScript


• DHH's auto_complete Rails plugin for use with Prototype


• JavaScript auto-include plugin


• My auto_complete_query Rails plugin

Enjoy!

Update: I removed the jQuery Dimensions JS file and include for it in my layout, as this is now included in the latest jQuery JS file itself.

Update 2: I don't know how the standard auto_complete plugin manages to do without routes, but here is a generic route for all auto-complete actions across controllers:

map.auto_complete ':controller/:action', 
                  :requirements => { :action => /auto_complete_for_\S+/ },
                  :conditions => { :method => :get }

I hesitate to put this into the plugin, as routes can be quite tricky in more complex apps, and I wouldn't want to auto-hose someone :)