The majority of the time you'll generate a response by rendering a view template. Here we'll discuss where to find a controller's view templates and how to pass variables from the controller to the view. We'll take a much closer look at view templates in ???. All of an application’s view templates are found underneath the app/views directory. The list of view paths is mutable, so to view the current list of view paths you can inspect the ActionController::Base.view_paths accessor. This would give you an up-to-date list of view paths in the event that your code or a plugin has modified the view paths for your application.

The controller's view templates directory is found in a subdirectory named after the controller under app/views. The name of the subdirectory is determined by underscoring the controller's class name after the Controller portion of the name has been removed. Therefore, the views for the OrdersController are located in app/views/orders. If you're ever in doubt you can call the controller's controller_path class method to get the name of the subdirectory:

OrdersController.controller_path # => "orders"

If a controller is namespaced then each namespace is added to the path as a subdirectory:

Admin::OrdersController.controller_path # => "admin/orders"

All instance variables of the instance of the controller that is handling the request are passed to the view template during rendering. These instance variables are called the controller's assigns and are available in the view template as instance variables of the same name.

The render call takes a variety of options depending which type of rendering is being performed. Several of the options are common to all types of rendering, so we'll go over them right here:

Rendering nothing is a way to return a response that has no response body. The response only contains headers. Rendering nothing is the simplest form of all of the different methods of rendering and looks as follows:

class PingController < ApplicationController
  def index
    render :nothing => true
  end
end

This works fine, but we've already looked at a more powerful and flexible method called head that also returns an empty response body. The advantage of head is that it allows you to set arbitrary HTTP headers on the response with the passed in options. With the :nothing option of render you're limited to setting the Content-Type, Location, and Status headers and using the headers method available in the controller to set other arbitrary headers.

Rendering an action instructs the controller to render a view template with the name provided from the controller's view directory.

The generator we ran earlier automatically generated an index.html.erb view template for us. The template, app/views/orders/index.html.erb, looks like this:

<h1>Orders#index</h1>
<p>Find me in app/views/orders/index.html.erb</p>

We can render this view template as follows:

class OrdersController < ApplicationController
  def index
    render :action => 'index'
  end
end

As we mentioned earlier, the template could also be rendered using the convenience form of the render method:

class OrdersController < ApplicationController
  def index
    render 'index'
  end
end

Following is a portion of an idiomatic OrdersController controller with show, new and create actions:

class OrdersController < ApplicationController
  # GET /blogs/1
  def show
    @order = Order.find(params[:id])
  end
  
  # GET /orders/new
  def new
    @order = Order.new
  end
  
  # POST /orders
  def create
    @order = Order.new(params[:order])

    if @order.save
      redirect_to(@order, :notice => 'Order was successfully created.')
    else
      render :action => "new"
    end
  end
end

Notice how the create method renders the new.html.erb view template when validation fails. Calling render only renders a template and never executes the method body of another controller action. This means that you must correctly set up all of the context the view template requires in each controller action the view template will be rendered from.

Rendering a template is exactly the same as rendering an action, but instead of looking for the view template in the controller’s view template directory, the view template is searched for using the application’s view template directory, app/views as the base. This is useful for sharing templates between different controllers, possibly with a app/views/shared view directory. Like rendering an action, you can use either the normal method of passing a hash of options to render or the more concise shortcut syntax. To render a template app/views/shared/index.html.erb with the regular hash syntax:

class OrdersController < ApplicationController
  def index
    render :template => 'shared/index'
  end
end

Or to render the very same template with the more concise shortcut syntax:

class OrdersController < ApplicationController
  def index
    render 'shared/index'
  end
end

Rendering a file is the same as rendering an action or template, however, you can render any file on the file system. You pass the :file option an absolution filename to render. Here we render the /etc/hosts file from my system:

class HostsController < ApplicationController
  def list
    render :file => '/etc/hosts', :layout => false, :content_type => Mime::TEXT
  end
end

Here we use curl to fetch the contents of the /etc/hosts file:

$ curl http://localhost:3000/hosts/list
##
# Host Database
#
# localhost is used to configure the loopback interface
# when the system is booting.  Do not change this entry.
##

127.0.0.1	localhost
255.255.255.255	broadcasthost
::1             localhost 
fe80::1%lo0	localhost

As is apparent from the example, you need to be extremely careful when rendering with the :file option. You must avoid using user input for the filename or be very careful in validating and sanitizing the input.

