Layouts and Rendering in Rails

1. Overview: How the Pieces Fit Together

This guide focuses on the interaction between Controller and View in the Model-View-Controller triangle. As you know, the Controller is responsible for orchestrating the whole process of handling a request in Rails, though it normally hands off any heavy code to the Model. But then, when it's time to send a response back to the user, the Controller hands things off to the View. It's that handoff that is the subject of this guide.

In broad strokes, this involves deciding what should be sent as the response and calling an appropriate method to create that response. If the response is a full-blown view, Rails also does some extra work to wrap the view in a layout and possibly to pull in partial views. You'll see all of those paths later in this guide.

2. Creating Responses

From the controller's point of view, there are three ways to create an HTTP response:

• Call render to create a full response to send back to the browser
• Call redirect_to to send an HTTP redirect status code to the browser
• Call head to create a response consisting solely of HTTP headers to send back to the browser

2.1. Rendering by Default: Convention Over Configuration in Action

You've heard that Rails promotes "convention over configuration". Default rendering is an excellent example of this. By default, controllers in Rails automatically render views with names that correspond to valid routes. For example, if you have this code in your BooksController class:

class BooksController < ApplicationController
end

And the following in your routes file:

resources :books

And you have a view file app/views/books/index.html.erb:

<h1>Books are coming soon!</h1>

Rails will automatically render app/views/books/index.html.erb when you navigate to /books and you will see "Books are coming soon!" on your screen.

However, a coming soon screen is only minimally useful, so you will soon create your Book model and add the index action to BooksController:

class BooksController < ApplicationController
  def index
    @books = Book.all
  end
end

Note that we don't have explicit render at the end of the index action in accordance with "convention over configuration" principle. The rule is that if you do not explicitly render something at the end of a controller action, Rails will automatically look for the action_name.html.erb template in the controller's view path and render it. So in this case, Rails will render the app/views/books/index.html.erb file.

If we want to display the properties of all the books in our view, we can do so with an ERB template like this:

<h1>Listing Books</h1>

<table>
  <thead>
    <tr>
      <th>Title</th>
      <th>Content</th>
      <th colspan="3"></th>
    </tr>
  </thead>

  <tbody>
    <% @books.each do |book| %>
      <tr>
        <td><%= book.title %></td>
        <td><%= book.content %></td>
        <td><%= link_to "Show", book %></td>
        <td><%= link_to "Edit", edit_book_path(book) %></td>
        <td><%= link_to "Destroy", book, data: { turbo_method: :delete, turbo_confirm: "Are you sure?" } %></td>
      </tr>
    <% end %>
  </tbody>
</table>

<br>

<%= link_to "New book", new_book_path %>

2.2. Using render

In most cases, the controller's render method does the heavy lifting of rendering your application's content for use by a browser. There are a variety of ways to customize the behavior of render. You can render the default view for a Rails template, or a specific template, or a file, or inline code, or nothing at all. You can render text, JSON, or XML. You can specify the content type or HTTP status of the rendered response as well.

2.2.1. Rendering an Action's View

If you want to render the view that corresponds to a different template within the same controller, you can use render with the name of the view:

def update
  @book = Book.find(params[:id])
  if @book.update(book_params)
    redirect_to(@book)
  else
    render "edit"
  end
end

If the call to update fails, calling the update action in this controller will render the edit.html.erb template belonging to the same controller.

If you prefer, you can use a symbol instead of a string to specify the action to render:

def update
  @book = Book.find(params[:id])
  if @book.update(book_params)
    redirect_to(@book)
  else
    render :edit, status: :unprocessable_entity
  end
end

2.2.2. Rendering an Action's Template from Another Controller

What if you want to render a template from an entirely different controller from the one that contains the action code? You can also do that with render, which accepts the full path (relative to app/views) of the template to render. For example, if you're running code in an AdminProductsController that lives in app/controllers/admin, you can render the results of an action to a template in app/views/products this way:

render "products/show"

Rails knows that this view belongs to a different controller because of the embedded slash character in the string. If you want to be explicit, you can use the :template option (which was required on Rails 2.2 and earlier):

render template: "products/show"

