ERB views, layouts, partials and helpers

The batch page of Kaksha, the coaching-centre app this track builds, is an action of two lines with no render call in it, and the HTML that leaves it comes out of four files: a controller, a template, a layout and one partial rendered three times, plus the helpers called inside them. Two kinds of trouble start in that handover. One is a page that looks nothing like the one you edited, because Rails picked a different file. The other is a guardian’s typed text turning into a pop-up, because one output tag was written the wrong way.

This lesson follows one recorded render of that page. You will see which files Rails chose and why, how the layout’s three holes were filled, what a partial refuses when a local is misspelt, and a check counting the script elements that reached the page with the safe tag and with the unsafe one.

Rails picks the template from the controller, the action and the format

Here is the whole controller behind the page. The index action sets one instance variable and ends:

# The action sets one instance variable and renders nothing: Rails then renders app/views/batches/index.html.erb
# wrapped in app/views/layouts/batches.html.erb.
class BatchesController < ApplicationController
  def index
    @batches = Batch.ordered
  end

  def show
    @batch = Batch.find(params[:id])
  end
end

Because it calls neither render nor redirect_to, Action View has to work out what to render from two names it already has: the controller, batches, and the action, index. It looks for app/views/batches/index, then narrows that by the format the request asked for, html, and the last extension names the library that compiles the file. index.html.erb matches both. If the file is not there, the search does not stop: Rails walks the controller’s inheritance chain and tries app/views/application/index.html.erb too, which is why shared partials belong in app/views/application. Only when nothing is found anywhere does it raise.

Step through the lookup, one stage per step, and watch the names the recorded run of the page later confirms:

Now the render itself. Action View is asked for the page outside a request, so nothing listens on a port, and the HTML is printed as it would be sent. Read the comments in the output first: in development a new app sets config.action_view.annotate_rendered_view_with_filenames to true, so every template, partial and layout marks where its own output begins and ends.

# The batch page of Kaksha, rendered by the real Action View. ../batchpage holds the files this lesson adds to the
# generated app (the controller, the model, the template, the partial, the layout and the routes); ../render_batch_page.rb
# renders BatchesController#index and prints the HTML.
require_relative "session"

Session.run(<<~SH)
  cd ../kaksha
  cp -R ../batchpage/app ../batchpage/config .
  bin/rails runner ../render_batch_page.rb
SH

$ cd ../kaksha
$ cp -R ../batchpage/app ../batchpage/config .
$ bin/rails runner ../render_batch_page.rb
<!-- BEGIN app/views/layouts/batches.html.erb
--><!DOCTYPE html>
<html lang="en">
  <head>
    <title>Batches | Kaksha</title>
      <meta name="description" content="Batches running at the Pune centre">

  </head>
  <body>
    <header>Kaksha, Pune centre</header>
    <main><!-- BEGIN app/views/batches/index.html.erb
-->
<h1>3 batches running</h1>

<!-- BEGIN app/views/batches/_batch.html.erb
--><article id="batch_1">
  <h2><a href="/batches/1">Class 10 maths, morning</a></h2>
  <p>Teacher Asha Rane, 28 seats</p>
    <p>Fee ₹12,000 a term</p>
</article>
<!-- END app/views/batches/_batch.html.erb --><!-- BEGIN app/views/batches/_batch.html.erb
--><article id="batch_2">
  <h2><a href="/batches/2">Class 12 physics, evening</a></h2>
  <p>Teacher Imran Shah, 22 seats</p>
    <p>Fee ₹18,000 a term</p>
</article>
<!-- END app/views/batches/_batch.html.erb --><!-- BEGIN app/views/batches/_batch.html.erb
--><article id="batch_3">
  <h2><a href="/batches/3">Spoken English, weekend</a></h2>
  <p>Teacher Nila Menon, 35 seats</p>
    <p>Fee ₹6,000 a term</p>
</article>
<!-- END app/views/batches/_batch.html.erb -->
<!-- END app/views/batches/index.html.erb --></main>
  </body>
</html>
<!-- END app/views/layouts/batches.html.erb -->
--- partial rendered 3 times, one per batch

Three files signed their work in those comments: the layout opened the body, batches/index.html.erb produced the heading, and batches/_batch.html.erb appears three times, once per row of the collection. The two numbers in the output are the lesson’s own: the heading says three batches, and the last line counts three renders of the partial.

A layout wraps the template, and named blocks fill its holes

