Prototype is a JavaScript library that provides DOM manipulation, Ajax functionality, and more traditional object-oriented facilities for JavaScript. This module provides a set of helpers to make it more convenient to call functions from Prototype using Rails, including functionality to call remote Rails methods (that is, making a background request to a Rails action) using Ajax. This means that you can call actions in your controllers without reloading the page, but still update certain parts of it using injections into the DOM. A common use case is having a form that adds a new element to a list without reloading the page or updating a shopping cart total when a new item is added.

Usage

To be able to use these helpers, you must first include the Prototype JavaScript framework in your pages.

javascript_include_tag 'prototype'

(See the documentation for ActionView::Helpers::JavaScriptHelper for more information on including this and other JavaScript files in your Rails templates.)

Now you’re ready to call a remote action either through a link…

link_to_remote "Add to cart",
  :url => { :action => "add", :id => product.id },
  :update => { :success => "cart", :failure => "error" }

…through a form…

<% form_remote_tag :url => '/shipping' do -%>
  <div><%= submit_tag 'Recalculate Shipping' %></div>
<% end -%>

…periodically…

periodically_call_remote(:url => 'update', :frequency => '5', :update => 'ticker')

…or through an observer (i.e., a form or field that is observed and calls a remote action when changed).

<%= observe_field(:searchbox,
     :url => { :action => :live_search }),
     :frequency => 0.5,
     :update => :hits,
     :with => 'query'
     %>

As you can see, there are numerous ways to use Prototype’s Ajax functions (and actually more than are listed here); check out the documentation for each method to find out more about its usage and options.

Common Options

See link_to_remote for documentation of options common to all Ajax helpers; any of the options specified by link_to_remote can be used by the other helpers.

Designing your Rails actions for Ajax

When building your action handlers (that is, the Rails actions that receive your background requests), it’s important to remember a few things. First, whatever your action would normall return to the browser, it will return to the Ajax call. As such, you typically don’t want to render with a layout. This call will cause the layout to be transmitted back to your page, and, if you have a full HTML/CSS, will likely mess a lot of things up. You can turn the layout off on particular actions by doing the following:

class SiteController < ActionController::Base
  layout "standard", :except => [:ajax_method, :more_ajax, :another_ajax]
end

Optionally, you could do this in the method you wish to lack a layout:

render :layout => false

You can tell the type of request from within your action using the request.xhr? (XmlHttpRequest, the method that Ajax uses to make background requests) method.

def name
  # Is this an XmlHttpRequest request?
  if (request.xhr?)
    render :text => @name.to_s
  else
    # No?  Then render an action.
    render :action => 'view_attribute', :attr => @name
  end
end

The else clause can be left off and the current action will render with full layout and template. An extension to this solution was posted to Ryan Heneise’s blog at ArtOfMission.

layout proc{ |c| c.request.xhr? ? false : "application" }

render :text => 'Return this from my method!'

Since whatever the method returns is injected into the DOM, this will simply inject some text (or HTML, if you tell it to). This is usually how small updates, such updating a cart total or a file count, are handled.

Updating multiple elements

See JavaScriptGenerator for information on updating multiple elements on the page in an Ajax response.