# frozen_string_literal: true
# :markup: markdown
module ActionView
module Helpers # :nodoc:
# # 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.
module RenderingHelper
# 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 "<h1>Hello, World!</h1>"
#
# `: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
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
# 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>
#
def _layout_for(*args, &block)
name = args.first
if block && !name.is_a?(Symbol)
capture(*args, &block)
else
super
end
end
end
end
end