2.2.3. Wrapping it up

The above two ways of rendering (rendering the template of another action in the same controller, and rendering the template of another action in a different controller) are actually variants of the same operation.

In fact, in the BooksController class, inside of the update action where we want to render the edit template if the book does not update successfully, all of the following render calls would all render the edit.html.erb template in the views/books directory:

render :edit
render action: :edit
render "edit"
render action: "edit"
render "books/edit"
render template: "books/edit"

Which one you use is really a matter of style and convention, but the rule of thumb is to use the simplest one that makes sense for the code you are writing.

2.2.4. Using render with :inline

The render method can do without a view completely, if you're willing to use the :inline option to supply ERB as part of the method call. This is perfectly valid:

render inline: "<% products.each do |p| %><p><%= p.name %></p><% end %>"

By default, inline rendering uses ERB. You can force it to use Builder instead with the :type option:

render inline: "xml.p {'Horrid coding practice!'}", type: :builder

2.2.5. Rendering Text

You can send plain text - with no markup at all - back to the browser by using the :plain option to render:

render plain: "OK"

2.2.6. Rendering HTML

You can send an HTML string back to the browser by using the :html option to render:

render html: helpers.tag.strong("Not Found")

2.2.7. Rendering JSON

JSON is a JavaScript data format used by many Ajax libraries. Rails has built-in support for converting objects to JSON and rendering that JSON back to the browser:

render json: @product

2.2.8. Rendering XML

Rails also has built-in support for converting objects to XML and rendering that XML back to the caller:

render xml: @product

2.2.9. Rendering Vanilla JavaScript

Rails can render vanilla JavaScript:

render js: "alert('Hello Rails');"

This will send the supplied string to the browser with a MIME type of text/javascript.

2.2.10. Rendering Raw Body

You can send a raw content back to the browser, without setting any content type, by using the :body option to render:

render body: "raw"

2.2.11. Rendering Raw File

Rails can render a raw file from an absolute path. This is useful for conditionally rendering static files like error pages.

render file: "#{Rails.root}/public/404.html", layout: false

