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 http://code.google.com/p/jqueryjs/source).

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.

Installation

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 http://jqueryjs.googlecode.com/svn/trunk/tools/jquery_on_rails

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!