Katz Got Your Tongue?

So the Vibrant Ink theme for Textmate has become a bit harder to track down lately due to some changes in EncyteMedia’s site structure.

Just to be helpful, you can download it from my blog

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 http://jqueryjs.googlecode.com/svn/trunk/tools/rails_demo_app for the entire demo, or http://jqueryjs.googlecode.com/svn/trunk/tools/rails_demo_app/vendor/plugins/jquery_on_rails 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 %>
<thead>
<tr>
<th>Col 1</th>
<th>Col 2</th>
</tr>
</thead>
<tbody>
<tr>
<td>jQuery 1.0</td>
<td>$100</td>
</tr>
<tr>
<td>jQuery 1.1</td>
<td>$59</td>
</tr>
<tr>
<td>jQuery 1.1.1</td>
<td>$68</td>
</tr>
<tr>
<td>jQuery 1.1.2</td>
<td>$8</td>
</tr>
</tbody>
<% 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.

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!

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 :).

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.