Cody Fauser

Some background

During my daily reading of the Ruby on Rails mailing list I ran across a post asking about RJS templates. I hadn't heard of them before and I was intrigued to find out more.

It turns out that RJS templates are a new form of template, called JavascriptGeneratorTemplates, and end with a .rjs file extension.

Ok, so there is a new type of template, but what does it do? Here is the description from the rdoc documentation in the changeset:

Unlike conventional templates which are used to render the results of an action, these templates generate instructions on how to modify an already rendered page. This makes it easy to modify multiple elements on your page in one declarative Ajax response. Actions with these templates are called in the background with Ajax and make updates to the page where the request originated from.

Trying out the rjs templates requires checking out the latest Rails code from the subversion repository. You can use these instructions to help get your project running on edge Rails. After you are running edge Rails be sure to run the following:

rake update_javascripts

A short example

First, create the view that will be updated by the rjs template:

1
2
3
4
5
6
7
8
9

    <h1 id='header'>RJS Template Test</h1>
    <ul id='list'>
      <li>Dog</li>
      <li>Cat</li>
      <li>Mouse</li>
    </ul>
    <%= link_to_remote("Add a fox",
          :url =>{ :action => :add }) %>

Ensure that your layout is including the javascript libraries:

1
2

<%= javascript_include_tag :defaults %>

Then add the action that will be called by link_to_remote to your controller:

1
2
3

def add
end

Rails now looks for templates with an extension of .rjs, in addition to .rhtml and .rxml, so create a view named add.rjs for your controller and add the following code to it:

1
2
3
4
5
6

page.insert_html :bottom, 'list',
                 content_tag("li", "Fox")
page.visual_effect :highlight, 'list', :duration => 3
page.replace_html 'header',
                  'RJS Template Test Complete!'

If you're curious where the page object comes from, the rdocs provide the explanation:

An instance of the JavaScriptGenerator object named +page+ is automatically made available to your template, which is implicitly wrapped in an ActionView::Helpers::PrototypeHelper#update_page block.

Now when you load the page in your browser and click the 'Add a fox' link, a Fox list item will be added to the list and the entire list will be highlighted. The header will also be updated. You can also render partials:

1
2

page.replace_html 'header', :partial => 'my_partial'

Summary

As you can see from the example, the new RJS templates make it dead simple to update multiple page elements using AJAX. This example barely scratched the surface of what is possible. Kudos to the Rails developers for yet another wonderful addition to the framework.

Update

Checkout the new RJS Element and Collection Proxies.

Rails 1.1 has been released

No longer do you need Edge Rails or any plugin to get RJS working. Just upgrade to Rails 1.1 to get RJS baked right into the framework. Have fun!