Yehuda Katz is a member of the Ember.js, Ruby on Rails and jQuery Core Teams; his 9-to-5 home is at the startup he founded, Tilde Inc.. There he works on Skylight, the smart profiler for Rails, and does Ember.js consulting. He is best known for his open source work, which also includes Thor and Handlebars. He travels the world doing open source evangelism and web standards work.

Archive for the ‘JavaScript’ Category

jQuery on Rails… Alpha (very very Alpha)

UPDATE: The information in this post is outdated. Please check out the follow-up post for more details.

I’ve posted the first release of jQuery on Rails on the jQuery svn (you can check it out at

This is a very early alpha, with fairly limited functionality, but I really wanted to get it out there so people can take a look at it (and hopefully provide feedback).

Basically, this release allows you to modularize your JS files into related functions (say, one file for sortable tables, one file for sortable lists, etc.). Rails will then parse your completed file to determine which JS files are needed, and compile them into a single file for download. This means that you can write JavaScript files based on functionality, and not have to worry about making sure you include the exact files necessary for each page on your site. You also get the benefit of a single file being sent to the client, while avoiding the problems of sticking everything in application.js.


You’re going to need to download two things from trunk/tools in the jQuery svn. (1) jQuery on Rails; (2) Hpricot.

Even if you’re already using hpricot, you’re going to need the special patched version that improves compatibility with jQuery. The plugin relies on strict compatibility, and there were a number of bugs (such as :even and :odd returning wildly different numbers of elements due to an incompatible implementation).

To compile hpricot, you will also need ragel. If you’re on OSX, a simple sudo port install ragel should do the trick (make sure you’re on the latest version of MacPorts; you can update via sudo port selfupdate).

After you’re done with Ragel, go into the hpricot directory and do a rake install. You’re going to get a new version of hpricot (0.5.142, which corresponds to the svn version that the patch is based on).

You can add jQuery on Rails to your project as a plugin by doing script/plugin install

Once it’s installed, you’ll need to add a route to your routes.rb file. It’s simply map.jquery (it’ll create the route that’s necessary to compile the JavaScript and run it).

You’ll also need to add <%= include_jquery %> in your layouts. It’ll automatically include the jQuery library, some common plugins, as well as the compiled file. If you want to change the files that are included by default, edit the JQueryOnRails::JQUERY_LIBRARY constant in init.rb of the plugin.

The plugin installation should automatically copy the necessary JavaScript files to your public/javascripts directory. If they’re not copied for some reason, just make sure you have jquery.js, interface.js, form.js, and dimensions.js.

How to use it

  • Create a page that needs to use some JavaScript, and create a new file in public/javascripts.
  • Use a selector to select some elements on your page, and do stuff with them (that’s what jQuery’s for!).
  • Restart your web server, and navigate to the page. You should see an included JS file called app_jquery that contains your code.
  • Profit!

What’s Next

This is a fairly skeletal plugin. I’m going to be adding some extra caching options, so you don’t need two hits to the server for each page load.

I’m also going to be adding some helpers, as well as a small jQuery plugin to simplify markup generation for common cases (so you’d be able to do <%= sortable_table ... do %> and stuff like that).

Porting the existing Prototype helpers is not at the top of my list, but I might do some of the more common ones to ease in the transition.

As always, feel free to contact me at outlookeic on AIM or wycats AT gmail DOT com with any questions!

jQuery on Rails: A Fresh Approach

My apologies for dropping off the face of the earth. I’ve been working hard at Procore, which I mentioned last time, and getting neck-deep in the specific problems that make working with jQuery and Rails at the same time so difficult.

Since I last publicly discussed jQuery on Rails, I’ve gone down a lot of avenues, and written a lot of code, and came to some conclusions:

  • jQuery and Unobtrusive JavaScript are fundamentally incompatible with an attempt to describe behavior inside markup, as Rails does via “JavaScript helpers.”
  • Attempts to fix the problem, specifically UJS for Rails, still require that you include your JS behaviors in your views, which are then marshalled into JavaScript files on the fly (and cached as appropriate). If you wanted to include the same JS behavior in multiple pages, you’d need to create custom helpers and call out to them.
  • jQuery is already the perfect mechanism for unobtrusive JavaScript, baked right into the library
  • The biggest problem faced by jQuery developers is not simplicity (which, again, you get for free in the library), but difficulty in including the correct jQuery “modules” in the Rails views that require them.

The most common problem with using jQuery with Rails in an app of moderate or higher complexity is the trade-off between including everything in a single application.js (which can lead to serious slowdowns in larger apps) and having multiple, modular files (which are a serious pain to include correctly as needed).

This is a problem for jQuery users who want to use Rails more than Rails users who are used to Prototype helpers and want to be able to use the jQuery library as a drop-in replacement. In the first release of jQuery on Rails, I will be targeting jQuery developers who want to work with Rails. In other words, jQuery on Rails is for you if you know jQuery or are willing to use jQuery.

This release of jQuery is not for you if you don’t want to learn jQuery, and want to program purely in Ruby. There will be a future release that will include some features for pure-Ruby developers, but I maintain that Unobtrusive JavaScript is fundamentally incompatible with that mode of thinking.

With all that said, what does jQuery on Rails actually do?

First up, it’s a Rails plugin, which you activate by adding <%= include_jquery %> in your application.rhtml. When your server is started, it’ll parse all of your JavaScript files, and identify selectors in those files. When include_jquery is called in your layout, it’ll get the rendered HTML and use Hpricot (which shares syntax with jQuery) to determine whether any instances of the selectors identified on server startup are present.

The JavaScript files that have selectors that are also present in your HTML will be loaded, and run as expected.

So in short:

  • Create your JavaScript files, using selectors as usual
  • Use include_jquery in your layout
  • You’re done

I’ll be demoing the code at RailsConf tonight and should be releasing the first beta version sometime in the next week. If you’re at RailsConf, check out the Birds of a Feather presentation at Room c122 at 9:30 pm tonight.

Using jQuery in Rails (Part I)

This is the first in a series of posts about using jQuery together with Ruby on Rails. In my professional life, I work on Procore, a project management tool for the construction industry. The application is massive by any standard. And before I came on, it made heavy use of the Prototype library, Rails’ native JavaScript mechanism.

When I came onboard, I introduced the team to jQuery, and they loved it. But it was far too much work to backtrack and remove all Prototype instances and replace them with jQuery. So our massive, complex app uses both, with no difficulties. Both libraries live side-by-side, causing no problems.

In this series, I will discuss setting up jQuery in Rails, and some techniques I’ve developed to make working with jQuery easier in Ruby on Rails applications.

First up, installation:

You’ll need to download a working copy of jQuery from You can either get the most recent release (recommended), or, if you’re particularly adventuresome, you can build your own copy of bleeding-edge jQuery.

Drop jquery.js into public/javascripts, and add <%= javascript_include_tag "jquery", "application" %> to your main layout file.

Your site will now be loading in jQuery, as well as application.js in every page (application.js is your application’s default JavaScript file and is created by default when you run the “rails” command). If you want to run Prototype alongside jQuery, use <%= javascript_include_tag :defaults, "jquery" %>. This will load in the default prototype files, application.js, and jQuery.

In application.js, add the following:


That will call jQuery.noConflict(), which relinquishes control of the $ alias to Prototype.

jQuery Commands

Virtually all jQuery commands won’t function correctly unless they’re run after the DOM has fully loaded. jQuery’s way of solving this is something called a “document ready block.”

jQuery(document).ready(function() {
  // commands go here 

This waits until the document is ready, the fires off the function passed to ready. Here’s a shortcut syntax:

jQuery(function() { 
  // commands go here 

This does exactly what jQuery(document).ready(…) does, but is shorter. The strategy for using jQuery in Rails is to treat JavaScript in much the way you treat CSS. You’re binding behavior, not style, to a particular set of elements identified by particular markup.

In CSS, you might give an “a” tag the class “external” to indicate that the link goes to a page external to your site. Through a site-wide CSS page, you can then indicate that you want the tag to use a special graphic (like in Wikipedia), to illustrate to users that the link is external.

Using jQuery, you can then indicate what behavior you want this link to have. For instance, you might the link to open in a new window. Inside the document ready block, you would use:

jQuery("a.external").click(function() {, "_blank") 

I will use jQuery, not $, throughout this tutorial series, because some of you will be using Prototype alongside jQuery in your Rails apps. If you’re not, feel free to convert any instance of “jQuery” to “$”

The above snippet will bind a click handler to all links with class “external,” and open them in a new window. And what’s great is that with JavaScript turned off, the link opens the page perfectly well, just in the same window.
Now, let’s say you like this a lot, and want a simple Rails way to create links with the appropriate markup throughout your app (without having to train all other developers on the new markup requirements).

You might create a simple helper in application_helpers.rb. Say, something like:

def external_link_to name, options = {}, html_options = nil, *parameters_for_method_reference
  (html_options ||= {}).merge!({:class => "external"})
  link_to name, options, html_options, *parameters_for_method_reference

As you can see, I’ve grabbed the call signature from link_to, made some modifications to html_options (added :class => external), and then fired off a call to the original link_to.

This is a very simple example, but this is the strategy we will use throughout this series: create some markup that is used to identify a particular behavior, instantiate the behavior via jQuery, and then, if desired, write a helper to make markup generation easier.

Next up: Create a sortable list using jQuery and Interface. We will look at how to create the markup, write a helper, and write a single, reusable controller method to use the returned results to update a model.