This renders the raw file (it doesn't support ERB or other handlers). By default it is rendered within the current layout.

2.2.12. Rendering Objects

Rails can render objects responding to #render_in. The format can be controlled by defining #format on the object.

class Greeting
  def render_in(view_context)
    view_context.render html: "Hello, World"
  end

  def format
    :html
  end
end

render Greeting.new
# => "Hello World"

This calls render_in on the provided object with the current view context. You can also provide the object by using the :renderable option to render:

render renderable: Greeting.new
# => "Hello World"

2.2.13. Options for render

Calls to the render method generally accept six options:

• :content_type
• :layout
• :location
• :status
• :formats
• :variants

2.2.13.1. The :content_type Option

By default, Rails will serve the results of a rendering operation with the MIME content-type of text/html (or application/json if you use the :json option, or application/xml for the :xml option.). There are times when you might like to change this, and you can do so by setting the :content_type option:

render template: "feed", content_type: "application/rss"

2.2.13.2. The :layout Option

With most of the options to render, the rendered content is displayed as part of the current layout. You'll learn more about layouts and how to use them later in this guide.

You can use the :layout option to tell Rails to use a specific file as the layout for the current action:

render layout: "special_layout"

You can also tell Rails to render with no layout at all:

render layout: false

2.2.13.3. The :location Option

You can use the :location option to set the HTTP Location header:

render xml: photo, location: photo_url(photo)

2.2.13.4. The :status Option

Rails will automatically generate a response with the correct HTTP status code (in most cases, this is 200 OK). You can use the :status option to change this:

render status: 500
render status: :forbidden

Rails understands both numeric status codes and the corresponding symbols shown below.

2.2.13.5. The :formats Option

Rails uses the format specified in the request (or :html by default). You can change this passing the :formats option with a symbol or an array:

render formats: :xml
render formats: [:json, :xml]

If a template with the specified format does not exist an ActionView::MissingTemplate error is raised.

2.2.13.6. The :variants Option

This tells Rails to look for template variations of the same format. You can specify a list of variants by passing the :variants option with a symbol or an array.

An example of use would be this.

# called in HomeController#index
render variants: [:mobile, :desktop]

With this set of variants Rails will look for the following set of templates and use the first that exists.

• app/views/home/index.html+mobile.erb
• app/views/home/index.html+desktop.erb
• app/views/home/index.html.erb

If a template with the specified format does not exist an ActionView::MissingTemplate error is raised.

Instead of setting the variant on the render call you may also set it on the request object in your controller action.

def index
  request.variant = determine_variant
end

private
  def determine_variant
    variant = nil
    # some code to determine the variant(s) to use
    variant = :mobile if session[:use_mobile]

    variant
  end

2.2.14. Finding Layouts

To find the current layout, Rails first looks for a file in app/views/layouts with the same base name as the controller. For example, rendering actions from the PhotosController class will use app/views/layouts/photos.html.erb (or app/views/layouts/photos.builder). If there is no such controller-specific layout, Rails will use app/views/layouts/application.html.erb or app/views/layouts/application.builder. If there is no .erb layout, Rails will use a .builder layout if one exists. Rails also provides several ways to more precisely assign specific layouts to individual controllers and actions.

2.2.14.1. Specifying Layouts for Controllers

You can override the default layout conventions in your controllers by using the layout declaration. For example:

class ProductsController < ApplicationController
  layout "inventory"
  #...
end

With this declaration, all of the views rendered by the ProductsController will use app/views/layouts/inventory.html.erb as their layout.

To assign a specific layout for the entire application, use a layout declaration in your ApplicationController class:

class ApplicationController < ActionController::Base
  layout "main"
  #...
end

With this declaration, all of the views in the entire application will use app/views/layouts/main.html.erb for their layout.

2.2.14.2. Choosing Layouts at Runtime

You can use a symbol to defer the choice of layout until a request is processed:

class ProductsController < ApplicationController
  layout :products_layout

  def show
    @product = Product.find(params[:id])
  end

  private
    def products_layout
      @current_user.special? ? "special" : "products"
    end
end

Now, if the current user is a special user, they'll get a special layout when viewing a product.

You can even use an inline method, such as a Proc, to determine the layout. For example, if you pass a Proc object, the block you give the Proc will be given the controller instance, so the layout can be determined based on the current request:

class ProductsController < ApplicationController
  layout Proc.new { |controller| controller.request.xhr? ? "popup" : "application" }
end

2.2.14.3. Conditional Layouts

Layouts specified at the controller level support the :only and :except options. These options take either a method name, or an array of method names, corresponding to method names within the controller:

class ProductsController < ApplicationController
  layout "product", except: [:index, :rss]
end

With this declaration, the product layout would be used for everything but the rss and index methods.

2.2.14.4. Layout Inheritance

Layout declarations cascade downward in the hierarchy, and more specific layout declarations always override more general ones. For example:

• application_controller.rb

  class ApplicationController < ActionController::Base
    layout "main"
  end
  

  Copy

• articles_controller.rb

  class ArticlesController < ApplicationController
  end
  

  Copy

• special_articles_controller.rb

  class SpecialArticlesController < ArticlesController
    layout "special"
  end
  

  Copy

• old_articles_controller.rb

  class OldArticlesController < SpecialArticlesController
    layout false
  
    def show
      @article = Article.find(params[:id])
    end
  
    def index
      @old_articles = Article.older
      render layout: "old"
    end
    # ...
  end
  

  Copy

In this application:

• In general, views will be rendered in the main layout
• ArticlesController#index will use the main layout
• SpecialArticlesController#index will use the special layout
• OldArticlesController#show will use no layout at all
• OldArticlesController#index will use the old layout

2.2.14.5. Template Inheritance

Similar to the Layout Inheritance logic, if a template or partial is not found in the conventional path, the controller will look for a template or partial to render in its inheritance chain. For example:

# app/controllers/application_controller.rb
class ApplicationController < ActionController::Base
end

# app/controllers/admin_controller.rb
class AdminController < ApplicationController
end

# app/controllers/admin/products_controller.rb
class Admin::ProductsController < AdminController
  def index
  end
end

The lookup order for an admin/products#index action will be:

• app/views/admin/products/
• app/views/admin/
• app/views/application/

This makes app/views/application/ a great place for your shared partials, which can then be rendered in your ERB as such:

<%# app/views/admin/products/index.html.erb %>
<%= render @products || "empty_list" %>

<%# app/views/application/_empty_list.html.erb %>
There are no items in this list <em>yet</em>.

2.2.15. Avoiding Double Render Errors

Sooner or later, most Rails developers will see the error message "Can only render or redirect once per action". While this is annoying, it's relatively easy to fix. Usually it happens because of a fundamental misunderstanding of the way that render works.

For example, here's some code that will trigger this error:

def show
  @book = Book.find(params[:id])
  if @book.special?
    render action: "special_show"
  end
  render action: "regular_show"
end

If @book.special? evaluates to true, Rails will start the rendering process to dump the @book variable into the special_show view. But this will not stop the rest of the code in the show action from running, and when Rails hits the end of the action, it will start to render the regular_show view - and throw an error. The solution is simple: make sure that you have only one call to render or redirect in a single code path. One thing that can help is return. Here's a patched version of the method:

def show
  @book = Book.find(params[:id])
  if @book.special?
    render action: "special_show"
    return
  end
  render action: "regular_show"
end

Note that the implicit render done by ActionController detects if render has been called, so the following will work without errors:

def show
  @book = Book.find(params[:id])
  if @book.special?
    render action: "special_show"
  end
end

This will render a book with special? set with the special_show template, while other books will render with the default show template.

2.3. Using redirect_to

Another way to handle returning responses to an HTTP request is with redirect_to. As you've seen, render tells Rails which view (or other asset) to use in constructing a response. The redirect_to method does something completely different: it tells the browser to send a new request for a different URL. For example, you could redirect from wherever you are in your code to the index of photos in your application with this call:

redirect_to photos_url

You can use redirect_back to return the user to the page they just came from. This location is pulled from the HTTP_REFERER header which is not guaranteed to be set by the browser, so you must provide the fallback_location to use in this case.

redirect_back(fallback_location: root_path)

2.3.1. Getting a Different Redirect Status Code

Rails uses HTTP status code 302, a temporary redirect, when you call redirect_to. If you'd like to use a different status code, perhaps 301, a permanent redirect, you can use the :status option:

redirect_to photos_path, status: 301

Just like the :status option for render, :status for redirect_to accepts both numeric and symbolic header designations.

2.3.2. The Difference Between render and redirect_to

Sometimes inexperienced developers think of redirect_to as a sort of goto command, moving execution from one place to another in your Rails code. This is not correct.

The current action will complete, returning a response to the browser. After this your code stops running and waits for a new request, it just happens that you've told the browser what request it should make next by sending back an HTTP 302 status code.

Consider these actions to see the difference:

def index
  @books = Book.all
end

def show
  @book = Book.find_by(id: params[:id])
  if @book.nil?
    render action: "index"
  end
end

With the code in this form, there will likely be a problem if the @book variable is nil. Remember, a render :action doesn't run any code in the target action, so nothing will set up the @books variable that the index view will probably require. One way to fix this is to redirect instead of rendering:

def index
  @books = Book.all
end

def show
  @book = Book.find_by(id: params[:id])
  if @book.nil?
    redirect_to action: :index
  end
end

With this code, the browser will make a fresh request for the index page, the code in the index method will run, and all will be well.

The only downside to this code is that it requires a round trip to the browser: the browser requested the show action with /books/1 and the controller finds that there are no books, so the controller sends out a 302 redirect response to the browser telling it to go to /books/, the browser complies and sends a new request back to the controller asking now for the index action, the controller then gets all the books in the database and renders the index template, sending it back down to the browser which then shows it on your screen.

While in a small application, this added latency might not be a problem, it is something to think about if response time is a concern. We can demonstrate one way to handle this with a contrived example:

def index
  @books = Book.all
end

def show
  @book = Book.find_by(id: params[:id])
  if @book.nil?
    @books = Book.all
    flash.now[:alert] = "Your book was not found"
    render "index"
  end
end

This would detect that there are no books with the specified ID, populate the @books instance variable with all the books in the model, and then directly render the index.html.erb template, returning it to the browser with a flash alert message to tell the user what happened.

2.4. Using head to Build Header-Only Responses

The head method can be used to send responses with only headers to the browser. The head method accepts a number or symbol (see reference table) representing an HTTP status code. The options argument is interpreted as a hash of header names and values. For example, you can return only an error header:

head :bad_request

This would produce the following header:

HTTP/1.1 400 Bad Request
Connection: close
Date: Sun, 24 Jan 2010 12:15:53 GMT
Transfer-Encoding: chunked
Content-Type: text/html; charset=utf-8
X-Runtime: 0.013483
Set-Cookie: _blog_session=...snip...; path=/; HttpOnly
Cache-Control: no-cache

Or you can use other HTTP headers to convey other information:

head :created, location: photo_path(@photo)

Which would produce:

HTTP/1.1 201 Created
Connection: close
Date: Sun, 24 Jan 2010 12:16:44 GMT
Transfer-Encoding: chunked
Location: /photos/1
Content-Type: text/html; charset=utf-8
X-Runtime: 0.083496
Set-Cookie: _blog_session=...snip...; path=/; HttpOnly
Cache-Control: no-cache

3. Structuring Layouts

When Rails renders a view as a response, it does so by combining the view with the current layout, using the rules for finding the current layout that were covered earlier in this guide. Within a layout, you have access to three tools for combining different bits of output to form the overall response:

• Asset tags
• yield and content_for
• Partials

3.1. Asset Tag Helpers

Asset tag helpers provide methods for generating HTML that link views to feeds, JavaScript, stylesheets, images, videos, and audios. There are six asset tag helpers available in Rails:

• auto_discovery_link_tag
• javascript_include_tag
• stylesheet_link_tag
• image_tag
• video_tag
• audio_tag

You can use these tags in layouts or other views, although the auto_discovery_link_tag, javascript_include_tag, and stylesheet_link_tag, are most commonly used in the <head> section of a layout.

3.1.1. Linking to Feeds with the auto_discovery_link_tag

The auto_discovery_link_tag helper builds HTML that most browsers and feed readers can use to detect the presence of RSS, Atom, or JSON feeds. It takes the type of the link (:rss, :atom, or :json), a hash of options that are passed through to url_for, and a hash of options for the tag:

<%= auto_discovery_link_tag(:rss, {action: "feed"},
  {title: "RSS Feed"}) %>

There are three tag options available for the auto_discovery_link_tag:

• :rel specifies the rel value in the link. The default value is "alternate".
• :type specifies an explicit MIME type. Rails will generate an appropriate MIME type automatically.
• :title specifies the title of the link. The default value is the uppercase :type value, for example, "ATOM" or "RSS".

3.1.2. Linking to JavaScript Files with the javascript_include_tag

The javascript_include_tag helper returns an HTML script tag for each source provided.

If you are using Rails with the Asset Pipeline enabled, this helper will generate a link to /assets/javascripts/ rather than public/javascripts which was used in earlier versions of Rails. This link is then served by the asset pipeline.

A JavaScript file within a Rails application or Rails engine goes in one of three locations: app/assets, lib/assets or vendor/assets. These locations are explained in detail in the Asset Organization section in the Asset Pipeline Guide.

You can specify a full path relative to the document root, or a URL, if you prefer. For example, to link to a JavaScript file main.js that is inside one of app/assets/javascripts, lib/assets/javascripts or vendor/assets/javascripts, you would do this:

<%= javascript_include_tag "main" %>

Rails will then output a script tag such as this:

<script src='/assets/main.js'></script>

The request to this asset is then served by the Sprockets gem.

To include multiple files such as app/assets/javascripts/main.js and app/assets/javascripts/columns.js at the same time:

<%= javascript_include_tag "main", "columns" %>

To include app/assets/javascripts/main.js and app/assets/javascripts/photos/columns.js:

<%= javascript_include_tag "main", "/photos/columns" %>

To include http://example.com/main.js:

<%= javascript_include_tag "http://example.com/main.js" %>

3.1.3. Linking to CSS Files with the stylesheet_link_tag

The stylesheet_link_tag helper returns an HTML <link> tag for each source provided.

If you are using Rails with the "Asset Pipeline" enabled, this helper will generate a link to /assets/stylesheets/. This link is then processed by the Sprockets gem. A stylesheet file can be stored in one of three locations: app/assets, lib/assets, or vendor/assets.

You can specify a full path relative to the document root, or a URL. For example, to link to a stylesheet file that is inside a directory called stylesheets inside of one of app/assets, lib/assets, or vendor/assets, you would do this:

<%= stylesheet_link_tag "main" %>

To include app/assets/stylesheets/main.css and app/assets/stylesheets/columns.css:

<%= stylesheet_link_tag "main", "columns" %>

To include app/assets/stylesheets/main.css and app/assets/stylesheets/photos/columns.css:

<%= stylesheet_link_tag "main", "photos/columns" %>

To include http://example.com/main.css:

<%= stylesheet_link_tag "http://example.com/main.css" %>

By default, the stylesheet_link_tag creates links with rel="stylesheet". You can override this default by specifying an appropriate option (:rel):

<%= stylesheet_link_tag "main_print", media: "print" %>

3.1.4. Linking to Images with the image_tag

The image_tag helper builds an HTML <img /> tag to the specified file. By default, files are loaded from public/images.

<%= image_tag "header.png" %>

You can supply a path to the image if you like:

<%= image_tag "icons/delete.gif" %>

You can supply a hash of additional HTML options:

<%= image_tag "icons/delete.gif", {height: 45} %>

You can supply alternate text for the image which will be used if the user has images turned off in their browser. If you do not specify an alt text explicitly, it defaults to the file name of the file, capitalized and with no extension. For example, these two image tags would return the same code:

<%= image_tag "home.gif" %>
<%= image_tag "home.gif", alt: "Home" %>

You can also specify a special size tag, in the format "{width}x{height}":

<%= image_tag "home.gif", size: "50x20" %>

In addition to the above special tags, you can supply a final hash of standard HTML options, such as :class, :id, or :name:

<%= image_tag "home.gif", alt: "Go Home",
                          id: "HomeImage",
                          class: "nav_bar" %>

3.1.5. Linking to Videos with the video_tag

The video_tag helper builds an HTML5 <video> tag to the specified file. By default, files are loaded from public/videos.

<%= video_tag "movie.ogg" %>

Produces

<video src="/videos/movie.ogg" />

Like an image_tag you can supply a path, either absolute, or relative to the public/videos directory. Additionally you can specify the size: "#{width}x#{height}" option just like an image_tag. Video tags can also have any of the HTML options specified at the end (id, class et al).

The video tag also supports all of the <video> HTML options through the HTML options hash, including:

• poster: "image_name.png", provides an image to put in place of the video before it starts playing.
• autoplay: true, starts playing the video on page load.
• loop: true, loops the video once it gets to the end.
• controls: true, provides browser supplied controls for the user to interact with the video.
• autobuffer: true, the video will pre load the file for the user on page load.

You can also specify multiple videos to play by passing an array of videos to the video_tag:

<%= video_tag ["trailer.ogg", "movie.ogg"] %>

This will produce:

<video>
  <source src="/videos/trailer.ogg">
  <source src="/videos/movie.ogg">
</video>

3.1.6. Linking to Audio Files with the audio_tag

The audio_tag helper builds an HTML5 <audio> tag to the specified file. By default, files are loaded from public/audios.

<%= audio_tag "music.mp3" %>

You can supply a path to the audio file if you like:

<%= audio_tag "music/first_song.mp3" %>

You can also supply a hash of additional options, such as :id, :class, etc.

Like the video_tag, the audio_tag has special options:

• autoplay: true, starts playing the audio on page load
• controls: true, provides browser supplied controls for the user to interact with the audio.
• autobuffer: true, the audio will pre load the file for the user on page load.

3.2. Understanding yield

Within the context of a layout, yield identifies a section where content from the view should be inserted. The simplest way to use this is to have a single yield, into which the entire contents of the view currently being rendered is inserted:

<html>
  <head>
  </head>
  <body>
    <%= yield %>
  </body>
</html>