6 Steps to Unobtrusive Rails (with jQuery)

Revised 11/20/2008 Simplified through use of save.js.erb and removal of jQuery Form plugin dependency.

Here's a set of 6 steps which breakdown the approach I have been using to unobtrusively add ajax functionality to a Rails application. The value of this approach (as opposed to traditional .rjs) is maintaining full separation of Javascript and display code, as well as building ajax on top of a version of your app that works without Javascript enabled in the user's browser.

Also here, we're going to be able to leverage our existing Rails templates, in both JS and non-JS scenarios. If a visitor has JS, the edit template will be displayed in a floating modal window without leaving the main page. So, we're not going to have to write separate display code for our ajax edit form, and importantly we're gonna get all of Rails built-in error handling magic as well. The ultimate goal is to have a simple tack-on system we can use to ajaxify our Rails app. First we have it working in standard mode, then we ajaxify it. While this may look like a lot of work, it really is not too bad considering that most of this is reusable for your app in general. Adding this same functionality to your Rails new, show, delete template-behaviors is done with minimal of additional effort.

Scenario
So let's assume that we're looking at a page with blog-like listing of multiple posts. Each post has an edit link and we have an edit template that handles editing of a post in standard Rails fashion. Our goal is to use this same template in an ajax manner, by loadiing the template into a modal dialog and processing its form submission all without moving away from our main page. Again, if there is no Javascript available in the user's client, our app will work in standard fashion.

So let's get started.

STEP 1: Load various JS libraries.

In this tutorial, we're using jQuery, Livequery and BlockUI. We will use: jQuery instead of Rails' default Prototype; Livequery for attaching events to dom elements that are loaded after the initial page (via ajax); and BlockUI for modal windows. You will need to include these libraries in your railsapp/public/javascripts folder, and remove all Prototype .js files.

STEP 2: Setup Rails for using jQuery.

In application.js ...

Add AUTH_TOKEN in JS variable in page header in application.html.erb...

STEP 3: AJAX configure Rails controller code using respond_to
Here are 2 methods, edit and save. The edit method is vanilla and will simply default load edit.html.erb. However, as you'll see below, our js code will jump in and load this in a modal dialog if js is enabled in the browser. So we won't be leaving the page we're on to open our edit dialog. Save is more special.

According to standard Rails fashion, we're using respond_to to handle either html or js gracefully in our controller.

In posts_controller.rb...

The wants.html{} is standard here -- handling things if js is not present.
However, if js is present, we get wants.js{}, where we handle either a successful save, or not. In our scenario, if we have success with our @post.save, we will render the updated @post object itself so we can insert that back into our dom, replacing the original post with our edited post (after we close the modal editor dialog). If we do not succeed with our save, we can access the errors themselves in json format, which I like because it's more visually elegant to simply load our errors rather than refresh the whole dialog. We will handle the errors display in a js function -- more on this below.

STEP 4: Edit Link in index.html.erb and edit.html.erb

The link tag below is used in each blog posting in our list of posts (posts/index.html.erb). We're using a partial as well that this code would be inside, _post.html.erb...

The css class 'edit' is key here, and will enable us to use jQuery to attach an event handler to it.

Here's our Rails edit template, edit.html.erb...

A standard Rails Form tag. Note id of 'post_edit_form' which we will use in our js to handlethe ajax form submission.

In application.html.erb, this is the modal window div. It's by default empty, and is filled with our templates and displayed when needed using BlockUI.

In styles.css ...

STEP 5: Setup AJAX event handlers in application.js

Now, in application.js, we use jQuery and the Livequery plugin to attach an event handler to every anchor tag with class of 'edit', inside of a div with class of 'post_div'. We need Livequery here, only because we will be allowing editing of posts without refreshing the page. Therefore edited posts have edit anchor tags that have been loaded after initial page load -- ie., reinserted into the dom. This is Livequery's special ability.

The $.get uses the href url attribute from our edit link above, makes the ajax call, and returns the response (the edit.html.erb template) to our modal (div#modal_window) dialog displayed using the BlockUI plugin. Whew, that's a mouthful.

STEP 6: Handling ajax form submission

In application.js ...

Here we use Livequery again to handle the submit event of the edit form which has been loaded after the initial page. We store a reference to the parent div of our form for later insertion of validation errors, if they exist. The jQuery $.post submits the form's serialized values and requests (via "script") Javascript as a result. The null parameter is because there is no callback function - none is needed here.

In save.js.erb...

The save JS template is loaded because our ajax form submission requests a Javascript response and we have respond_to wants.js{} in our controller method. This is a very cool scenario where we have both Javascript and Ruby available in our template and access to our Rails app context as well as our Javascript functions and variables (in application.js etc). Coding heaven.

If there are no errors, we set a variable (p) to the partial we will load back into the dom. Then we use p.gsub remove line-breaks in the partial before inserting it in the dom, and removing it's previous incarnation all in one nice jQuery chain. .unblockUI hides our modal dialog, and finally the notify function simply animates our flash notice. In our error scenario, we locate the div in our modal dialog with class 'error_messages' in order to insert the resulting messages (see function below) which have been converted to json. The .hide and .fadeIn create the nice fade-in error display.

And finally we have a Javascript function to format our Rails json error messages.

In application.js ...

So that's the tutorial ... for now at least. I am sure there are some different and perhaps better ways to do some of this. It represents the current state of my approach, which is always evolving (and may end up here in revisions).

Revised Nov 20th. -- simplified after influence of Ryan Bates' excellent screencast:
http://railscasts.com/episodes/136-jquery

My hope is that it is useful for people working in Rails who want to approach ajax unobtrusively via solid best-practice: writing a working, non-ajax app that is "progressively enhanced" with ajax code. We recognize that most visitors will have js, but for those who don't, we still present a functioning app to the web browser, and other non-js capable devices in addition.

Additional links of note:

The Pug Automatic
mad.ly