Render collections

CHANGELOG.md

@@ -1,5 +1,11 @@
 # master
 
+# v2.1.0
+
+* Support rendering collection (e.g., `render(MyComponent.all(@items))`).
+
+    *Tim Clem, Joel Hawksley*
+
 # v2.0.0
 
 * Move to `ViewComponent` namespace, removing all references to `ActionView`.

README.md

@@ -446,15 +446,10 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/github
 |@mellowfish|@horacio|@dukex|@dark-panda|@smashwilson|
 |Spring Hill, TN|Buenos Aires|São Paulo||Gambrills, MD|
 
-|<img src="https://avatars.githubusercontent.com/blakewilliams?s=256" alt="blakewilliams" width="128" />|
-|:---:|
-|@blakewilliams|
-|Boston, MA|
-
-|<img src="https://avatars.githubusercontent.com/seanpdoyle?s=256" alt="seanpdoyle" width="128" />|
-|:---:|
-|@seanpdoyle|
-|New York, NY|
+|<img src="https://avatars.githubusercontent.com/blakewilliams?s=256" alt="blakewilliams" width="128" />|<img src="https://avatars.githubusercontent.com/seanpdoyle?s=256" alt="seanpdoyle" width="128" />|<img src="https://avatars.githubusercontent.com/tclem?s=256" alt="tclem" width="128" />|
+|:---:|:---:|:---:|
+|@blakewilliams|@seanpdoyle|@tclem|
+|Boston, MA|New York, NY|San Francisco, CA|
 
 ## License
 

lib/view_component/base.rb

@@ -2,6 +2,7 @@
 
 require "action_view"
 require "active_support/configurable"
+require "view_component/collection"
 require "view_component/previewable"
 
 module ViewComponent
@@ -14,6 +15,11 @@ class Base < ActionView::Base
     class_attribute :content_areas, default: []
     self.content_areas = [] # default doesn't work until Rails 5.2
 
+    # Render a component collection.
+    def self.with_collection(*args)
+      Collection.new(self, *args)
+    end
+
     # Entrypoint for rendering components.
     #
     # view_context: ActionView context from calling view
@@ -213,6 +219,15 @@ def with_content_areas(*areas)
         self.content_areas = areas
       end
 
+      # Support overriding this component's collection parameter name
+      def with_collection_parameter(param)
+        @with_collection_parameter = param
+      end
+
+      def collection_parameter_name
+        (@with_collection_parameter || name.demodulize.underscore.chomp("_component")).to_sym
+      end
+
       private
 
       def matching_views_in_source_location

lib/view_component/collection.rb

@@ -0,0 +1,30 @@
+
+# frozen_string_literal: true
+
+module ViewComponent
+  class Collection
+    def render_in(view_context, &block)
+      as = @component.collection_parameter_name
+
+      @collection.map do |item|
+        @component.new(@options.merge(as => item)).render_in(view_context, &block)
+      end.join.html_safe
+    end
+
+    private
+
+    def initialize(component, object, **options)
+      @component = component
+      @collection = collection_variable(object || [])
+      @options = options
+    end
+
+    def collection_variable(object)
+      if object.respond_to?(:to_ary)
+        object.to_ary
+      else
+        raise ArgumentError.new("The value of the argument isn't a valid collection. Make sure it responds to to_ary: #{object.inspect}")
+      end
+    end
+  end
+end

test/app/components/product_component.html.erb

@@ -0,0 +1,7 @@
+<li>
+  <h1>Product</h1>
+  <h2><%= @product.name %></h2>
+  <p>
+    <%= @notice %>
+  </p>
+</li>

test/app/components/product_component.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+class ProductComponent < ViewComponent::Base
+  def initialize(product:, notice:)
+    @product = product
+    @notice = notice
+  end
+end

test/app/components/product_coupon_component.html.erb

@@ -0,0 +1 @@
+<h3><%= @item.percent_off %>%</h3>

test/app/components/product_coupon_component.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class ProductCouponComponent < ViewComponent::Base
+  with_collection_parameter :item
+
+  def initialize(item:)
+    @item = item
+  end
+end

test/app/controllers/integration_examples_controller.rb

@@ -14,4 +14,8 @@ def controller_inline
   def controller_inline_baseline
     render("integration_examples/_controller_inline", locals: { message: "bar" })
   end
+
+  def products
+    @products = [OpenStruct.new(name: "Radio clock"), OpenStruct.new(name: "Mints")]
+  end
 end

test/app/views/integration_examples/products.html.erb

@@ -0,0 +1,4 @@
+<h1>Products for sale</h1>
+<ul>
+  <%= render(ProductComponent.with_collection(@products, notice: "Today only")) %>
+</ul>

test/config/routes.rb

@@ -6,6 +6,7 @@
   get :partial, to: "integration_examples#partial"
   get :content, to: "integration_examples#content"
   get :variants, to: "integration_examples#variants"
+  get :products, to: "integration_examples#products"
   get :cached, to: "integration_examples#cached"
   get :render_check, to: "integration_examples#render_check"
   get :controller_inline, to: "integration_examples#controller_inline"

test/view_component/integration_test.rb

@@ -175,4 +175,14 @@ class IntegrationTest < ActionDispatch::IntegrationTest
 
     assert_select("div", "hello,world!")
   end
+
+  test "renders collections" do
+    get "/products"
+
+    assert_select("h1", text: "Products for sale")
+    assert_select("h1", text: "Product", count: 2)
+    assert_select("h2", text: "Radio clock")
+    assert_select("h2", text: "Mints")
+    assert_select("p", text: "Today only", count: 2)
+  end
 end

test/view_component/view_component_test.rb

@@ -99,7 +99,7 @@ def test_renders_content_for_template
   end
 
   def test_renders_content_areas_template_with_initialize_arguments
-    render_inline(ContentAreasComponent.new(title: "Hi!", footer: "Bye!")) do |component|
+    render_inline(ContentAreasComponent.new(title: "Radio clock!", footer: "Bye!")) do |component|
       component.with(:body) { "Have a nice day." }
     end
   end
@@ -129,11 +129,11 @@ def test_renders_content_areas_template_with_block
   def test_renders_content_areas_template_replaces_content
     render_inline(ContentAreasComponent.new(footer: "Bye!")) do |component|
       component.with(:title) { "Hello!" }
-      component.with(:title, "Hi!")
+      component.with(:title, "Radio clock!")
       component.with(:body) { "Have a nice day." }
     end
 
-    assert_selector(".title", text: "Hi!")
+    assert_selector(".title", text: "Radio clock!")
     assert_selector(".body", text: "Have a nice day.")
     assert_selector(".footer", text: "Bye!")
   end
@@ -386,6 +386,61 @@ def test_backtrace_returns_correct_file_and_line_number
     assert_match %r[app/components/exception_in_template_component\.html\.erb:2], error.backtrace[0]
   end
 
+  # Rendering collections
+
+  def test_render_collection
+    @products = [OpenStruct.new(name: "Radio clock"), OpenStruct.new(name: "Mints")]
+    render_inline(ProductComponent.with_collection(@products, notice: "On sale"))
+
+    assert_selector("h1", text: "Product", count: 2)
+    assert_selector("h2", text: "Radio clock")
+    assert_selector("h2", text: "Mints")
+    assert_selector("p", text: "On sale", count: 2)
+  end
+
+  def test_render_collection_custom_collection_parameter_name
+    @coupons = [OpenStruct.new(percent_off: 20), OpenStruct.new(percent_off: 50)]
+    render_inline(ProductCouponComponent.with_collection(@coupons))
+
+    assert_selector("h3", text: "20%")
+    assert_selector("h3", text: "50%")
+  end
+
+  def test_render_collection_nil_and_empty_collection
+    [nil, []].each do |collection|
+      render_inline(ProductComponent.with_collection(collection, notice: "On sale"))
+
+      assert_no_text("Products")
+    end
+  end
+
+  def test_render_collection_missing_collection_object
+    exception = assert_raises ArgumentError do
+      render_inline(ProductComponent.with_collection(notice: "On sale"))
+    end
+
+    assert_equal exception.message, "The value of the argument isn't a valid collection. Make sure it responds to to_ary: {:notice=>\"On sale\"}"
+  end
+
+  def test_render_collection_missing_arg
+    @products = [OpenStruct.new(name: "Radio clock"), OpenStruct.new(name: "Mints")]
+    exception = assert_raises ArgumentError do
+      render_inline(ProductComponent.with_collection(@products))
+    end
+
+    assert_match /missing keyword/, exception.message
+    assert_match /notice/, exception.message
+  end
+
+  def test_render_single_item_from_collection
+    @product = OpenStruct.new(name: "Mints")
+    render_inline(ProductComponent.new(product: @product, notice: "On sale"))
+
+    assert_selector("h1", text: "Product", count: 1)
+    assert_selector("h2", text: "Mints")
+    assert_selector("p", text: "On sale", count: 1)
+  end
+
   private
 
   def modify_file(file, content)