actionpack 6.1.7.5 → 7.1.3.1

data/lib/action_controller/metal/renderers.rb

@@ -3,12 +3,12 @@
 require "set"
 
 module ActionController
-  # See <tt>Renderers.add</tt>
+  # See Renderers.add
   def self.add_renderer(key, &block)
     Renderers.add(key, &block)
   end
 
-  # See <tt>Renderers.remove</tt>
+  # See Renderers.remove
   def self.remove_renderer(key)
     Renderers.remove(key)
   end
@@ -31,8 +31,7 @@ module ActionController
       class_attribute :_renderers, default: Set.new.freeze
     end
 
-    # Used in <tt>ActionController::Base</tt>
-    # and <tt>ActionController::API</tt> to include all
+    # Used in ActionController::Base and ActionController::API to include all
     # renderers by default.
     module All
       extend ActiveSupport::Concern
@@ -45,7 +44,7 @@ module ActionController
 
     # Adds a new renderer to call within controller actions.
     # A renderer is invoked by passing its name as an option to
-    # <tt>AbstractController::Rendering#render</tt>. To create a renderer
+    # AbstractController::Rendering#render. To create a renderer
     # pass it a name and a block. The block takes two arguments, the first
     # is the value paired with its key and the second is the remaining
     # hash of options passed to +render+.
@@ -59,7 +58,7 @@ module ActionController
     #       disposition: "attachment; filename=#{filename}.csv"
     #   end
     #
-    # Note that we used Mime[:csv] for the csv mime type as it comes with Rails.
+    # Note that we used Mime[:csv] for the csv mime type as it comes with \Rails.
     # For a custom renderer, you'll need to register a mime type with
     # <tt>Mime::Type.register</tt>.
     #
@@ -96,18 +95,18 @@ module ActionController
       # Adds, by name, a renderer or renderers to the +_renderers+ available
       # to call within controller actions.
       #
-      # It is useful when rendering from an <tt>ActionController::Metal</tt> controller or
+      # It is useful when rendering from an ActionController::Metal controller or
       # otherwise to add an available renderer proc to a specific controller.
       #
-      # Both <tt>ActionController::Base</tt> and <tt>ActionController::API</tt>
-      # include <tt>ActionController::Renderers::All</tt>, making all renderers
-      # available in the controller. See <tt>Renderers::RENDERERS</tt> and <tt>Renderers.add</tt>.
+      # Both ActionController::Base and ActionController::API
+      # include ActionController::Renderers::All, making all renderers
+      # available in the controller. See Renderers::RENDERERS and Renderers.add.
       #
-      # Since <tt>ActionController::Metal</tt> controllers cannot render, the controller
-      # must include <tt>AbstractController::Rendering</tt>, <tt>ActionController::Rendering</tt>,
-      # and <tt>ActionController::Renderers</tt>, and have at least one renderer.
+      # Since ActionController::Metal controllers cannot render, the controller
+      # must include AbstractController::Rendering, ActionController::Rendering,
+      # and ActionController::Renderers, and have at least one renderer.
       #
-      # Rather than including <tt>ActionController::Renderers::All</tt> and including all renderers,
+      # Rather than including ActionController::Renderers::All and including all renderers,
       # you may specify which renderers to include by passing the renderer name or names to
       # +use_renderers+. For example, a controller that includes only the <tt>:json</tt> renderer
       # (+_render_with_renderer_json+) might look like:
@@ -133,7 +132,7 @@ module ActionController
       alias use_renderer use_renderers
     end
 
-    # Called by +render+ in <tt>AbstractController::Rendering</tt>
+    # Called by +render+ in AbstractController::Rendering
     # which sets the return value as the +response_body+.
     #
     # If no renderer is found, +super+ returns control to

data/lib/action_controller/metal/rendering.rb

@@ -24,19 +24,125 @@ module ActionController
       end
     end
 
