module `ActionView::Helpers::RenderingHelper`

Action View Rendering Helpers

Implements methods that allow rendering from a view context. In order to use this module, all you need is to implement view_renderer that returns an ActionView::Renderer object.

Public instance methods

`_layout_for(*args, &block)`

Overrides _layout_for in the context object so it supports the case a block is passed to a partial. Returns the contents that are yielded to a layout, given a name or a block.

You can think of a layout as a method that is called with a block. If the user calls yield :some_name, the block, by default, returns content_for(:some_name). If the user calls simply yield, the default block returns content_for(:layout).

The user can override this default by passing a block to the layout:

# The template
<%= render layout: "my_layout" do %>
  Content
<% end %>

# The layout
<html>
  <%= yield %>
</html>

In this case, instead of the default block, which would return content_for(:layout), this method returns the block that was passed in to render :layout, and the response would be

<html>
  Content
</html>

Finally, the block can take block arguments, which can be passed in by yield:

# The template
<%= render layout: "my_layout" do |customer| %>
  Hello <%= customer.name %>
<% end %>

# The layout
<html>
  <%= yield Struct.new(:name).new("David") %>
</html>

In this case, the layout would receive the block passed into render :layout, and the struct specified would be passed into the block as an argument. The result would be

<html>
  Hello David
</html>

Source code GitHub

# File actionview/lib/action_view/helpers/rendering_helper.rb, line 207
def _layout_for(*args, &block)
  name = args.first

  if block && !name.is_a?(Symbol)
    capture(*args, &block)
  else
    super
  end
end

`render(options = {}, locals = {}, &block)`

Renders a template and returns the result.

Pass the template to render as the first argument. This is shorthand syntax for partial rendering, so the template filename should be prefixed with an underscore. The partial renderer looks for the partial template in the directory of the calling template first.

<% # app/views/posts/new.html.erb %>
<%= render "form" %>
# => renders app/views/posts/_form.html.erb

Use the complete view path to render a partial from another directory.

<% # app/views/posts/show.html.erb %>
<%= render "comments/form" %>
# => renders app/views/comments/_form.html.erb

Without the rendering mode, the second argument can be a Hash of local variable assignments for the template.

<% # app/views/posts/new.html.erb %>
<%= render "form", post: Post.new %>
# => renders app/views/posts/_form.html.erb

If the first argument responds to render_in, the template will be rendered by calling render_in with the current view context.

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

  def format
    :html
  end
end

<%= render Greeting.new %>
# => "<h1>Hello, World</h1>"

Rendering Mode

Pass the rendering mode as first argument to override it.

:partial: See ActionView::PartialRenderer for details.

    <%= render partial: "form", locals: { post: Post.new } %>
    # => renders app/views/posts/_form.html.erb

:file: Renders the contents of a file. This option should not be used with unsanitized user input.

    <%= render file: "/path/to/some/file" %>
    # => renders /path/to/some/file

:inline: Renders an ERB template string.

    <% name = "World" %>
    <%= render inline: "<h1>Hello, <%= name %>!</h1>" %>
    # => renders "<h1>Hello, World!</h1>"

:body: Renders the provided text, and sets the format as :text.

    <%= render body: "Hello, World!" %>
    # => renders "Hello, World!"

:plain: Renders the provided text, and sets the format as :text.

    <%= render plain: "Hello, World!" %>
    # => renders "Hello, World!"

:html: Renders the provided HTML string, and sets the format as :html. If the string is not html_safe?, performs HTML escaping on the string before rendering.

    <%= render html: "<h1>Hello, World!</h1>".html_safe %>
    # => renders "<h1>Hello, World!</h1>"

    <%= render html: "<h1>Hello, World!</h1>" %>
    # => renders "&lt;h1&gt;Hello, World!&lt;/h1&gt;"

:renderable: Renders the provided object by calling render_in with the current view context. The format is determined by calling format on the renderable if it responds to format, falling back to :html by default.

    <%= render renderable: Greeting.new %>
    # => renders "<h1>Hello, World</h1>"

Options

:locals: Hash of local variable assignments for the template.

    <%= render inline: "<h1>Hello, <%= name %>!</h1>", locals: { name: "World" } %>
    # => renders "<h1>Hello, World!</h1>"

:formats: Override the current format to render a template for a different format.

    <% # app/views/posts/show.html.erb %>
    <%= render template: "posts/content", formats: [:text] %>
    # => renders app/views/posts/content.text.erb

:variants: Render a template for a different variant.

    <% # app/views/posts/show.html.erb %>
    <%= render template: "posts/content", variants: [:tablet] %>
    # => renders app/views/posts/content.html+tablet.erb

:handlers: Render a template for a different handler.

    <% # app/views/posts/show.html.erb %>
    <%= render template: "posts/content", handlers: [:builder] %>
    # => renders app/views/posts/content.html.builder

Source code GitHub

# File actionview/lib/action_view/helpers/rendering_helper.rb, line 138
def render(options = {}, locals = {}, &block)
  case options
  when Hash
    in_rendering_context(options) do |renderer|
      if block_given?
        view_renderer.render_partial(self, options.merge(partial: options[:layout]), &block)
      else
        view_renderer.render(self, options)
      end
    end
  else
    if options.respond_to?(:render_in)
      options.render_in(self, &block)
    else
      view_renderer.render_partial(self, partial: options, locals: locals, &block)
    end
  end
end

Definition files

actionview/lib/action_view/helpers/rendering_helper.rb

module ActionView::Helpers::RenderingHelper