skip to content

In a Rails controller, what do render's template:, plain:, html:, body: and inline: options each send, and which of them use the layout?

level: juniorimportance: nice to knowfreq 25%

answer

  1. a path with a slash means template:
  2. plain: is text/plain
  3. html: escapes unless html_safe
  4. inline: compiles ERB per call
  5. layout only for template renders by default

basics

~20 s

template: renders a view file by path inside the layout; plain: sends text/plain; html: sends text/html, escaping strings not marked html_safe; body: sends the string as is, text/plain unless content_type: says otherwise; inline: renders an ERB string. Only template renders get the layout unless layout: is passed.

solid answer

~40 s

`render template: "tickets/show"` (or `render "tickets/show"`, since a slash means a template path) finds a view file and wraps it in the controller's layout. The text modes skip the layout unless you pass `layout:`: `plain:` sends the string as `text/plain`; `html:` sends `text/html` and runs `ERB::Util.html_escape`, so a string that is not `html_safe` arrives escaped; `body:` sends the raw string and lands as `text/plain` unless you set `content_type:` or the header first; `inline:` compiles an ERB string in the view context, with helpers and instance variables, every time it is called. All accept `status:`. In Rails 8.1 these replace `render :text` and `render :nothing`, both removed in Rails 5.1.

code

ruby · 11 lines
ruby
class Tickets::StatusController < ApplicationController
  def show
    ticket = Ticket.find(params.expect(:ticket_id))

    case request.format.symbol
    when :html then render html: helpers.tag.span(ticket.status, class: "badge")
    when :text then render plain: ticket.status
    else head :not_acceptable
    end
  end
end

go deeper

for a junior

Recall that template renders use the layout, plain: sends text/plain and html: sends text/html, and that render :text no longer exists.

for a middle

Explain html:'s escaping rule, body:'s default content type, the slash rule between action: and template:, and that text modes skip the layout unless layout: is given.

for a senior

Show you keep markup in templates, use helpers for safe HTML fragments, refuse inline: with request data, and choose head when no body is needed.

for a principal

Treat inline: and hand-built HTML strings as review flags, and keep controller responses either template-backed or status-only so escaping stays in Action View.

## Template renders and text renders `render` in a Rails controller has two families of options: - **Template renders** look up a view file: `render :show`, `render action: :show`, `render "tickets/show"` and `render template: "tickets/show"`. A bare string or symbol becomes `action:` when it has no slash and `template:` when it has one. - **Text renders** send a string you supply: `plain:`, `html:`, `body:` and `inline:` (which is a string, but one that is compiled as a template). `render json:` belongs to the JSON-rendering topic, and `partial:` and `layout:` choices to the view topics; this answer covers the rest. ## Each option in turn | Option | What is sent | Content-Type | Layout by default | |---|---|---|---| | `template:` / `action:` | the view file's output | the template's format, e.g. `text/html` | yes | | `plain:` | the string as given | `text/plain` | no | | `html:` | the string, HTML-escaped unless `html_safe` | `text/html` | no | | `body:` | the string as given | `text/plain` unless you set one | no | | `inline:` | an ERB string compiled and rendered | the request format | no | Some detail on each: - **`plain:`** is for short plain-text answers, such as a health response or a message to a script. With `layout: true` Rails looks for a `.text.erb` layout. - **`html:`** calls `ERB::Util.html_escape` on the value. `render html: "<p>Closed</p>"` therefore arrives as visible `&lt;p&gt;` text. Build the string with tag helpers or mark it with `html_safe` only when you trust every part of it. - **`body:`** is the raw option. It sets nothing beyond what the renderer defaults to, so the response is `text/plain` unless a `Content-Type` was already set or you pass `content_type:`. It suits a pre-built payload in a format you name yourself. - **`inline:`** compiles an ERB string with the full view context, so `@ticket` and helpers work. A new template object is built on every call, and ERB in the controller is hard to read; the Rails guide calls good reasons for it rare. Never interpolate request input into it, because that input would run as template code. ## Options shared by every mode - **`status:`** takes an integer or a Rack symbol and defaults to 200. - **`content_type:`** overrides the type the mode would set. - **`layout:`** turns the layout on (`true` or a layout name) for text modes, or off (`false`) for template renders. - **`locals:`** and **`assigns:`** pass variables into template and inline renders. Calling `render` a second time in the same action raises `AbstractController::DoubleRenderError`, whichever mode either call used. ## Status symbols Every `status:` value goes through `ActionDispatch::Response.rack_status_code` and then Rack's symbol table, which is built from the reason phrases: `:ok`, `:created`, `:not_found`, `:forbidden`, `:unprocessable_content`. Two details matter in Rails 8.1: - **`:unprocessable_content` is the current name for 422.** With Rack 3.1 or later Rails maps the older `:unprocessable_entity` to it before Rack sees it, so old code still sends 422, but new code and the scaffold use the new name. - **An unknown symbol raises** `ArgumentError` ("Unrecognized status code"), at the moment `render` runs, not at boot. ## Which one to use 1. A page a person reads: a **template**, so markup lives in `app/views` with the layout around it. 2. A short machine-readable string: **`plain:`**, or **`head`** if a status says it all. 3. A tiny HTML fragment, often built with `helpers.tag`: **`html:`**. 4. Bytes in a format you name: **`body:`** with `content_type:`. 5. **`inline:`** almost never; move the ERB into a file. ## Retired names - **`render :text`** was removed in Rails 5.1. It sent its string as `text/html`, which the Rails 4.1 upgrade notes flagged as a security risk when the text was not meant to be markup. Use `plain:` or `html:`. - **`render :nothing`** was removed at the same time. Use `head`.

  • What reaches the browser from render html: "<strong>Urgent</strong>"?
    The text `&lt;strong&gt;Urgent&lt;/strong&gt;` with `Content-Type: text/html`. The `html:` option escapes any string that is not `html_safe`, so the tags show up literally. Use `helpers.tag.strong("Urgent")`, which returns a safe buffer, or mark a fully trusted literal `html_safe`.
  • How do render "show" and render "tickets/show" differ?
    Without a slash the string is treated as an action name, `render action: "show"`, and the template is looked up under the controller's own view prefixes. With a slash it is a path, `render template: "tickets/show"`, which any controller can use to render another controller's view.

  • render :text is still the way to send plain text in Rails 8.1
  • render html: sends any string unescaped, so tags always render
  • render plain: wraps the text in the application layout by default
  • render inline: is cached like a file template, so it is as fast
  • render body: has to be used for every non-HTML response

Assumes Rails 8.1; render :text and render :nothing were removed in Rails 5.1, so plain:, html:, body: and head replace them.