-    # Before processing, set the request formats in current controller formats.
-    def process_action(*) #:nodoc:
-      self.formats = request.formats.map(&:ref).compact
-      super
-    end
-
+    # Renders a template and assigns the result to +self.response_body+.
+    #
+    # If no rendering mode option is specified, the template will be derived
+    # from the first argument.
+    #
+    #   render "posts/show"
+    #   # => renders app/views/posts/show.html.erb
+    #
+    #   # In a PostsController action...
+    #   render :show
+    #   # => 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.
+    #
+    # ==== \Rendering Mode
+    #
+    # [+:partial+]
+    #   See ActionView::PartialRenderer for details.
+    #
+    #     render partial: "posts/form", locals: { post: Post.new }
+    #     # => renders app/views/posts/_form.html.erb
+    #
+    # [+:file+]
+    #   Renders the contents of a file. This option should <b>not</b> 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 content type as +text/plain+.
+    #
+    #     render body: "Hello, World!"
+    #     # => renders "Hello, World!"
+    #
+    # [+:plain+]
+    #   Renders the provided text, and sets the content type as +text/plain+.
+    #
+    #     render plain: "Hello, World!"
+    #     # => renders "Hello, World!"
+    #
+    # [+:html+]
+    #   Renders the provided HTML string, and sets the content type as +text/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;"
+    #
+    # [+:json+]
+    #   Renders the provided object as JSON, and sets the content type as
+    #   +application/json+. If the object is not a string, it will be converted
+    #   to JSON by calling +to_json+.
+    #
+    #     render json: { hello: "world" }
+    #     # => renders "{\"hello\":\"world\"}"
+    #
+    # By default, when a rendering mode is specified, no layout template is
+    # rendered.
+    #
+    # ==== Options
+    #
+    # [+:assigns+]
+    #   Hash of instance variable assignments for the template.
+    #
+    #     render inline: "<h1>Hello, <%= @name %>!</h1>", assigns: { name: "World" }
+    #     # => renders "<h1>Hello, World!</h1>"
+    #
+    # [+:locals+]
+    #   Hash of local variable assignments for the template.
+    #
+    #     render inline: "<h1>Hello, <%= name %>!</h1>", locals: { name: "World" }
+    #     # => renders "<h1>Hello, World!</h1>"
+    #
+    # [+:layout+]
+    #   The layout template to render. Can also be +false+ or +true+ to disable
+    #   or (re)enable the default layout template.
+    #
+    #     render "posts/show", layout: "holiday"
+    #     # => renders app/views/posts/show.html.erb with the app/views/layouts/holiday.html.erb layout
+    #
+    #     render "posts/show", layout: false
+    #     # => renders app/views/posts/show.html.erb with no layout
+    #
+    #     render inline: "<h1>Hello, World!</h1>", layout: true
+    #     # => renders "<h1>Hello, World!</h1>" with the default layout
+    #
+    # [+:status+]
+    #   The HTTP status code to send with the response. Can be specified as a
+    #   number or as the status name in Symbol form. Defaults to 200.
+    #
+    #     render "posts/new", status: 422
+    #     # => renders app/views/posts/new.html.erb with HTTP status code 422
+    #
+    #     render "posts/new", status: :unprocessable_entity
+    #     # => renders app/views/posts/new.html.erb with HTTP status code 422
+    #
+    #--
     # Check for double render errors and set the content_type after rendering.
-    def render(*args) #:nodoc:
+    def render(*args)
       raise ::AbstractController::DoubleRenderError if response_body
       super
     end
 
-    # Overwrite render_to_string because body can now be set to a Rack body.
+    # Similar to #render, but only returns the rendered template as a string,
+    # instead of setting +self.response_body+.
+    #--
+    # Override render_to_string because body can now be set to a Rack body.
     def render_to_string(*)
       result = super
       if result.respond_to?(:each)
@@ -48,11 +154,17 @@ module ActionController
       end
     end
 
-    def render_to_body(options = {})
+    def render_to_body(options = {}) # :nodoc:
       super || _render_in_priorities(options) || " "
     end
 
     private
+      # Before processing, set the request formats in current controller formats.
+      def process_action(*) # :nodoc:
+        self.formats = request.formats.filter_map(&:ref)
+        super
+      end
+
       def _process_variant(options)
         if defined?(request) && !request.nil? && request.variant.present?
           options[:variant] = request.variant
@@ -83,13 +195,6 @@ module ActionController
         end
       end
 
-      # Normalize arguments by catching blocks and setting them on :update.
-      def _normalize_args(action = nil, options = {}, &blk)
-        options = super
-        options[:update] = blk if block_given?
-        options
-      end
-
       # Normalize both text and status options.
       def _normalize_options(options)
         _normalize_text(options)