1 files changed, 67 insertions, 28 deletions
diff --git a/actionpack/lib/action_view/render/rendering.rb b/actionpack/lib/action_view/render/rendering.rb
index 5320245173..baa5d2c3fd 100644
--- a/actionpack/lib/action_view/render/rendering.rb
+++ b/actionpack/lib/action_view/render/rendering.rb
@@ -10,6 +10,7 @@ module ActionView
     # * <tt>:file</tt> - Renders an explicit template file (this used to be the old default), add :locals to pass in those.
     # * <tt>:inline</tt> - Renders an inline template similar to how it's done in the controller.
     # * <tt>:text</tt> - Renders the text passed in out.
+    # * <tt>:once</tt> - Accepts a string or an array of strings and Rails will ensure they each of them are rendered just once.
     #
     # If no options hash is passed or :update specified, the default is to render a partial and use the second parameter
     # as the locals hash.
@@ -20,10 +21,10 @@ module ActionView
           _render_partial(options.merge(:partial => options[:layout]), &block)
         elsif options.key?(:partial)
           _render_partial(options)
+        elsif options.key?(:once)
+          _render_once(options)
         else
-          template = _determine_template(options)
-          lookup_context.freeze_formats(template.formats, true)
-          _render_template(template, options[:layout], options)
+          _render_template(options)
         end
       when :update
         update_page(&block)
@@ -32,36 +33,74 @@ module ActionView
       end
     end
 
-    # Determine the template to be rendered using the given options.
-    def _determine_template(options) #:nodoc:
-      if options.key?(:inline)
-        handler = Template.handler_class_for_extension(options[:type] || "erb")
-        Template.new(options[:inline], "inline template", handler, {})
-      elsif options.key?(:text)
-        Template::Text.new(options[:text], formats.try(:first))
-      elsif options.key?(:file)
-        with_fallbacks { find_template(options[:file], options[:prefix]) }
-      elsif options.key?(:template)
-        options[:template].respond_to?(:render) ?
-          options[:template] : find_template(options[:template], options[:prefix])
+    # 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
+    # <tt>yield :some_name</tt>, the block, by default, returns <tt>content_for(:some_name)</tt>.
+    # If the user calls simply +yield+, the default block returns <tt>content_for(:layout)</tt>.
+    #
+    # 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 <tt>content_for(:layout)</tt>,
+    # this method returns the block that was passed in to <tt>render :layout</tt>, 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 <tt>render :layout</tt>,
+    # 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 name.is_a?(Symbol)
+        @_content_for[name].html_safe
+      elsif block
+        capture(*args, &block)
+      else
+        @_content_for[:layout].html_safe
       end
     end
 
-    # Renders the given template. An string representing the layout can be
-    # supplied as well.
-    def _render_template(template, layout = nil, options = {}) #:nodoc:
-      locals = options[:locals] || {}
-      layout = find_layout(layout) if layout
-
-      ActiveSupport::Notifications.instrument("render_template.action_view",
-        :identifier => template.identifier, :layout => layout.try(:virtual_path)) do
+    def _render_once(options) #:nodoc:
+      _template_renderer.render_once(options)
+    end
 
-        content = template.render(self, locals) { |*name| _layout_for(*name) }
-        @_content_for[:layout] = content if layout
+    def _render_template(options) #:nodoc:
+      _template_renderer.render(options)
+    end
 
-        content = _render_layout(layout, locals) if layout
-        content
-      end
+    def _template_renderer #:nodoc:
+      @_template_renderer ||= TemplateRenderer.new(self)
     end
   end
 end