Rails renders the template first and hands the result to a layout, and the layout it picks follows the controller’s name: app/views/layouts/batches.html.erb for anything BatchesController renders, and app/views/layouts/application.html.erb when no such file exists. The one in this app is deliberately small:

<%# A layout named after the controller: Rails prefers app/views/layouts/batches.html.erb over application.html.erb
    for every action of BatchesController. The unnamed yield receives the whole template; yield :head receives
    whatever the template collected under content_for :head. %>
<!DOCTYPE html>
<html lang="en">
  <head>
    <title><%= content_for(:title) || "Kaksha" %></title>
    <%= yield :head %>
  </head>
  <body>
    <header>Kaksha, Pune centre</header>
    <main><%= yield %></main>
  </body>
</html>

A layoutlayout: A template that wraps the one an action renders: the plain yield receives the whole template's output and each named yield receives a block the template collected with content_for. has one hole that is always filled and as many named ones as you like. The plain yield receives the whole template; yield :head receives whatever the template collected under that name with content_for. The generated application.html.erb of a new Rails 8.1 app uses both ideas already: it has yield :head inside its head element, and its title element reads content_for(:title) || "Kaksha", which is the page’s own title when a template set one and the app’s name when none did.

The template fills all three holes and renders nothing else of its own except a heading and the collection:

<%# app/views/batches/index.html.erb: the template Rails renders for BatchesController#index when the action
    renders nothing itself. content_for fills the layout's two holes; render @batches renders one partial per row. %>
<% content_for :title, "Batches | Kaksha" %>
<% content_for :head do %>
  <meta name="description" content="Batches running at the Pune centre">
<% end %>

<h1><%= pluralize(@batches.size, "batch") %> running</h1>

<%= render @batches %>

The order is what makes this work, and the diagram below is worth reading next to the recorded output above: the template runs before the layout, so by the time the layout asks for :title and :head, both are already collected.

In the recorded page, Batches | Kaksha is in the title element and the description meta element sits in the head, neither of them written in the layout. Everything else the template produced landed at the plain yield.

Partials follow the same inheritance rule as templates, so a piece of furniture that two controllers share can live in app/views/application and be rendered from either template by name.

Partials take locals, and a strict-locals line turns a typo into an error

A partialpartial: A template whose file name starts with an underscore, rendered from another template and referred to without that underscore, so that one piece of markup can be reused with different data. is a template whose file name starts with an underscore, rendered from another template and referred to without that underscore: render "batch" renders _batch.html.erb. Partials exist to be called with different data each time, so what they receive matters more than what they contain. This one declares what it accepts on its first line:

<%# locals: (batch:, show_fee: true) -%>
<article id="<%= dom_id(batch) %>">
  <h2><%= link_to batch.name, batch_path(batch) %></h2>
  <p>Teacher <%= batch.teacher %>, <%= batch.seats %> seats</p>
  <% if show_fee %>
    <p>Fee <%= number_to_currency(batch.fee_paise / 100, unit: "₹", precision: 0) %> a term</p>
  <% end %>
</article>

That first line is an ERB comment that Action View reads as a signature. Without it a partial accepts any locals at all, and a misspelt name silently becomes nil, because partials are compiled into Ruby methods and one version is compiled for every combination of locals passed in. With it, exactly one version is compiled, batch is required, and show_fee has a default of true. Four renders of the same file show what that buys:

# Four renders of the same partial through its strict-locals signature: both locals given, the default used, a
# required local missing, and a local whose name is misspelt.
require_relative "session"

Session.run(<<~SH)
  cd ../kaksha
  cp -R ../batchpage/app ../batchpage/config .
  bin/rails runner ../strict_locals_probe.rb
SH

$ cd ../kaksha
$ cp -R ../batchpage/app ../batchpage/config .
$ bin/rails runner ../strict_locals_probe.rb
both locals given: rendered, fee paragraph left out
show_fee left out: rendered, fee paragraph included
batch left out   : ActionView::StrictLocalsError: missing local: :batch for app/views/batches/_batch.html.erb
show_fees misspelt: ActionView::StrictLocalsError: unknown local: :show_fees for app/views/batches/_batch.html.erb

The first render passed show_fee: false and the fee paragraph is gone. The second passed only batch and the default put the fee back. The third and fourth raise ActionView::StrictLocalsError and name the file: once for missing local: :batch, once for unknown local: :show_fees, the misspelling that would otherwise have rendered a page with no fee on it and no error anywhere.

