Pass render options and block to calls to #render_in

Closes [rails#45432][]

Support for objects that respond to `#render_in` was introduced in
[rails#36388][] and [rails#37919][]. Those implementations assume that the
instance will all the context it needs to render itself. That assumption
doesn't account for call-site arguments like `locals: { ... }` or a
block.

This commit expands support for rendering with a `:renderable` option to
incorporate locals and blocks. For example:

```ruby
class Greeting
  def render_in(view_context, **options, &block)
    if block
      view_context.render plain: block.call
    else
      case Array(options[:formats]).first
      when :json
        view_context.render json: { greeting: "Hello, World!" }
      else
        view_context.render **options, inline: "<%= Hello, <%= name %>!"
      end
    end
  end
end

render(Greeting.new)                              # => "Hello, World!"
render(Greeting.new, name: "Local")               # => "Hello, Local!"
render(Greeting.new) { "Hello, Block!" }          # => "Hello, Block!"

render(renderable: Greeting.new, formats: :json)  # => "{\"greeting\":\"Hello, World!\"}"
```

Since existing tools depend on the `#render_in(view_context)` signature
without options, this commit deprecates that signature in favor of one
that accepts options and a block.

[rails#45432]: rails#45432
[rails#36388]: rails#36388
[rails#37919]: rails#37919

Author: seanpdoyle

actionpack/CHANGELOG.md

@@ -1,3 +1,30 @@
+*   Accept render options and block in `render_to_string` calls made with `:renderable`
+
+    ```ruby
+    class Greeting
+      def render_in(view_context, locals: {}, formats: nil, &block)
+        if block
+          view_context.render plain: block.call
+        else
+          case Array(formats).first
+          when :json
+            view_context.render plain: { greeting: "Hello, #{locals.fetch(:name, "World")}!" }.to_json
+          else
+            view_context.render inline: <<~ERB.strip, locals: locals
+              Hello, <%= local_assigns.fetch(:name, "World") %>!
+            ERB
+          end
+        end
+      end
+    end
+
+    ApplicationController.render(Greeting.new, name: "Local")               # => "Hello, Local!"
+    ApplicationController.render(Greeting.new) { "Hello, Block!" }          # => "Hello, Block!"
+    ApplicationController.render(renderable: Greeting.new, formats: :json)  # => "{\"greeting\":\"Hello, World!\"}"
+    ```
+
+    *Sean Doyle*
+
 *   Add `allow_browser` to set minimum browser versions for the application.
 
     A browser that's blocked will by default be served the file in `public/426.html` with a HTTP status code of "426 Upgrade Required".

actionpack/lib/abstract_controller/rendering.rb

@@ -42,11 +42,11 @@ def render(*args, &block)
     # needs to be overridden in order to still return a string.
     def render_to_string(*args, &block)
       options = _normalize_render(*args, &block)
-      render_to_body(options)
+      render_to_body(options, &block)
     end
 
     # Performs the actual template rendering.
-    def render_to_body(options = {})
+    def render_to_body(options = {}, &block)
     end
 
     # Returns +Content-Type+ of rendered content.

actionpack/lib/action_controller/metal/rendering.rb

@@ -37,7 +37,31 @@ def inherited(klass)
     #   # => renders app/views/posts/show.html.erb
     #
     # If the first argument responds to +render_in+, the template will be
-    # rendered by calling +render_in+ with the current view context.
+    # rendered by calling +render_in+ with the current view context, render
+    # options, and block.
+    #
+    #   class Greeting
+    #     def render_in(view_context, **options, &block)
+    #       if block
+    #         view_context.render html: block.call
+    #       else
+    #         view_context.render inline: <<~ERB.strip, **options
+    #           <%= Hello, <%= local_assigns.fetch(:name, "World") %>
+    #         ERB
+    #       end
+    #     end
+    #
+    #     def format
+    #       :html
+    #     end
+    #   end
+    #
+    #   render(Greeting.new)                                        # => "Hello, World"
+    #   render(renderable: Greeting.new)                            # => "Hello, World"
+    #   render(Greeting.new, name: "Local")                         # => "Hello, Local"
+    #   render(renderable: Greeting.new, locals: { name: "Local" }) # => "Hello, Local"
+    #   render(Greeting.new) { "Hello, Block" }                     # => "Hello, Block"
+    #   render(renderable: Greeting.new) { "Hello, Block" }         # => "Hello, Block"
     #
     #   class Greeting
     #     def render_in(view_context)
@@ -110,12 +134,16 @@ def inherited(klass)
     #
     # [+:renderable+]
     #   Renders the provided object by calling +render_in+ with the current view
-    #   context. The response format is determined by calling +format+ on the
-    #   renderable if it responds to +format+, falling back to +text/html+ by default.
+    #   context, render options, and block. The response format is determined by
+    #   calling +format+ on the renderable if it responds to +format+, falling
+    #   back to +text/html+ by default.
     #
     #     render renderable: Greeting.new
     #     # => renders "<h1>Hello, World</h1>"
     #
+    #     render renderable: Greeting.new, locals: { name: "Local" }
+    #     # => renders "Hello, Local"
+    #
     # By default, when a rendering mode is specified, no layout template is
     # rendered.
     #

actionpack/lib/action_controller/renderer.rb

@@ -120,14 +120,14 @@ def defaults
     end
 
     # Renders a template to a string, just like ActionController::Rendering#render_to_string.
-    def render(*args)
+    def render(...)
       request = ActionDispatch::Request.new(env_for_request)
       request.routes = controller._routes
 
       instance = controller.new
       instance.set_request! request
       instance.set_response! controller.make_response!(request)
-      instance.render_to_string(*args)
+      instance.render_to_string(...)
     end
     alias_method :render_to_string, :render # :nodoc:
 

actionpack/test/controller/renderer_test.rb

@@ -77,6 +77,40 @@ class RendererTest < ActiveSupport::TestCase
       %(Hello, World!),
       renderer.render(renderable: TestRenderable.new)
     )
+    assert_equal(
+      %(Hello, Local!),
+      renderer.render(TestRenderable.new, name: "Local")
+    )
+    assert_equal(
+      %(Hello, Local!),
+      renderer.render(renderable: TestRenderable.new, locals: { name: "Local" })
+    )
+  end
+
+  test "render a renderable object with :formats" do
+    renderer = ApplicationController.renderer
+
+    assert_equal(
+      { greeting: "Hello, World!" }.to_json,
+      renderer.render(renderable: TestRenderable.new, formats: :json)
+    )
+    assert_equal(
+      { greeting: "Hello, Local!" }.to_json,
+      renderer.render(renderable: TestRenderable.new, locals: { name: "Local" }, formats: :json)
+    )
+  end
+
+  test "render a renderable object with block" do
+    renderer = ApplicationController.renderer
+
+    assert_equal(
+      %(Goodbye, World!),
+      renderer.render(TestRenderable.new) { "Goodbye, World!" }
+    )
+    assert_equal(
+      %(Goodbye, World!),
+      renderer.render(renderable: TestRenderable.new) { "Goodbye, World!" }
+    )
   end
 
   test "rendering with custom env" do

actionpack/test/lib/test_renderable.rb

@@ -1,11 +1,17 @@
 # frozen_string_literal: true
 
 class TestRenderable
-  def render_in(_view_context)
-    "Hello, World!"
-  end
+  def render_in(view_context, locals: {}, formats: nil, **options, &block)
+    if block
+      view_context.render plain: block.call
+    elsif Array(formats).first == :json
+      json = { greeting: "Hello, #{locals.fetch(:name, "World")}!" }
 
-  def format
-    :html
+      view_context.render plain: json.to_json
+    else
+      view_context.render inline: <<~ERB.strip, locals: locals
+        Hello, <%= local_assigns.fetch(:name, "World") %>!
+      ERB
+    end
   end
 end

actionview/CHANGELOG.md

@@ -1,3 +1,32 @@
+*   Pass render options and block to calls to `#render_in`
+
+    ```ruby
+    class Greeting
+      def render_in(view_context, locals: {}, formats: nil, **options, &block)
+        if block
+          view_context.render plain: block.call
+        else
+          case Array(formats).first
+          when :json
+            json = { greeting: "Hello, #{locals.fetch(:name, "World")}!" }
+
+            view_context.render plain: json.to_json
+          else
+            view_context.render inline: <<~ERB.strip, locals: locals
+              Hello, <%= local_assigns.fetch(:name, "World") %>!
+            ERB
+          end
+        end
+      end
+    end
+
+    render(Greeting.new, name: "Local")               # => "Hello, Local!"
+    render(Greeting.new) { "Hello, Block!" }          # => "Hello, Block!"
+    render(renderable: Greeting.new, formats: :json)  # => "{\"greeting\":\"Hello, World!\"}"
+    ```
+
+    *Sean Doyle*
+
 *   Add the `nonce: true` option for `stylesheet_link_tag` helper to support automatic nonce generation for Content Security Policy.
     Works the same way as `javascript_include_tag nonce: true` does.
 

actionview/lib/action_view/helpers/rendering_helper.rb

@@ -24,22 +24,23 @@ module RenderingHelper
       # If no <tt>options</tt> hash is passed or if <tt>:update</tt> is specified, then:
       #
       # If an object responding to +render_in+ is passed, +render_in+ is called on the object,
-      # passing in the current view context.
+      # passing in the current view context, render options, and block. The
+      # object can optionally control its rendered format by defining the +format+ method.
       #
       # Otherwise, a partial is rendered using the second parameter as the locals hash.
       def render(options = {}, locals = {}, &block)
         case options
         when Hash
           in_rendering_context(options) do |renderer|
-            if block_given?
+            if block_given? && !options.key?(:renderable)
               view_renderer.render_partial(self, options.merge(partial: options[:layout]), &block)
             else
-              view_renderer.render(self, options)
+              view_renderer.render(self, options, &block)
             end
           end
         else
           if options.respond_to?(:render_in)
-            options.render_in(self, &block)
+            view_renderer.render(self, renderable: options, locals: locals, &block)
           else
             view_renderer.render_partial(self, partial: options, locals: locals, &block)
           end

actionview/lib/action_view/renderer/renderer.rb

@@ -20,15 +20,15 @@ def initialize(lookup_context)
     end
 
     # Main render entry point shared by Action View and Action Controller.
-    def render(context, options)
-      render_to_object(context, options).body
+    def render(context, options, &block)
+      render_to_object(context, options, &block).body
     end
 
-    def render_to_object(context, options) # :nodoc:
+    def render_to_object(context, options, &block) # :nodoc:
       if options.key?(:partial)
         render_partial_to_object(context, options)
       else
-        render_template_to_object(context, options)
+        render_template_to_object(context, options, &block)
       end
     end
 
@@ -54,8 +54,8 @@ def cache_hits # :nodoc:
     end
 
     private
-      def render_template_to_object(context, options)
-        TemplateRenderer.new(@lookup_context).render(context, options)
+      def render_template_to_object(context, options, &block)
+        TemplateRenderer.new(@lookup_context).render(context, options, &block)
       end
 
       def render_partial_to_object(context, options, &block)

actionview/lib/action_view/renderer/template_renderer.rb

@@ -2,9 +2,9 @@
 
 module ActionView
   class TemplateRenderer < AbstractRenderer # :nodoc:
-    def render(context, options)
+    def render(context, options, &block)
       @details = extract_details(options)
-      template = determine_template(options)
+      template = determine_template(options, &block)
 
       prepend_formats(template.format)
 
@@ -13,7 +13,7 @@ def render(context, options)
 
     private
       # Determine the template to be rendered using the given options.
-      def determine_template(options)
+      def determine_template(options, &block)
         keys = options.has_key?(:locals) ? options[:locals].keys : []
 
         if options.key?(:body)
@@ -41,7 +41,7 @@ def determine_template(options)
           end
           Template::Inline.new(options[:inline], "inline template", handler, locals: keys, format: format)
         elsif options.key?(:renderable)
-          Template::Renderable.new(options[:renderable])
+          Template::Renderable.new(options[:renderable], options[:formats], &block)
         elsif options.key?(:template)
           if options[:template].respond_to?(:render)
             options[:template]