omg-actionview 8.0.0.alpha1

data/lib/action_view/renderer/collection_renderer.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require "action_view/renderer/partial_renderer"
+
+module ActionView
+  class PartialIteration
+    # The number of iterations that will be done by the partial.
+    attr_reader :size
+
+    # The current iteration of the partial.
+    attr_reader :index
+
+    def initialize(size)
+      @size  = size
+      @index = 0
+    end
+
+    # Check if this is the first iteration of the partial.
+    def first?
+      index == 0
+    end
+
+    # Check if this is the last iteration of the partial.
+    def last?
+      index == size - 1
+    end
+
+    def iterate! # :nodoc:
+      @index += 1
+    end
+  end
+
+  class CollectionRenderer < PartialRenderer # :nodoc:
+    include ObjectRendering
+
+    class CollectionIterator # :nodoc:
+      include Enumerable
+
+      def initialize(collection)
+        @collection = collection
+      end
+
+      def each(&blk)
+        @collection.each(&blk)
+      end
+
+      def size
+        @collection.size
+      end
+
+      def length
+        @collection.respond_to?(:length) ? @collection.length : size
+      end
+
+      def preload!
+        # no-op
+      end
+    end
+
+    class SameCollectionIterator < CollectionIterator # :nodoc:
+      def initialize(collection, path, variables)
+        super(collection)
+        @path      = path
+        @variables = variables
+      end
+
+      def from_collection(collection)
+        self.class.new(collection, @path, @variables)
+      end
+
+      def each_with_info
+        return enum_for(:each_with_info) unless block_given?
+        variables = [@path] + @variables
+        @collection.each { |o| yield(o, variables) }
+      end
+    end
+
+    class PreloadCollectionIterator < SameCollectionIterator # :nodoc:
+      def initialize(collection, path, variables, relation)
+        super(collection, path, variables)
+        relation.skip_preloading! unless relation.loaded?
+        @relation = relation
+      end
+
+      def from_collection(collection)
+        self.class.new(collection, @path, @variables, @relation)
+      end
+
+      def each_with_info
+        return super unless block_given?
+        preload!
+        super
+      end
+
+      def preload!
+        @relation.preload_associations(@collection)
+      end
+    end
+
+    class MixedCollectionIterator < CollectionIterator # :nodoc:
+      def initialize(collection, paths)
+        super(collection)
+        @paths = paths
+      end
+
+      def each_with_info
+        return enum_for(:each_with_info) unless block_given?
+        @collection.each_with_index { |o, i| yield(o, @paths[i]) }
+      end
+    end
+
+    def render_collection_with_partial(collection, partial, context, block)
+      iter_vars  = retrieve_variable(partial)
+
+      collection = if collection.respond_to?(:preload_associations)
+        PreloadCollectionIterator.new(collection, partial, iter_vars, collection)
+      else
+        SameCollectionIterator.new(collection, partial, iter_vars)
+      end
+
+      template = find_template(partial, @locals.keys + iter_vars)
+
+      layout = if !block && (layout = @options[:layout])
+        find_template(layout.to_s, @locals.keys + iter_vars)
+      end
+
+      render_collection(collection, context, partial, template, layout, block)
+    end
+
+    def render_collection_derive_partial(collection, context, block)
+      paths = collection.map { |o| partial_path(o, context) }
+
+      if paths.uniq.length == 1
+        # Homogeneous
+        render_collection_with_partial(collection, paths.first, context, block)
+      else
+        if @options[:cached]
+          raise NotImplementedError, "render caching requires a template. Please specify a partial when rendering"
+        end
+
+        paths.map! { |path| retrieve_variable(path).unshift(path) }
+        collection = MixedCollectionIterator.new(collection, paths)
+        render_collection(collection, context, nil, nil, nil, block)
+      end
+    end
+
+    private
+      def retrieve_variable(path)
+        variable = local_variable(path)
+        [variable, :"#{variable}_counter", :"#{variable}_iteration"]
+      end
+
+      def render_collection(collection, view, path, template, layout, block)
+        identifier = (template && template.identifier) || path
+        ActiveSupport::Notifications.instrument(
+          "render_collection.action_view",
+          identifier: identifier,
+          layout: layout && layout.virtual_path,
+          count: collection.length
+        ) do |payload|
+          spacer = if @options.key?(:spacer_template)
+            spacer_template = find_template(@options[:spacer_template], @locals.keys)
+            build_rendered_template(spacer_template.render(view, @locals), spacer_template)
+          else
+            RenderedTemplate::EMPTY_SPACER
+          end
+
+          collection_body = if template
+            cache_collection_render(payload, view, template, collection) do |filtered_collection|
+              collection_with_template(view, template, layout, filtered_collection)
+            end
+          else
+            collection_with_template(view, nil, layout, collection)
+          end
+
+          return RenderedCollection.empty(@lookup_context.formats.first) if collection_body.empty?
+
+          build_rendered_collection(collection_body, spacer)
+        end
+      end
+
+      def collection_with_template(view, template, layout, collection)
+        locals = @locals
+        cache = {}
+
+        partial_iteration = PartialIteration.new(collection.size)
+
+        collection.each_with_info.map do |object, (path, as, counter, iteration)|
+          index = partial_iteration.index
+
+          locals[as]        = object
+          locals[counter]   = index
+          locals[iteration] = partial_iteration
+
+          _template = (cache[path] ||= (template || find_template(path, @locals.keys + [as, counter, iteration])))
+
+          content = _template.render(view, locals, implicit_locals: [counter, iteration])
+          content = layout.render(view, locals) { content } if layout
+          partial_iteration.iterate!
+          build_rendered_template(content, _template)
+        end
+      end
+  end
+end

data/lib/action_view/renderer/object_renderer.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module ActionView
+  class ObjectRenderer < PartialRenderer # :nodoc:
+    include ObjectRendering
+
+    def initialize(lookup_context, options)
+      super
+      @object     = nil
+      @local_name = nil
+    end
+
+    def render_object_with_partial(object, partial, context, block)
+      @object     = object
+      @local_name = local_variable(partial)
+      render(partial, context, block)
+    end
+
+    def render_object_derive_partial(object, context, block)
+      path = partial_path(object, context)
+      render_object_with_partial(object, path, context, block)
+    end
+
+    private
+      def template_keys(path)
+        super + [@local_name]
+      end
+
+      def render_partial_template(view, locals, template, layout, block)
+        locals[@local_name || template.variable] = @object
+        super(view, locals, template, layout, block)
+      end
+  end
+end

data/lib/action_view/renderer/partial_renderer/collection_caching.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/enumerable"
+
+module ActionView
+  module CollectionCaching # :nodoc:
+    extend ActiveSupport::Concern
+
+    included do
+      # Fallback cache store if Action View is used without Rails.
+      # Otherwise overridden in Railtie to use Rails.cache.
+      mattr_accessor :collection_cache, default: ActiveSupport::Cache::MemoryStore.new
+    end
+
+    private
+      def will_cache?(options, view)
+        options[:cached] && view.controller.respond_to?(:perform_caching) && view.controller.perform_caching
+      end
+
+      def cache_collection_render(instrumentation_payload, view, template, collection)
+        return yield(collection) unless will_cache?(@options, view)
+
+        collection_iterator = collection
+
+        # Result is a hash with the key represents the
+        # key used for cache lookup and the value is the item
+        # on which the partial is being rendered
+        keyed_collection, ordered_keys = collection_by_cache_keys(view, template, collection)
+
+        # Pull all partials from cache
+        # Result is a hash, key matches the entry in
+        # `keyed_collection` where the cache was retrieved and the
+        # value is the value that was present in the cache
+        cached_partials = collection_cache.read_multi(*keyed_collection.keys)
+        instrumentation_payload[:cache_hits] = cached_partials.size
+
+        # Extract the items for the keys that are not found
+        collection = keyed_collection.reject { |key, _| cached_partials.key?(key) }.values
+
+        rendered_partials = collection.empty? ? [] : yield(collection_iterator.from_collection(collection))
+
+        index = 0
+        keyed_partials = fetch_or_cache_partial(cached_partials, template, order_by: keyed_collection.each_key) do
+          # This block is called once
+          # for every cache miss while preserving order.
+          rendered_partials[index].tap { index += 1 }
+        end
+
+        ordered_keys.map do |key|
+          keyed_partials[key]
+        end
+      end
+
+      def callable_cache_key?
+        @options[:cached].respond_to?(:call)
+      end
+
+      def collection_by_cache_keys(view, template, collection)
+        seed = callable_cache_key? ? @options[:cached] : ->(i) { i }
+
+        digest_path = view.digest_path_from_template(template)
+        collection.preload! if callable_cache_key?
+
+        collection.each_with_object([{}, []]) do |item, (hash, ordered_keys)|
+          key = expanded_cache_key(seed.call(item), view, template, digest_path)
+          ordered_keys << key
+          hash[key] = item
+        end
+      end
+
+      def expanded_cache_key(key, view, template, digest_path)
+        key = view.combined_fragment_cache_key(view.cache_fragment_name(key, digest_path: digest_path))
+        key.frozen? ? key.dup : key # #read_multi & #write may require mutability, Dalli 2.6.0.
+      end
+
+      # `order_by` is an enumerable object containing keys of the cache,
+      # all keys are  passed in whether found already or not.
+      #
+      # `cached_partials` is a hash. If the value exists
+      # it represents the rendered partial from the cache
+      # otherwise `Hash#fetch` will take the value of its block.
+      #
+      # This method expects a block that will return the rendered
+      # partial. An example is to render all results
+      # for each element that was not found in the cache and store it as an array.
+      # Order it so that the first empty cache element in `cached_partials`
+      # corresponds to the first element in `rendered_partials`.
+      #
+      # If the partial is not already cached it will also be
+      # written back to the underlying cache store.
+      def fetch_or_cache_partial(cached_partials, template, order_by:)
+        entries_to_write = {}
+
+        keyed_partials = order_by.index_with do |cache_key|
+          if content = cached_partials[cache_key]
+            build_rendered_template(content, template)
+          else
+            rendered_partial = yield
+            body = rendered_partial.body
+
+            # We want to cache buffers as raw strings. This both improve performance and
+            # avoid creating forward compatibility issues with the internal representation
+            # of these two types.
+            if body.is_a?(ActionView::OutputBuffer) || body.is_a?(ActiveSupport::SafeBuffer)
+              body = body.to_str
+            end
+
+            entries_to_write[cache_key] = body
+            rendered_partial
+          end
+        end
+
+        unless entries_to_write.empty?
+          collection_cache.write_multi(entries_to_write)
+        end
+
+        keyed_partials
+      end
+  end
+end

data/lib/action_view/renderer/partial_renderer.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+require "action_view/renderer/partial_renderer/collection_caching"
+
+module ActionView
+  # = Action View Partials
+  #
+  # There's also a convenience method for rendering sub templates within the current controller that depends on a
+  # single object (we call this kind of sub templates for partials). It relies on the fact that partials should
+  # follow the naming convention of being prefixed with an underscore -- as to separate them from regular
+  # templates that could be rendered on their own.
+  #
+  # In a template for Advertiser#account:
+  #
+  #  <%= render partial: "account" %>
+  #
+  # This would render "advertiser/_account.html.erb".
+  #
+  # In another template for Advertiser#buy, we could have:
+  #
+  #   <%= render partial: "account", locals: { account: @buyer } %>
+  #
+  #   <% @advertisements.each do |ad| %>
+  #     <%= render partial: "ad", locals: { ad: ad } %>
+  #   <% end %>
+  #
+  # This would first render <tt>advertiser/_account.html.erb</tt> with <tt>@buyer</tt> passed in as the local variable +account+, then
+  # render <tt>advertiser/_ad.html.erb</tt> and pass the local variable +ad+ to the template for display.
+  #
+  # == The +:as+ and +:object+ options
+  #
+  # By default ActionView::PartialRenderer doesn't have any local variables.
+  # The <tt>:object</tt> option can be used to pass an object to the partial. For instance:
+  #
+  #   <%= render partial: "account", object: @buyer %>
+  #
+  # would provide the <tt>@buyer</tt> object to the partial, available under the local variable +account+ and is
+  # equivalent to:
+  #
+  #   <%= render partial: "account", locals: { account: @buyer } %>
+  #
+  # With the <tt>:as</tt> option we can specify a different name for said local variable. For example, if we
+  # wanted it to be +user+ instead of +account+ we'd do:
+  #
+  #   <%= render partial: "account", object: @buyer, as: 'user' %>
+  #
+  # This is equivalent to
+  #
+  #   <%= render partial: "account", locals: { user: @buyer } %>
+  #
+  # == \Rendering a collection of partials
+  #
+  # The example of partial use describes a familiar pattern where a template needs to iterate over an array and
+  # render a sub template for each of the elements. This pattern has been implemented as a single method that
+  # accepts an array and renders a partial by the same name as the elements contained within. So the three-lined
+  # example in "Using partials" can be rewritten with a single line:
+  #
+  #   <%= render partial: "ad", collection: @advertisements %>
+  #
+  # This will render <tt>advertiser/_ad.html.erb</tt> and pass the local variable +ad+ to the template for display. An
+  # iteration object will automatically be made available to the template with a name of the form
+  # +partial_name_iteration+. The iteration object has knowledge about which index the current object has in
+  # the collection and the total size of the collection. The iteration object also has two convenience methods,
+  # +first?+ and +last?+. In the case of the example above, the template would be fed +ad_iteration+.
+  # For backwards compatibility the +partial_name_counter+ is still present and is mapped to the iteration's
+  # +index+ method.
+  #
+  # The <tt>:as</tt> option may be used when rendering partials.
+  #
+  # You can specify a partial to be rendered between elements via the <tt>:spacer_template</tt> option.
+  # The following example will render <tt>advertiser/_ad_divider.html.erb</tt> between each ad partial:
+  #
+  #   <%= render partial: "ad", collection: @advertisements, spacer_template: "ad_divider" %>
+  #
+  # If the given <tt>:collection</tt> is +nil+ or empty, <tt>render</tt> will return +nil+. This will allow you
+  # to specify a text which will be displayed instead by using this form:
+  #
+  #   <%= render(partial: "ad", collection: @advertisements) || "There's no ad to be displayed" %>
+  #
+  # == \Rendering shared partials
+  #
+  # Two controllers can share a set of partials and render them like this:
+  #
+  #   <%= render partial: "advertisement/ad", locals: { ad: @advertisement } %>
+  #
+  # This will render the partial <tt>advertisement/_ad.html.erb</tt> regardless of which controller this is being called from.
+  #
+  # == \Rendering objects that respond to +to_partial_path+
+  #
+  # Instead of explicitly naming the location of a partial, you can also let PartialRenderer do the work
+  # and pick the proper path by checking +to_partial_path+ method.
+  #
+  #  # @account.to_partial_path returns 'accounts/account', so it can be used to replace:
+  #  # <%= render partial: "accounts/account", locals: { account: @account} %>
+  #  <%= render partial: @account %>
+  #
+  #  # @posts is an array of Post instances, so every post record returns 'posts/post' on +to_partial_path+,
+  #  # that's why we can replace:
+  #  # <%= render partial: "posts/post", collection: @posts %>
+  #  <%= render partial: @posts %>
+  #
+  # == \Rendering the default case
+  #
+  # If you're not going to be using any of the options like collections or layouts, you can also use the short-hand
+  # defaults of render to render partials. Examples:
+  #
+  #  # Instead of <%= render partial: "account" %>
+  #  <%= render "account" %>
+  #
+  #  # Instead of <%= render partial: "account", locals: { account: @buyer } %>
+  #  <%= render "account", account: @buyer %>
+  #
+  #  # @account.to_partial_path returns 'accounts/account', so it can be used to replace:
+  #  # <%= render partial: "accounts/account", locals: { account: @account} %>
+  #  <%= render @account %>
+  #
+  #  # @posts is an array of Post instances, so every post record returns 'posts/post' on +to_partial_path+,
+  #  # that's why we can replace:
+  #  # <%= render partial: "posts/post", collection: @posts %>
+  #  <%= render @posts %>
+  #
+  # == \Rendering partials with layouts
+  #
+  # Partials can have their own layouts applied to them. These layouts are different than the ones that are
+  # specified globally for the entire action, but they work in a similar fashion. Imagine a list with two types
+  # of users:
+  #
+  #   <%# app/views/users/index.html.erb %>
+  #   Here's the administrator:
+  #   <%= render partial: "user", layout: "administrator", locals: { user: administrator } %>
+  #
+  #   Here's the editor:
+  #   <%= render partial: "user", layout: "editor", locals: { user: editor } %>
+  #
+  #   <%# app/views/users/_user.html.erb %>
+  #   Name: <%= user.name %>
+  #
+  #   <%# app/views/users/_administrator.html.erb %>
+  #   <div id="administrator">
+  #     Budget: $<%= user.budget %>
+  #     <%= yield %>
+  #   </div>
+  #
+  #   <%# app/views/users/_editor.html.erb %>
+  #   <div id="editor">
+  #     Deadline: <%= user.deadline %>
+  #     <%= yield %>
+  #   </div>
+  #
+  # ...this will return:
+  #
+  #   Here's the administrator:
+  #   <div id="administrator">
+  #     Budget: $<%= user.budget %>
+  #     Name: <%= user.name %>
+  #   </div>
+  #
+  #   Here's the editor:
+  #   <div id="editor">
+  #     Deadline: <%= user.deadline %>
+  #     Name: <%= user.name %>
+  #   </div>
+  #
+  # If a collection is given, the layout will be rendered once for each item in
+  # the collection. For example, these two snippets have the same output:
+  #
+  #   <%# app/views/users/_user.html.erb %>
+  #   Name: <%= user.name %>
+  #
+  #   <%# app/views/users/index.html.erb %>
+  #   <%# This does not use layouts %>
+  #   <ul>
+  #     <% users.each do |user| -%>
+  #       <li>
+  #         <%= render partial: "user", locals: { user: user } %>
+  #       </li>
+  #     <% end -%>
+  #   </ul>
+  #
+  #   <%# app/views/users/_li_layout.html.erb %>
+  #   <li>
+  #     <%= yield %>
+  #   </li>
+  #
+  #   <%# app/views/users/index.html.erb %>
+  #   <ul>
+  #     <%= render partial: "user", layout: "li_layout", collection: users %>
+  #   </ul>
+  #
+  # Given two users whose names are Alice and Bob, these snippets return:
+  #
+  #   <ul>
+  #     <li>
+  #       Name: Alice
+  #     </li>
+  #     <li>
+  #       Name: Bob
+  #     </li>
+  #   </ul>
+  #
+  # The current object being rendered, as well as the object_counter, will be
+  # available as local variables inside the layout template under the same names
+  # as available in the partial.
+  #
+  # You can also apply a layout to a block within any template:
+  #
+  #   <%# app/views/users/_chief.html.erb %>
+  #   <%= render(layout: "administrator", locals: { user: chief }) do %>
+  #     Title: <%= chief.title %>
+  #   <% end %>
+  #
+  # ...this will return:
+  #
+  #   <div id="administrator">
+  #     Budget: $<%= user.budget %>
+  #     Title: <%= chief.name %>
+  #   </div>
+  #
+  # As you can see, the <tt>:locals</tt> hash is shared between both the partial and its layout.
+  class PartialRenderer < AbstractRenderer
+    include CollectionCaching
+
+    def initialize(lookup_context, options)
+      super(lookup_context)
+      @options = options
+      @locals  = @options[:locals] || {}
+      @details = extract_details(@options)
+    end
+
+    def render(partial, context, block)
+      template = find_template(partial, template_keys(partial))
+
+      if !block && (layout = @options[:layout])
+        layout = find_template(layout.to_s, template_keys(partial))
+      end
+
+      render_partial_template(context, @locals, template, layout, block)
+    end
+
+    private
+      def template_keys(_)
+        @locals.keys
+      end
+
+      def render_partial_template(view, locals, template, layout, block)
+        ActiveSupport::Notifications.instrument(
+          "render_partial.action_view",
+          identifier: template.identifier,
+          layout: layout && layout.virtual_path,
+          locals: locals
+        ) do |payload|
+          content = template.render(view, locals, add_to_stack: !block) do |*name|
+            view._layout_for(*name, &block)
+          end
+
+          content = layout.render(view, locals) { content } if layout
+          payload[:cache_hit] = view.view_renderer.cache_hits[template.virtual_path]
+          build_rendered_template(content, template)
+        end
+      end
+
+      def find_template(path, locals)
+        prefixes = path.include?(?/) ? [] : @lookup_context.prefixes
+        @lookup_context.find_template(path, prefixes, true, locals, @details)
+      end
+  end
+end