The template never passed locals by hand, though. render @batches is the collection form: Rails asks each record for its partial path, renders _batch once per record, and passes the record as a local named after the partial, which is exactly the batch the signature requires. The table gives that form and the three options worth knowing beside it:

An empty collection makes render return nil, so render(@batches) || "No batches yet." is the usual way to write the empty case.

The default output tag escapes, and raw is where cross-site scripting starts

Everything so far assumed the data is harmless. A coaching centre’s data is typed by people: a batch name arrives from a form, and someone will eventually type markup into it. The OWASP Cross Site Scripting Prevention Cheat Sheet asks for encoding at the place where untrusted data is written into the page, and in Action View that place is the output tag. <%= %> escapes what it prints; <% %> prints nothing at all and is for conditions and loops.

Three renders of one batch whose name is a script element show what each way produces. The check under each render is Nokogiri parsing the result and counting the script elements a browser would have run, which is the only count that matters:

# Output escaping in Action View, with a check that proves it. A batch whose name is a <script> element is rendered
# three ways; Nokogiri then counts the script elements that reached the page, which is what a browser would run.
# The raw version is here only to be recognised and never written: it is the usual start of a stored XSS defect.
require "action_view"
require "nokogiri"

NAME = "<script>alert(1)</script>"
NOTICE = "<p>Fees due <b>Friday</b>.</p><script>alert(2)</script>"

view = ActionView::Base.with_empty_template_cache.new(ActionView::LookupContext.new([]), {}, nil)

def check(html)
  found = Nokogiri::HTML5.fragment(html).css("script").size
  puts "#{html}"
  puts "  check: #{found} script element(s) reached the page -> #{found.zero? ? "PASS" : "FAIL"}"
end

puts "1. <%= %>, the default:"
check(view.render(inline: "<h2><%= name %></h2>", locals: { name: NAME }))

puts "2. raw, never do this with anything a user typed:"
check(view.render(inline: "<h2><%= raw name %></h2>", locals: { name: NAME }))

puts "3. sanitize with an allowlist, for a field that is meant to hold HTML:"
check(view.render(inline: "<div><%= sanitize notice, tags: %w[p b i a], attributes: %w[href] %></div>",
                   locals: { notice: NOTICE }))

puts "4. the same three values as Ruby strings:"
puts "  html_safe? of the name          #{NAME.html_safe?}"
puts "  html_safe? after .html_safe     #{NAME.html_safe.html_safe?}"
puts "  html_safe? of sanitize's result #{view.sanitize(NOTICE).html_safe?}"

1. <%= %>, the default:
<h2>&lt;script&gt;alert(1)&lt;/script&gt;</h2>
  check: 0 script element(s) reached the page -> PASS
2. raw, never do this with anything a user typed:
<h2><script>alert(1)</script></h2>
  check: 1 script element(s) reached the page -> FAIL
3. sanitize with an allowlist, for a field that is meant to hold HTML:
<div><p>Fees due <b>Friday</b>.</p>alert(2)</div>
  check: 0 script element(s) reached the page -> PASS
4. the same three values as Ruby strings:
  html_safe? of the name          false
  html_safe? after .html_safe     true
  html_safe? of sanitize's result true

With <%= %> the angle brackets came out as < and >, the page shows the name as text, and the check found no script element. With raw the element went straight through and the check found one: that is a stored cross-site-scripting defect, and the only reason it is in this lesson is so that you can recognise the shape in a code review. The third render is the case where HTML really is wanted: sanitize keeps an allowlist of tags and attributes, so the p and b elements survived, the script element did not, and its text was left behind as plain words.

Four ways of printing a value, the first safe and the other three not, are worth knowing by name:

The last block of the recorded output is the state they share: Action View asks every string it prints whether it is HTML-safeHTML-safe: A flag on a string that tells Action View it may be printed unescaped; sanitize sets it on markup it has checked against an allowlist, and html_safe sets it on any string at all.. A plain batch name answers no, so it is escaped. The same name after .html_safe answers yes, so it is not. The result of sanitize answers yes too, and that answer is earned: the markup was checked against the allowlist before it was marked. The default sanitizer in Rails 8.1 is Rails::HTML5::SafeListSanitizer, and its documentation warns that adding tags or attributes to the allowlist may introduce vulnerabilities, so the default lists are the ones to keep.

The helpers almost every page uses

A view helperview helper: A method available inside templates, such as link_to or number_to_currency, that builds a piece of markup or formats a value, so that templates hold markup rather than logic. is a method available inside templates, and Action View ships with several hundred. The batch page used four of them: pluralize in the template, and dom_id, link_to and number_to_currency in the partial. This run prints each on the first batch, so the output and the page agree value for value:

# The built-in view helpers on one batch of Kaksha. The render happens outside a request, so there is no session and
# the form that button_to builds carries no hidden authenticity_token field; in a real request Rails adds one.
require_relative "session"

Session.run(<<~SH)
  cd ../kaksha
  cp -R ../batchpage/app ../batchpage/config .
  bin/rails runner ../helper_tour.rb
SH

$ cd ../kaksha
$ cp -R ../batchpage/app ../batchpage/config .
$ bin/rails runner ../helper_tour.rb
link_to          <a href="/batches/1">Class 10 maths, morning</a>
dom_id           batch_1 and new_batch
dom_class        batch
number_to_currency ₹12,000
number_with_delimiter 12,000
l(:long)         May 10, 2031
l(:short)        May 10
time_ago_in_words 3 days and 35 minutes
pluralize        1 batch / 3 batches
truncate         Class 10 maths,...

button_to builds a form that posts, not a link:
<!-- BEGIN inline template
--><form class="button_to" method="post" action="/batches/1/attendance"><button type="submit">Mark attendance</button></form>
<!-- END inline template -->

link_to built the anchor, with the path from the route helper rather than a hand-written string, so a change to config/routes.rb cannot leave a dead link behind. number_to_currency and number_with_delimiter grouped the amount; l formatted the date twice, in the :long and :short formats the locale file defines; time_ago_in_words turned two moments into “3 days” and “35 minutes”; pluralize and truncate did the small jobs that otherwise fill a template with ifs.

Two of the lines deserve a second look. dom_id returned batch_1 for a saved record and new_batch for an unsaved one, and dom_class returned batch: these are the conventional ids and classes that form_with writes and that Turbo targets, so using the helper instead of typing "batch_#{batch.id}" keeps your markup and the framework’s in step. And button_to produced a form element with method="post", not an anchor. That difference is the point: a state change belongs in a non-GET request, and the Rails security guide’s countermeasure for cross-site request forgery is a security token in non-GET requests, added automatically because config.action_controller.default_protect_from_forgery is true in a new app. Rails puts that token in the forms it builds, so button_to is protected where a styled link is not. The recorded form has no token field only because the render happened outside a request, where there is no session to tie a token to.

One thing about these templates will change in the next minor release, and it is worth building the habit now.

Practise: predict what each file renders

These questions are taken from the four runs above: the rendered page, the four sets of locals, the three ways of printing a dangerous name, and the helper output. Answer one and its explanation opens at once:

Interview questions

Warm-up: which Action View tag escapes its output, and which three ways of printing a value do not?

<%= %> escapes, unless the value it prints is already marked HTML-safe, so &, ", < and > reach the page as character references and a typed script element is shown as text. Three ways skip that. raw value prints the value unchanged and is only value.to_s.html_safe written differently. <%== value %> is the same thing in tag form, which makes it easy to read as <%= %> in a code review. And value.html_safe marks the string itself, so every later <%= %> prints it as it is, however far from the template that marking happened. The safe way to print a field that is meant to carry markup is sanitize, which checks the markup against an allowlist of tags and attributes and marks only the result as safe.

The module’s question bank takes two longer cases from this page, one on a field that must keep its formatting and one on where shared page furniture belongs. Write down your own answer to both before you read what each question sets out to test:

Key takeaways

• An action that renders nothing gets the template named after its controller and action, narrowed by the request’s format, and Rails walks the controller’s inheritance chain, through app/views/application, before it raises.
• The template is rendered before the layout, which Rails picks by controller name and then by layouts/application.html.erb; the plain yield takes the body and a named yield takes whatever content_for collected.
• A partial’s strict-locals signature makes required locals required and misspelt ones an error, which is why the recorded run raised ActionView::StrictLocalsError instead of rendering a page with a missing fee.
• render @batches renders one partial per record with the record in a local named after the partial, and brings the counter, renaming, the empty-collection result and cached: true with it.
• <%= %> escapes by default, and raw, <%== %> and html_safe are the three ways that defect reports begin: the check on the recorded run found a script element in the page only in the raw version.
• The built-in helpers keep markup in step with the framework: route helpers inside link_to, button_to for a state change in a non-GET form, and dom_id for the ids that forms and Turbo already expect.