Rendering inline templates is very uncommon as it means you're rendering a view fragment inline in the controller. This violates the principles of MVC and should generally be avoided, since it is trivial to extract the content into its own view template. If you do have a need for it, though, you just use the :inline option and provide the contents of the view template as a string:

class CustomersController < ApplicationController
  def show
    @customer = Customer.find(params[:id])
    render :inline => <<-ERB
      <%= div_for(@customer) do %>
        <p><%= @customer.name %></p>
      <% end %>
    ERB
  end
end

Here we render a div containing the customers name using the Ruby heredoc syntax. As you can clearly see, this would be better extracted to an ERB template. ERB is the default template type for inline templates. You can use the :type option to change the template handler used to render the template.

By default, inline templates are not rendered within a layout, so you'll have to pass in the layout name you want to use in the :layout option if you want your content rendered in a layout.

If you’re displaying the same chunk of view code in multiple view templates, you need to refactor and use a partial instead. Partial templates, more commonly called partials, are reusable view snippets used to extract a portion of a view into a partial template when you need to use the same view fragment in two or more different templates. Partial templates are exactly the same as other templates except that they must be named with a leading _ character. If you had a partial ERB template for rendering a view snippet for an order you would name it _order.html.erb.

Rendering partials is typically done from within another view template. The only reason you would ever want to render a partial template in a controller is return an HTML fragment as the response to an AJAX call. The JavaScript library, jQuery by default in Rails 3, would make the request for the partial with an AJAX request and then update the page with the page fragment returned in the response. We’ll take a much closer look at partials in ???, but for now, we'll just stick to the basics of rendering partials.

Here we render the _user.html.erb from the controller's app/views/users view template directory:

class UsersController < ApplicationController
  def show
    @user = User.find(params[:id])
    render :partial => 'user'
  end
end

You can also let the rendering subsystem determine the name of the partial template for you by implicitly passing the object to the :partial option. Here’s what that looks like:

class UsersController < ApplicationController
  def index
    @user = User.find(params[:id])
    render @user
  end
end

Rendering text is probably the most straightforward of the rendering options. The content passed in with the :text option is returned to the client as the response. By default, rendering text does not wrap the content in the controller's layout, so you'll need to manually specify a layout if that is desired. Let's look at a simple example for a PingController, which simply renders the text PONG. Something like this is useful to respond to monitoring services, such as Pingdom. Here is the controller:

class PingController < ApplicationController
  def index
    render :text => 'PONG'
  end
end

It is worth noting that the content type of the response is not automatically set to text/plain when rendering text. The content type defaults to text/html, but could be overridden either by the Accept header of the request or the :content_type option of the render call.

Rendering an XML response couldn't be easier with Rails, especially with Active Model and Active Record’s object’s support for serializing themselves to XML. You can pass a string of XML markup to the :xml option or any object that defines a to_xml method. The XML renderer will automatically call the to_xml method for you if the object you pass in respond_to?(:to_xml).

Assuming a simple Customer model with name and birthdate attributes that can serialize itself to XML:

Customer.create(:name => "Mr. T", :birthdate => "1952-05-21")

Calling to_xml on the customer object returns the following XML string:

<customer>
  <name>Mr. T</name>
  <birthdate type="date">1952-05-21</birthdate>
  <id type="integer">1</id>
</customer>

You can explicitly call to_xml on the object to get the XML string:

class CustomersController < ApplicationController
  def show
    @customer = Customer.find(params[:id])
    render :xml => @customer.to_xml
  end
end

But it isn't required because the object implements a to_xml method:

class CustomersController < ApplicationController
  def show
    @customer = Customer.find(params[:id])
    render :xml => @customer
  end
end

When allowing the XML renderer to implicitly call to_xml for you, you can also pass any other options accepted by to_xml to the render call. For example, to change the root element from customer to person we would do the following:

class CustomersController < ApplicationController
  def show
    @customer = Customer.find(params[:id])
    render :xml => @customer, :root => 'person'
  end
end

Additionally, when rendering XML, the controller automatically sets the correct Content-Type header for the you, which we can see by viewing the headers with curl:

$ curl -I http://localhost:3000/customers/1.xml
HTTP/1.1 200 OK
Connection: close
Date: Sun, 23 May 2010 15:59:22 GMT
ETag: "d3d1de8feb536eb14aab247d613f44d6"
Content-Type: application/xml; charset=utf-8
X-Runtime: 0.038544
Content-Length: 0
Cache-Control: max-age=0, private, must-revalidate

Another handy way to generate XML is to create a hash of data and pass that to the :xml option. Hashes have a to_xml built-in thanks to Active Support, so the XML renderer does the right thing:

