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 ‘Ruby on Rails’ Category

First Rails Presentation

So I was digging through the Wayback Machine and I found the first ever Rails presentation (from March 2004), given before Rails was even released.

Take a look. There’s some great stuff in there, from the original name of the basic controller class (AbstractApplicationController), the names of the methods in controllers (do_index, do_authenticate), to passing ivars to the view (@assigns["customer"] = Customer.find(@params["id"])).

Check it out… it’s pretty cool :)

Webrick Anywhere

I’ve lately found myself frequently in a situation where I had a directory structure that I wanted to be able to easily browse like a server. One common reason for me was a desire to browse work I was doing on my Mac on Parallels.

Rails uses Webrick to quickly mount its directory structure, and since my needs were very lightweight, I decided to investigate how I could set up webrick to mount a directory structure on a particular port. The result: a small script called server.rb which you can drop into any folder and call via ruby server.rb [PORT]. It’ll default to port 2000.

The code is almost entirely the example code from the Webrick library, but there are a few modification. Bon Apetit!

jQuery on Rails: A (Still Very Alpha) Update

I’ve made a number of updates to my preliminary release of jQuery on Rails:

  • It’s now in svn as part of a demo app, so you can see how it all fits together.
  • The new svn URL is for the entire demo, or for just the plugin
  • I added a number of new JavaScript files to get copied when you install the plugin.
  • Your jQuery modules now need to be in app/public/javascripts/jquery_modules, which allows the core library files to be separate from your modules

And the big news…

I’ve written a few proof of concept helpers for jQuery on Rails that come with modules that are automatically installed in jquery_modules.

So far, I wrote one for a tabbed interface and one for sortable tables.

They both take the same settings as the underlying JavaScript libraries. For instance, you can set up the table sorter as follows:

<% sortable_table :sort_class_asc => “ascending”, :sort_class_desc => “descending”, :striping_row_class => ["even", "odd"], :stripe_rows_on_start_up => true do %>
<th>Col 1</th>
<th>Col 2</th>
<td>jQuery 1.0</td>
<td>jQuery 1.1</td>
<td>jQuery 1.1.1</td>
<td>jQuery 1.1.2</td>
<% end %>

This corresponds to:

tableSorter({sortClassAsc: ‘ascending’, sortClassDesc: ‘descending’, stripingRowClass: ['even', 'odd'], stipeRowOnStartup: true})

You can check out both the tablesorter helper and the tabs helper in action by checking out the jQuery on Rails demo app.

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!

RailsConf Talk Recap

There was a great turnout at the jQuery talk at RailsConf yesterday (packed house!), mostly not jQuery users, but hungry for an alternative to Prototype.

At the session, I explained what I thought were some seminal differences about the way jQuery works as opposed to using built-in helpers:

  • jQuery prefers passing *data* — not code. In other words, a jQuery-friendly action will pass back JSON data, to be processed by a jQuery callback, while RJS (Rails’ preferred method), sends back code to be executed by the client. Sending back data makes for a skinnier pipe needed to accomplish the same thing
  • Unobtrusive thinking is incompatible with Rails helpers that are dumped in the middle of views. Even going the UJS4Rails route, requiring code to be inserted in the views that they refer to violates unobtrusive principles and mashes together behavior and content (even though the CLIENT sees the code separately, UJS is a design philosophy, not a compile-time philosophy).
  • Using server-side JavaScript (RJS) leads to a reliance on the server to maintain state (or at least, a reliance on the server to tell the client what to do), but many RJS’ers end up making extra trips to the server to compensate for their lack of client-side code
  • Rails works exactly the same as any other server-side framework from the perspective of the client. From that perspective, requests are made of the server (via Ajax) and responses are returned. Rails can make returning responses saner via respond_to and to_json but it’s fundamentally a communication that can be easily understood in a server-framework-agnostic way.
  • Last but not least, it’s worth your time to learn JavaScript even if you’ve been putting it off. Learning the basics of jQuery shouldn’t take more than an hour, but it’ll be an hour that’ll free you from having to worry about how someone else implemented a JavaScript helper and bring you closer to a saner design philosophy
  • Again, I’m really happy about the turnout at the session and I hope to be posting more about Rails as well as the release of jQuery on Rails real soon :).

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.

A better assert_select (assert_elements)

I’ve been using Rails since the days of assert_tag (an abomination that required far too much work to do very must testing for specific tags), which was powerful enough to take a look at the responses to gets and posts and make sure that they fit basic criteria.

Unfortunately, its syntax was far too verbose. Here’s an actual example from the Rails API:

assert_tag :tag => “div”,
:ancestor => { :tag => “ul” },
:parent => { :tag => “li”,
:attributes => { :class => “enum” } },
:descendant => { :tag => “span”, :child => /hello world/ }

As you can see, this is no fun, so I was really happy to see assert_select come into the picture, first as a plugin, and finally getting into the Rails core in Rails 1.2. Here’s what it does:

  • You can do assert_select “css_selector”
  • You can assert that there’s an exact number of matches, a minimum number, or a maximum number
  • You can narrow the set of matched elements by a specific text string (or match a RegExp)
  • You can pass assert_select a block, which contains more assert_selects and for which the root assert_select only returns true if the asserts inside pass for the collection of elements matched in the initial one.

It’s pretty cool, but it also has a two major drawbacks:

It makes a fundamentally wrong assertion about how it handles blocks. It tests all assert_selects in the block against the collection of elements matched by the initial selection. What that means is that if you want to test that at least one div on the page contains exactly two divs inside it, the basic block technique will fail:

assert_select “div” do
assert_select “div”, :count => 2

This will fail if you have two divs on the page each containing two div. That’s because the inner assert is being run against the set of all elements matched by the first assert_select “div,” which will find four elements (two divs for each matched div).

What you want instead is for assert_select to work if and only if the inner asserts pass for at least one of the matched divs.

The second drawback is that the plugin uses its own home-grown selector system, which is both slower than hpricot and, more importantly, more limited than hpricot. It uses CSS2 selectors, and has no support for things like ancestor selection (like the original assert_tag has).

Hpricot, on the other hand, supports full CSS3 as well as some basic XPath (pretty much the same stuff that jQuery supports; it seems to have started off as a Ruby port of jQuery’s selector engine).

Thankfully, Luke Redpath already did the initial work to make it possible to test Rails views with hpricot. He made it possible to do stuff like (his examples):

  • assert_equal “My Funky Website”, tag(‘title’)
  • assert_equal 20, tags(‘div.boxout’).size
  • assert_equal ‘visible’, element(‘div#site_container’).attributes['class']

That’s really cool, and I was strongly considering leaving it at that and using Luke’s plugin, but there were some really cool things you could do with assert_select that you cannot do as easily with Luke’s plugin.

So I built on Luke’s plugin to create a new assert, called assert_elements:

  • It has identical syntax to assert_select
  • You can use full CSS3 and limited XPath syntax (hello again to ancestor support)
  • If you pass an assert_elements a block, it tests the results on each matched elements, and if all of the asserts return true at least once, the entire assert_elements passes.
  • If you pass a block, and have :count => 0, it’ll pass if there is no element in the set of matched elements for which all of the child asserts pass.
  • It is fast.

Known Issues:

  • This is my first release to the world of assert_elements. There will probably be issues I have not yet resolved. Please email me at wycats AT gmail DOT com with any bug reports.
  • The error messages are obtuse, especially with blocks.
  • As with Luke’s original plugin, there are no tests. I have to figure how to test an assert plugin.
  • Hpricot 0.4 has a serious issue with certain selectors (including [@att*=val]). The issue is no longer present in hpricot’s most recent candidate build (hpricot 0.4.99) so install it via:

gem install hpricot –source

You can get assert_elements as a plugin at by doing:

script/plugin install

Very many thanks to Luke Redpath. This plugin build very much on the work he did (in fact, most of the source excepting the assert_elements method itself and some minor changes to support blocks is Luke’s!).

My Preferred Rails Development Environment

I’ve been chatting with a bunch of new Rails guys lately, and have been recommending my particular mix of Eclipse, RDT, RadRails, Subclipse, and Aptana as a basic IDE for new guys.

It occurred to me that there’s no one-stop shop for instructions on how to do that, so here goes.

  1. Download Eclipse
    1. You will need to download the version for your particular environment (Win32, OSX, Linux)
    2. Extract the zip file you downloaded into someplace you use for program files
    3. Run Eclipse
  2. You will now need to install some plugins
    1. In Eclipse, go to Help->Updates->Find and Install
    2. Select “Search for new features to install” and click Next
    3. Click “New Remote Site” and add each of the following plugins:
      1. Eclipse plugins use “update sites,” which provide all of the information for updates to the software after initial installation.
      2. RadRails:
      3. RDT:
      4. SubClipse:
      5. Aptana:
    4. Make sure all of the new items are selected, and click “Finish”
    5. Some updates will come up. Select them all and click “Next”
    6. Several Licensing questions may come up. Accept the terms of the licensing agreements and click “Next”
    7. A list of features to be installed will appear. Click “Finish”
    8. Eclipse will download all of the features and install them. It will then ask you to verify any features that have not been “signed.” Accept all features.
    9. When Eclipse is done installing, it will ask you to restart Eclipse. Do so.
    10. Congrats. You are done.
  3. You may need to do some additional configuration.
    1. Go to Window->Preferences
    2. Go to General->Editors->File Associations
      1. Make sure the default editor for “htm” and “html” is “Aptana HTML Editor”
      2. Make sure the default editor for “js” is “Aptana JS Editor”
      3. Make sure the default editor for “css” is “Aptana CSS Editor”
      4. Make sure the default editor for “rb” is “Ruby Editor”
      5. Make sure the default editor for “rhtml” is “RHTML Editor”
      6. Make sure the default editor for “yml” is “YML Editor”
    3. Go to Ruby->Installed Interpreters
      1. Make sure there is an entry there.
      2. If not, click “Add” and find your ruby binary (it might be in /local/bin or /opt/local/bin)
      3. NOTE: It does not matter what name you give this. You just need to point it to the binary.
    4. Go to Ruby->Ri/rdoc
      1. If either of the two is missing, add the binary (in Windows, it might be a .bat file)
    5. Go to Rails->Configuration
      1. Make sure Rails and Rake both have entries. Otherwise, add them (the ones in the main bin directory may not work. I needed to use /opt/local/lib/ruby/gems/1.8/gems/rails-1.1.6/bin/rails, for instance). If you go this route, make sure to change the path to your binaries if you upgrade.
      2. If you plan to use Mongrel with the built-in IDE, make sure there’s an entry in the Mongrel path.
    6. Go to General->Editors->Text Editors and set your desired tab width
    7. Go to Ruby->Formatter.
      1. Click “Show” next to Eclipse [built-in]
      2. Select your desired tab policy
      3. Click Ok and select a new name for your formatting settings.
      4. Click Ok.
    8. Click Rails->Editors->RHTML Editor
      1. Choose your desired tab settings
    9. Go to Aptana->Editors
      1. Choose your desired tab settings under “Formatting”
  4. Your basic settings should now work.

I know the above sounds like a lot of work, but it’s not. Besides, most of the settings are good from the beginning. If you choose to go this route (and I hope you will), make sure to install Dr. Nic’s RadRails Templates, which make all of the pretty TextMate shortcuts (warning: PDF) work in Eclipse.

Happy Hacking!

Update: Digg it!