Layouts and Rendering in Rails

Ruby on Rails
Guides Index

+ +

+ + + +

Layouts and Rendering in Rails

This guide covers the basic layout features of Action Controller and Action View. By referring to this guide, you will be able to:

Use the various rendering methods built in to Rails @@ -256,18 +90,23 @@ Create layouts with multiple content sections Use partials to DRY up your views
+
+Use nested layouts (sub-templates) +
+

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.

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.

2. Creating Responses

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

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 @@ -284,9 +123,9 @@ Call head to create a response consisting solely of HTTP headers to sen

I'll cover each of these methods in turn. But first, a few words about the very easiest thing that the controller can do to create a response: nothing at all.

I’ll cover each of these methods in turn. But first, a few words about the very easiest thing that the controller can do to create a response: nothing at all.

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 actions. For example, if you have this code in your BooksController class:

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 actions. For example, if you have this code in your BooksController class:

def show
   @book = Book.find(params[:id])
-end
-

Rails will automatically render app/views/books/show.html.erb after running the method. In fact, if you have the default catch-all route in place (map.connect :controller/:action/:id), Rails will even render views that don't have any code at all in the controller. For example, if you have the default route in place and a request comes in for /books/sale_list, Rails will render app/views/books/sale_list.html.erb in response.

end

Rails will automatically render app/views/books/show.html.erb after running the method. In fact, if you have the default catch-all route in place (map.connect ':controller/:action/:id'), Rails will even render views that don’t have any code at all in the controller. For example, if you have the default route in place and a request comes in for /books/sale_list, Rails will render app/views/books/sale_list.html.erb in response.

- +

The actual rendering is done by subclasses of ActionView::TemplateHandlers. This guide does not dig into that process, but it's important to know that the file extension on your view controls the choice of template handler. In Rails 2, the standard extensions are .erb for ERB (HTML with embedded Ruby), .rjs for RJS (javascript with embedded ruby) and .builder for Builder (XML generator). You'll also find .rhtml used for ERB templates and .rxml for Builder templates, but those extensions are now formally deprecated and will be removed from a future version of Rails. The actual rendering is done by subclasses of ActionView::TemplateHandlers. This guide does not dig into that process, but it’s important to know that the file extension on your view controls the choice of template handler. In Rails 2, the standard extensions are .erb for ERB (HTML with embedded Ruby), .rjs for RJS (javascript with embedded ruby) and .builder for Builder (XML generator). You’ll also find .rhtml used for ERB templates and .rxml for Builder templates, but those extensions are now formally deprecated and will be removed from a future version of Rails.

2.2. Using `render`

In most cases, the ActionController::Base#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.

In most cases, the ActionController::Base#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.

@@ -316,25 +154,55 @@ http://www.gnu.org/software/src-highlite -->

2.2.1. Rendering Nothing

Perhaps the simplest thing you can do with render is to render nothing at all:

render :nothing => true
-

This will send an empty response to the browser (though it will include any status headers you set with the :status option, discussed below).

render :nothing => true

This will send an empty response to the browser (though it will include any status headers you set with the :status option, discussed below).

- +

You should probably be using the head method, discussed later in this guide, instead of render :nothing. This provides additional flexibility and makes it explicit that you're only generating HTTP headers. You should probably be using the head method, discussed later in this guide, instead of render :nothing. This provides additional flexibility and makes it explicit that you’re only generating HTTP headers.

2.2.2. Using `render` with `:action`

If you want to render the view that corresponds to a different action within the same template, you can use render with the :action option:

2.2.2. Rendering an Action’s View

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

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

If the call to update_attributes 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_attributes(params[:book])
+      redirect_to(@book)
+    else
+      render :edit
+    end
+  end
+end

To be explicit, you can use render with the :action option (though this is no longer necessary as of Rails 2.3):

render :action => "edit" end end -end -

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

+end

Ruby on Rails

Sustainable productivity for web-application development

Ruby on Rails

Sustainable productivity for web-application development

Chapters

Layouts and Rendering in Rails

Chapters

Layouts and Rendering in Rails

1. Overview: How the Pieces Fit Together

2. Creating Responses

2.1. Rendering by Default: Convention Over Configuration in Action

2.2. Using render

2.2.1. Rendering Nothing

2.2.2. Using render with :action

2.2.2. Rendering an Action’s View

2.2.3. Using render with :template

2.2.3. Rendering an Action’s Template from Another Controller

2.2.4. Rendering an Arbitrary File

2.2.4. Using render with :file

2.2.5. Using render with :inline

2.2.6. Using render with :update

2.2.7. Rendering Text

2.2.8. Rendering JSON

2.2.9. Rendering XML

2.2.10. Rendering Vanilla JavaScript

2.2.11. Options for render

The :content_type Option

The :layout Option

The :status Option

The :location Option

2.2.12. Finding Layouts

Specifying Layouts on a per-Controller Basis

Choosing Layouts at Runtime

Conditional Layouts

Layout Inheritance

2.2.13. Avoiding Double Render Errors

2.3. Using redirect_to

2.3.1. Getting a Different Redirect Status Code

2.3.2. The Difference Between render and redirect

2.4. Using head To Build Header-Only Responses

3. Structuring Layouts

3.1. Asset Tags

3.1.1. Linking to Feeds with auto_discovery_link_tag

3.1.2. Linking to Javascript Files with javascript_include_tag

3.1.3. Linking to CSS Files with stylesheet_link_tag

3.1.4. Linking to Images with image_tag

3.2. Understanding yield

3.3. Using content_for

3.4. Using Partials

3.4.1. Naming Partials

3.4.2. Using Partials to Simplify Views

3.4.3. Partial Layouts

3.4.4. Passing Local Variables

3.4.5. Rendering Collections

3.5. Using Nested Layouts

4. Changelog

2.2. Using `render`

2.2.2. Using `render` with `:action`

2.2.3. Using `render` with `:template`

2.2.4. Using `render` with `:file`

2.2.5. Using `render` with `:inline`

2.2.6. Using `render` with `:update`

2.2.11. Options for `render`

The `:content_type` Option

The `:layout` Option

The `:status` Option

The `:location` Option

2.3. Using `redirect_to`

2.3.2. The Difference Between `render` and `redirect`

2.4. Using `head` To Build Header-Only Responses

3.1.1. Linking to Feeds with `auto_discovery_link_tag`

3.1.2. Linking to Javascript Files with `javascript_include_tag`

3.1.3. Linking to CSS Files with `stylesheet_link_tag`

3.1.4. Linking to Images with `image_tag`

3.2. Understanding `yield`

3.3. Using `content_for`