RJS introduction

Publié par Nico Mar 24 juil 2007 12:05:00 GMT

RJS is a powerful type of template used in Rails to generate Javascript code from the server-side. This code will be sent to and executed by the browser.

This generated Javascript code is written in Ruby and allows you to update multiple elements in the page very easily without reloading it.

In this article I’m going to show you how RJS works using a concrete example.

Real-world application

Let’s say that you have a TODO-list with a form that can be used to add a new task. When you add a new task you want to append this task to your existing list, use a visual effect to show that a task has been added and reset the form.

RJS is perfect for this kind of task, you just have to create a file named after your action name that is adding your task to the database. For example, if my action is add_task, I’m going to create a file named add_task.rjs.

My add_task action is creating an instance variable @task, so my RJS file should be something like :

page.insert_html :bottom, 'tasks_div', :partial => 'task'
page.visual_effect :highlight, 'tasks_div'
page.form.reset 'add_task_form'

The page object is actually generated by Rails and is an instance of the Rails JavaScriptGenerator. This page object translates your Ruby code to Javascript.

First, we ask Rails to insert the resulting content into the bottom of the tasks_div <div>. So the first parameter is the position where the new content will be inserted.

The second parameter is the id of the element that will be modified.

The third parameter can either be a string literal or hash that corresponds to the options you can pass to render method. In this exemple we’re asking Rails to render the partial _task.rhtml.

After that we are applying a visual effect to the <div> that has been modified. To do this, we’re using visual_effect. The first parameter is the name of the effect to use, the second one is the id of the element on which we want to apply this effect.

The last line is used to reset the form with the id add_task_form so all the fields of this form are cleared.

Using these basics and reading the Rails API, you can start doing AJAX / RJS.

What can I do with RJS?

Anything! or almost anything you want to be dynamic

The Page object provides many methods to manipulate Javascript using simple and clear Ruby code.

• << : writes raw JavaScript to the page
• alert : displays an alert dialog
• assign : assigns a value to a JavaScript variable
• call : calls a JavaScript function
• delay : executes the content of the given block after a delay
• draggable : creates a script.aculo.us draggable element
• drop_receiving : creates a script.aculo.us drop receiving element
• hide : hides the given DOM elements
• insert_html : inserts HTML at the specified position for the given DOM element
• redirect_to : redirects the browser to the given location
• remove : removes the given DOM elements from the page
• replace : replaces the outer HTML of the given DOM element
• replace_html : replaces the inner HTML of the given DOM element
• select : returns a collection reference by finding it through a CSS pattern in the DOM
• show : shows the given DOM elements
• sortable : creates a script.aculo.us sortable element
• toggle : toggles the visibility of the given DOM elements
• visual_effect : starts a script.aculo.us visual effect
• [] : returns an element reference by finding it through id in the DOM

Debugging RJS

When you’ll come to using RJS (and Javascript) a lot, you’ll definitely have to debug it. There are some powerful tools that can help you out and save you a lot of time (and headaches).

First of all, Rails provides a few built in tools to get your bugs resolved quickly. In development mode you have access to a lot of information in the log file.

If an unhandled exception is raised, you’ll get an error page rather than the expected one. This error page gives you information about the file that has raised the exception, on which line, etc.

Alert boxes will popup too.The first one tells you what is the exception and the second one shows you the generated javascript code that raised the exception.

The last tool to debug your RJS / Javascript code is Firebug. Firebug is a plugin for firefox which include a DOM inspector, a Javascript console, an XMLHttpRequest logger and a command-line javascript interpreter.

Conclusion

As you can see it’s very easy to implement Ajax features with Rails and RJS templates. You can really do a lot of things using RJS, this article only scratch the surface of RJS capabilities. Be sure that if you try it, you’ll implement some AJAX functionnalities in all your future projects.

Have fun!