class CustomersController < ApplicationController
  def show
    render :xml => { :customer => "Jim" }
  end
end

For more information on XML serialization please see ???.

JSON, which stands for JavaScript Object Notation, is an object serialization format based on the JavaScript language that has recently gained a lot of momentum. The JSON format is a nice, human readable, lightweight data interchange format. Let's take a look at the same customer object in JSON format by calling to_json on it:

{"name":"Mr. T","birthdate":"1952-05-21","id":1}

Rendering JSON is more-or-less the same as rendering XML, as Rails provides excellent support for serializing objects to JSON. There is one difference in the way the JSON encoding works, though. Basically, any object can be encoded as JSON, so the JSON renderer return the passed in object as the response if the object responds to to_str. Otherwise the JSON encoder will encode the object and return the result. To return your object in JSON format simply pass it in to the render call as the :json option:

class CustomersController < ApplicationController
  def show
    @customer = Customer.find(params[:id])
    render :json => @customer
  end
end

As with the XML rendering, you can pass any of the options supported by the JSON encoder as options to the render call. For example, to only return the customer's name we could add the :only option:

class CustomersController < ApplicationController
  def show
    @customer = Customer.find(params[:id])
    render :json => @customer, :only => :name
  end
end

Again, from the HTTP headers, you can see that Action Controller does the right thing and sets the correct Content-Type headers for the response:

$ curl -I http://localhost:3000/customers/1.json
HTTP/1.1 200 OK
Connection: close
Date: Sun, 23 May 2010 20:33:20 GMT
ETag: "eb99282aedf4a9b4a22a6a99d7b21c64"
Content-Type: application/json; charset=utf-8
X-Runtime: 0.041876
Content-Length: 0
Cache-Control: max-age=0, private, must-revalidate

Just like with XML serialization, it can be convenient to pass the JSON renderer a hash of data, which it will automatically convert to a JSON string for you:

class CustomersController < ApplicationController
  def show
    render :json => { :customer => "Jim" }
  end
end

For more information on JSON serialization please see ???.

class CustomersController < ApplicationController
  def show
    @customer = Customer.find(params[:id])
    render :json => @customer, :callback => params[:callback]
  end
end

curl http://localhost:3000/customers/1.json?callback=showCustomer

showCustomer({"name":"Mr. T","birthdate":"1952-05-21","id":1})

<script type="text/javascript" src="http://example.com/customers/1?callback=showCustomer"></script>

Support for rendering JavaScript is similar to that for rendering XML and JSON. If the object passed in with the :js option responds to to_js then the result of the to_js call is used as the response body. If the object doesn't respond to to_js then the object is assumed to be a string containing JavaScript content. Where support for JavaScript differs than that for XML and JSON is that Rails does not automatically provide any predefined to_js methods. This means that you will have to define your own to_js method on the object if you want to take advantage of that functionality.

The most likely scenario is that you need to generate a bit of JavaScript on the server-side of your application to service an AJAX request from a link, such as a link at the bottom of the intro to an article to dynamically load the body of the article. The HTML representation of the show action is a view that shows an excerpt of the article with a link to load the rest of the content:

<%= truncate @article.body %>

<div id='read-more'>
<%= link_to "Read More", article_path(@article), :remote => true %>
</div>

We haven't covered linking yet, but the link_to call with the :remote => true option instructs the unobtrusive JavaScript library to issue an AJAX call to the show action of the ArticlesController when clicked. When the AJAX call arrives at the controller we make the call to render with the :js option:

class ArticlesController < ApplicationController  
  def show
    @article = Article.find(params[:id])
    render :js => "$('read-more').replace(#{@article.body.to_json})"
  end
end

The render call generates JavaScript code to replace the contents of the read-more div with the body of the article, which the Prototype library running in the browser will execute when it receives it. This will replace the div with the link with the body of the article. This is fully functional, but placing inline view code in the controller violates the MVC architecture. It would be recommended to create a view template for the JavaScript snippet and render that instead.

Using curl to request the JavaScript from the controller:

$ curl http://localhost:3000/articles/1
$('read-more').replace("Lorem ipsum dolor sit amet ...")

Inspecting the headers shows that Rails correctly set the Content-Type header of the response to text/javascript:

$ curl -I http://localhost:3000/articles/1
HTTP/1.1 200 OK
Connection: close
Date: Mon, 24 May 2010 03:40:23 GMT
ETag: "d58fcb69d89c7685861e4047f9658982"
Content-Type: text/javascript; charset=utf-8
X-Runtime: 0.048712
Content-Length: 0
Cache-Control: max-age=0, private, must-revalidate

Redirecting back to the page that issued the request can sometimes be handy when there’s a form that’s rendered in multiple places. Rails makes it easy: redirect_to :back Note however that if there is no referrer, ActionController::RedirectBackError will be raised.

The cookie session store keeps session data in a cookie in the client's browser. The cookie store is great because it requires no setup or configuration and is much faster than the other session stores. The session data is sent in a cookie with each request by the client and the server writes the session data in the cookie headers of each response, so it is a good idea to keep the session small to reduce the overhead of each request/response cycle.

Since the data is stored in a cookie, the maximum size of the encoded session data is limited to the maximum usable size of a cookie by all browsers, which is 4 KB. However, since the data is encoded and has a cryptographic signature attached to it, the most data you'll likely fit in the cookie store is around 2.5 KB. If you need to store more than around 2.5 KB of data you'd want to use one of the other session stores. If you do end up putting too much data in the session you'll end up triggering an exception when Rails processes the session data for the response.

Another thing to keep in mind is that the session data is readable by the client. The data is cryptographically signed by Rails using a Hash-based Message Authentication Code (HMAC) to prevent tampering, but the data is not encrypted. This means that you would never want to store sensitive private information in the session when using the cookie session store. If you must store private information in the session then you'd want to use one of the other session stores that maintains session data on the server.

The Active Record session store keeps all session data in the database. There are two reasons you might want to use this session store. The first is if you need to store more data in the session than will fit in the cookie session store. The second is if you need to store confidential information in the session.

The maximum size of the data stored in the Active Record session store depends on the maximum size of the database column you choose to store the session data in. By default, Rails uses a :text column for storing the session data. When using MySQL, this stores around 64 KB of data.

The Memcached session store is a server-side session store similar to the Active Record session store, but using Memcached for the back-end storage of the sessions. One major difference from the Active Record session store is that session data is not persistent in the Memcached session store. This is an inherent limitation of Memcached itself not being a persistent data store. The maximum size of session that can be stored in a Memcached server is 1 MB.

The reason you might want to use the Memcached session store is to leverage your existing Memcached infrastructure and to keep the load of sessions from impacting your database. You will still only want to use this session store if cookie session store is not adequate for your needs. Additionally, if anything happens to the Memcached process or the server that is running Memcached then the sessions that server contains will be lost. Unless your users won't notice losing their sessions then you'll probably not want to use the Memcached session store.

The cookie store is the default session store used by Rails. The default configuration of the cookie store generated by the Rails application generator in the config/initializers/session_store.rb file looks like the following:

ActionController::Base.session = {
  :key         => '_blog_session',
  :secret      => 'fdd1077479a7a13a8f3346c952047494b37a2fb6203b9a4a0ec03'
}

Rails names the session :key based on the name of your application. In the example the name of the application is blog. A cryptographically secure :secret is also generated. The :secret option is required when using the cookie store. Also, the :secret was shortened in order to fit it on a single line, but is normally 128 characters. To generate a new cryptographically secure secret key you can use the rake secret task provided by Rails. Changing the :secret will invalidate all of your existing sessions, so use with caution.

There are two additional session options specific to the cookie session store:

To configure your application to use the Active Record session store place the following line in config/initializers/session_store.rb:

ActionController::Base.session_store = :active_record_store

Before you can use the Active Record session store you'll need to generate and run a database migration. Run the following rake task to generate the migration:

$ rake db:sessions:create

The migration creates a sessions table with session_id, data, created_at, and updated_at columns. Run the migration to create the sessions table in your database:

$ rake db:migrate

There is also a rake task for clearing all sessions in the table:

$ rake db:sessions:clear

When using the Active Record session store each session will be stored in your database. If your application gets a lot of traffic there will end up being a substantial number of session stored in the database, which can negatively affect your application's performance. The simplest way to clear out old sessions would be to use rails runner from a cron task. The following command run from the root of your Rails project will delete all sessions in the production database that haven't been updated in the past 30 days:

$ rails runner -e production \
"ActiveRecord::SessionStore::Session.delete_all(
  [ 'updated_at < ?', 30.days.ago ]
)"

To configure your applications to use the Memcached session store place the following line in config/initializers/session_store.rb:

ActionController::Base.session_store = :mem_cache_store

You'll need to have Memcached servers accessible to your Rails application in order to use the Memcached store. See the section called “Memcached” for instructions on setting up Memcached on your machine.

There are several additional session options specific to the Memcached session store: