DO NOT READ THIS FILE ON GITHUB, GUIDES ARE PUBLISHED ON https://guides.rubyonrails.org.

Action View Overview

After reading this guide, you will know:

• What Action View is and how to use it with Rails.
• How best to use templates, partials, and layouts.
• How to use localized views.

What is Action View?

Action View is the V inMVC.Action Controller and Action View work together to handle web requests. Action Controller is concerned with communicating with the model layer (of MVC) and retrieving data. Action View is then responsible for rendering a response body to the web request using that data.

By default, Action View templates (also referred to simply as "views") are written using Embedded Ruby (ERB), which allows using Ruby code within HTML documents.

Action View provides manyhelper methods for dynamically generating HTML tags for forms, dates, and strings. It's also possible to add custom helpers to your application as needed.

NOTE: Action View can make use of Active Model features liketo_param</a> andto_partial_path</a> to simplify code. That doesn't mean Action View depends on Active Model. Action View is an independent package that can be used with any Ruby library.

Using Action View with Rails

Action View templates (aka "views") are stored in subdirectories in the app/views directory. There is a subdirectory matching the name of each controller. The view files inside that subdirectory are used to render specific views as a response to controller actions.

For example, when you use scaffolding to generate an article resource, Rails generates the following files in app/views/articles:

$ bin/rails generate scaffold article
      [...]
      invoke  scaffold_controller
      create    app/controllers/articles_controller.rb
      invoke    erb
      create      app/views/articles
      create      app/views/articles/index.html.erb
      create      app/views/articles/edit.html.erb
      create      app/views/articles/show.html.erb
      create      app/views/articles/new.html.erb
      create      app/views/articles/_form.html.erb
      [...]

The file names follow a Rails naming convention. They share their name with the associated controller action. For example the index.html.erb, edit.html.erb, etc.

By following this naming convention, Rails will automatically find and render the matching view at the end of a controller action, without you having to specify it. For example, the index action in the articles_controller.rb will automatically render the index.html.erb view inside the app/views/articles/ directory. The name and the location of the file are both important.

The final HTML returned to the client is composed of a combination of the .html.erb ERB file, a layout template that wraps it, and all the partials that the ERB file may reference. In the rest of this guide, you will find more details about each of the three components: Templates, Partials, Layouts.

Templates

Action View templates can be written in different formats. Rails uses the file extension to determine the view's format and templating system.

For example, a file with a .html.erb extension uses ERB to build an HTML response.Jbuilder templates that generate JSON will have the extension .json.jbuilder. And an XML template usingBuilder</a> would use .xml.builder.

<h1>Names</h1>
<% @people.each do |person| %>
  Name: <%= person.name %><br>
<% end %>

<%# WRONG %>
Hi, Mr. <% puts "Frodo" %>

gem "jbuilder"

json.name("Alex")
json.email("alex@example.com")

{
  "name": "Alex",
  "email": "alex@example.com"
}

See theJbuilder documentation for more examples.

Builder

Builder templates are a more programmatic alternative to ERB. It's similar to JBuilder but is used to generate XML, instead of JSON.

An XmlMarkup object named xml is automatically made available to templates with a .builder extension.

Here is a basic example:

xml.em("emphasized")
xml.em { xml.b("emph & bold") }
xml.a("A Link", "href" => "https://rubyonrails.org")
xml.target("name" => "compile", "option" => "fast")

which would produce:

<em>emphasized</em>
<em><b>emph &amp; bold</b></em>
<a href="https://rubyonrails.org">A link</a>
<target option="fast" name="compile" />

Any method with a block will be treated as an XML markup tag with nested markup in the block. For example, the following:

xml.div {
  xml.h1(@person.name)
  xml.p(@person.bio)
}

would produce something like:

<div>
  <h1>David Heinemeier Hansson</h1>
  <p>A product of Danish Design during the Winter of '79...</p>
</div>

SeeBuilder documentation for more examples.

Template Compilation

By default, Rails will compile each template to a method to render it. In the development environment, when you alter a template, Rails will check the file's modification time and recompile it.

There is also Fragment Caching for when different parts of the page need to be cached and expired separately. Learn more about it in the caching guide.

Partials

Partial templates - usually just called "partials" - are a way of breaking up the view templates into smaller reusable chunks. With partials, you can extract a piece of code from your main template to a separate smaller file, and render that file in the main template. You can also pass data to the partial files from the main template.

Let's see this in action with some examples:

Rendering Partials

To render a partial as part of a view, you use therender</a> method within the view:

<%= render "product" %>

NOTE: Refer to theLayouts and Rendering guide for further information on the lookup hierarchy of partials and template.

Partial file names start with leading underscore character by convention. The file name distinguishes partials from regular views. However, no underscore is used when referring to partials for rendering within a view. This is true even when you reference a partial from another directory:

<%= render "admin/control_panel" %>

That code will look for and render a partial named _control_panel.html.erb in app/views/admin/.

Using Partials to Simplify Views

One way to use partials is to treat them as the equivalent of methods. A way to move details out of a view so that you can grasp what's going on more easily. For example, you might have a view that looks like this:

<%= render "application/ad_banner" %>

<h1>Products</h1>

<p>Here are a few of our fine products:</p>
<% @products.each do |product| %>
  <%= render partial: "product", locals: { product: product } %>
<% end %>

<%= render "application/footer" %>

Here, the _ad_banner.html.erb and _footer.html.erb partials could contain content that is shared among many pages in your application. You don't need to see the details of these sections when you're focused on a Products' page.

The above example also uses the _product.html.erb partial. This partial contains details for rendering an individual product and is used to render each product in the collection @products.

Passing Data to Partials with locals Option

When rendering a partial, you can pass data to the partial from the rendering view. You use the locals: options hash for this. Each key in the locals: option is available as a partial-local variable:

<%# app/views/products/show.html.erb %>

<%= render partial: "product", locals: { my_product: @product } %>

<%# app/views/products/_product.html.erb %>

<%= tag.div id: dom_id(my_product) do %>
  <h1><%= my_product.name %></h1>
<% end %>

A "partial-local variable" is a variable that is local to a given partial and only available from within that partial. In the above example, my_product is a partial-local variable. It was assigned the value of @product when passed to the partial from the original view.

Note that typically we'd simply call this local variable product. We are using my_product to distinguish it from the instance variable name and template name in this example.

Since locals is a hash, you can pass in multiple variables as needed, like locals: { my_product: @product, my_reviews: @reviews }.

However, if a template refers to a variable that isn't passed into the view as part of the locals: option, the template will raise an ::ActionView::Template::Error:

<%# app/views/products/_product.html.erb %>

<%= tag.div id: dom_id(my_product) do %>
  <h1><%= my_product.name %></h1>

  <%# => raises ActionView::Template::Error for `product_reviews` %>
  <% product_reviews.each do |review| %>
    <%# ... %>
  <% end %>
<% end %>

Using local_assigns

Each partial has a method called local_assigns available. You can use this method to access keys passed via the locals: option. If a partial was not rendered with :some_key set, the value of local_assigns will be nil within the partial.

For example, product_reviews is nil in the below example since only product is set in locals::

<%# app/views/products/show.html.erb %>

<%= render partial: "product", locals: { product: @product } %>

<%# app/views/products/_product.html.erb %>

<% local_assigns[:product]          # => "#<Product:0x0000000109ec5d10>" %>
<% local_assigns[:product_reviews]  # => nil %>

One use case for local_assigns is optionally passing in a local variable and then conditionally performing an action in the partial based on whether the local variable is set. For example:

<% if local_assigns[:redirect] %>
  <%= form.hidden_field :redirect, value: true %>
<% end %>

Another example from Active Storage's _blob.html.erb. This one sets the size based on whether in_gallery local variable is set when rendering the partial that contains this line:

<%= image_tag blob.representation(resize_to_limit: local_assigns[:in_gallery] ? [ 800, 600 ] : [ 1024, 768 ]) %>

render without partial and locals Options

In the above examples, render takes 2 options: partial and locals. But if these are the only options you need to use, you can skip the keys, partial and locals, and specify the values only.

For example, instead of:

<%= render partial: "product", locals: { product: @product } %>

You can write:

<%= render "product", product: @product %>

You can also use this shorthand based on conventions:

<%= render @product %>

This will look for a partial named _product.html.erb in app/views/products/, as well as pass a local named product set to the value @product.

NOTE: Under the hood, Rails calls to_partial_path on the model to determine which partial to render. You can override this method to customize the partial if required.

The as and object Options

By default, objects passed to the template are in a local variable with the same name as the template. So, given:

<%= render @product %>

within the _product.html.erb partial you'll get @product instance variable in the local variable product, as if you had written:

<%= render partial: "product", locals: { product: @product } %>

The object option can be used to specify a different name. This is useful when the template's object is elsewhere (e.g. in a different instance variable or in a local variable).

For example, instead of:

<%= render partial: "product", locals: { product: @item } %>

you can write:

<%= render partial: "product", object: @item %>

This assigns the instance variable @item to a partial local variable named product. What if you wanted to change the local variable name from the default product to something else? You can use the :as option for that.

With the as option, you can specify a different name for the local variable like this:

<%= render partial: "product", object: @item, as: "item" %>

This is equivalent to

<%= render partial: "product", locals: { item: @item } %>

Rendering Collections

It's common for a view to iterate over a collection, such as @products, and render a partial template for each object in the collection. This pattern has been implemented as a single method that accepts an array and renders a partial for each one of the elements in the array.

For example, to render all products:

<% @products.each do |product| %>
  <%= render partial: "product", locals: { product: product } %>
<% end %>

can be rewritten in a single line:

<%= render partial: "product", collection: @products %>

When a partial is called with a collection, the individual instances of the partial have access to the member of the collection being rendered via a variable named after the partial. In this case, since the partial is _product.html.erb, you can use product to refer to the collection member that is being rendered.

When the collection you wish to render contains objects that respond to to_partial_path, such as Active Record and Active Model instances, you can use the following shorthand:

<%= render @products %>

Rails determines the partial for each object by calling to_partial_path on it. Conventionally, for Active Record objects, this is the name of the model: products/_product.html.erb for Product.

A collection can be composed of different types of objects and Rails will render the corresponding partial for each one.

<%# customers/_customer.html.erb -%>
<p>Customer: <%= customer.name %></p>

<%# employees/_employee.html.erb -%>
<p>Employee: <%= employee.name %></p>

<%# index.html.erb -%>
<h1>Contacts</h1>

<%# Rails will render the matching partial for customer and employee objects -%>
<%= render [customer1, employee1, customer2, employee2] %>

If the collection is empty, render will return nil so you can define a fallback.

<h1>Products</h1>
<%= render(@products) || "There are no products available." %>

Spacer Templates

You can also specify a second partial to be rendered between instances of the main partial by using the :spacer_template option:

<%= render partial: @products, spacer_template: "product_ruler" %>

Rails will render the _product_ruler.html.erb partial (with no data passed to it) between each pair of _product.html.erb partials.

Iteration Variables

Rails injects two additional variables into each partial when rendering a collection: