Module: ActionView::Helpers::PrototypeHelper

Overview

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"}

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 normally 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:

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.

defname# Is this an XmlHttpRequest request?if(request.xhr?)render:text=>@name.to_selse# No? Then render an action.render:action=>'view_attribute',:attr=>@nameendend

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.

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

Dropping this in your ApplicationController turns the layout off for every
request that is an “xhr” request.

If you are just returning a little data or don't want to build a
template for your output, you may opt to simply render text output, like
this:

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.