Add support for Props::Options object.

This addresses #56 by adding an options object. For simplicity
and backward compatibility we inherit from Hash. Here's an example
of usage:

```
json.note Props::Options.new
  .partial(“club_notes/notes”, locals: {club_note: @club_note}
  .fragment(“club_note_#{@club_note.id}”)
```

We also retain backward compat with the old syntax here:

```
json.note(
  partial: [
    "club_notes/note",
    fragment: "club_note_#{@club_note.id}",
    locals: {
      club_note: @club_note
    }
  ]
) do
end

```

Author: jho406

lib/props_template.rb

@@ -9,6 +9,7 @@
 require "active_support/core_ext/array"
 require "props_template/searcher"
 require "props_template/handler"
+require "props_template/options"
 require "props_template/version"
 
 require "active_support"
@@ -28,7 +29,7 @@ class << self
       :deferred!,
       :fragments!,
       :disable_deferments!,
-      :set_block_content!,
+      :set_content!,
       :traveled_path!,
       :fragment_context!,
       to: :builder!

lib/props_template/base.rb

@@ -14,7 +14,7 @@ def initialize(encoder = nil)
       @scope = nil
     end
 
-    def set_block_content!(options = {})
+    def set_content!(options = {})
       @scope = nil
       yield
       if @scope.nil?
@@ -26,7 +26,7 @@ def set_block_content!(options = {})
     def handle_set_block(key, options)
       key = format_key(key)
       @stream.push_key(key)
-      set_block_content!(options) do
+      set_content!(options) do
         yield
       end
     end
@@ -64,7 +64,7 @@ def refine_item_options(item, options)
     end
 
     def handle_collection_item(collection, item, index, options)
-      set_block_content!(options) do
+      set_content!(options) do
         yield
       end
     end
@@ -97,13 +97,20 @@ def array!(collection = nil, options = {})
         raise InvalidScopeForArrayError.new("array! expects exclusive use of this block")
       end
 
-      if collection.nil?
-        @child_index = nil
-        yield
-      else
-        handle_collection(collection, options) do |item, index|
-          yield item, index
+      if block_given?
+        if collection.nil?
+          @child_index = nil
+          yield
+        else
+          handle_collection(collection, options) do |item, index|
+            yield item, index
+          end
         end
+      elsif options.is_a?(Props::Options)
+        options.valid_for_set!
+        handle_collection(collection, options) {}
+      else
+        raise ArgumentError.new("array! requires a block when no Props::Options object is given")
       end
 
       @scope = :array
@@ -147,7 +154,7 @@ def child!(options = {})
       child_index += 1
 
       # this changes the scope to nil so child in a child will break
-      set_block_content!(options) do
+      set_content!(options) do
         yield
       end
 

lib/props_template/base_with_extensions.rb

@@ -26,7 +26,7 @@ def traveled_path!
       @traveled_path.join(".")
     end
 
-    def set_block_content!(options = {})
+    def set_content!(options = {})
       return super if !@em.has_extensions(options)
 
       @em.handle(options) do
@@ -51,11 +51,16 @@ def format_key(key)
     end
 
     def set!(key, options = {}, &block)
-      if block
+      if block || options.is_a?(Props::Options)
         options = @em.refine_options(options)
       end
 
-      super
+      if !block && options.is_a?(Props::Options)
+        options.valid_for_set!
+        super {}
+      else
+        super
+      end
     end
 
     def handle_set_block(key, options)

lib/props_template/extension_manager.rb

@@ -53,7 +53,7 @@ def handle(options)
         @fragment.handle(options)
       else
         handle_cache(options) do
-          base.set_block_content! do
+          base.set_content! do
             if options[:partial]
               @fragment.handle(options)
               @partialer.handle(options)

lib/props_template/extensions/partial_renderer.rb

@@ -167,4 +167,3 @@ def refine_options(options, item = nil)
     end
   end
 end
-

lib/props_template/options.rb

@@ -0,0 +1,36 @@
+module Props
+  class Options < Hash
+    def partial(partial_name, opts = {})
+      self[:partial] = [partial_name, opts]
+      self
+    end
+
+    def defer(type, placeholder: {}, **opts)
+      self[:defer] = [type, {placeholder: placeholder}.merge(opts)]
+      self
+    end
+
+    def fragment(fragment)
+      raise "Fragment can't be defined without a partial. Please use `partial` first" if !self[:partial]
+
+      self[:partial][1][:fragment] = fragment
+      self
+    end
+
+    def cache(id_or_block)
+      return unless id_or_block
+
+      self[:cache] = id_or_block
+      self
+    end
+
+    def id_key(key_name)
+      self[:key] = key_name
+      self
+    end
+
+    def valid_for_set!
+      raise "The partial option must be used with an inline `set!`" if !key?(:partial)
+    end
+  end
+end

lib/props_template/searcher.rb

@@ -41,12 +41,12 @@ def found!
       [@found_block, @traveled_path, pass_opts, @fragment_path, fragment_context]
     end
 
-    def set_block_content!(*args)
+    def set_content!(*args)
       yield
     end
 
     def set!(key, options = {}, &block)
-      return if @found_block || !block
+      return if @found_block || !block && !options.is_a?(Props::Options)
 
       if @search_path[@depth] == key.to_s
         @traveled_path.push(key)

spec/extensions/defer_extension_spec.rb

@@ -30,6 +30,29 @@
     })
   end
 
+  it "defers a block from loading using an options object" do
+    json = render(<<~PROPS)
+      json.outer do
+        json.inner(Props::Options.new.defer(:auto)) do
+          json.greeting do
+            json.foo 'hello world'
+          end
+        end
+      end
+
+      json.deferred json.deferred!
+    PROPS
+
+    expect(json).to eql_json({
+      outer: {
+        inner: {}
+      },
+      deferred: [
+        {url: "/some_url?props_at=outer.inner", path: "outer.inner", type: "auto"}
+      ]
+    })
+  end
+
   it "disables deferments" do
     json = render(<<~PROPS)
       json.disable_deferments!
@@ -79,6 +102,28 @@
       ]
     })
   end
+  it "defers a block from loading, and replaces with a custom placeholder from an options object" do
+    json = render(<<~PROPS)
+      json.outer do
+        json.inner(Props::Options.new.defer(:auto, placeholder: [])) do
+          json.greeting do
+            json.foo 'hello world'
+          end
+        end
+      end
+
+      json.deferred json.deferred!
+    PROPS
+
+    expect(json).to eql_json({
+      outer: {
+        inner: []
+      },
+      deferred: [
+        {url: "/some_url?props_at=outer.inner", path: "outer.inner", type: "auto"}
+      ]
+    })
+  end
 
   it "defers a block from loading, and passes success and fail types" do
     json = render(<<~PROPS)
@@ -103,6 +148,29 @@
     })
   end
 
+  it "defers a block from loading, and passes success and fail types using an options object" do
+    json = render(<<~PROPS)
+      json.outer do
+        json.inner(Props::Options.new.defer(:auto, success_action: 'SUCCESS', fail_action: 'FAIL')) do
+          json.greeting do
+            json.foo 'hello world'
+          end
+        end
+      end
+
+      json.deferred json.deferred!
+    PROPS
+
+    expect(json).to eql_json({
+      outer: {
+        inner: {}
+      },
+      deferred: [
+        {url: "/some_url?props_at=outer.inner", path: "outer.inner", type: "auto", successAction: "SUCCESS", failAction: "FAIL"}
+      ]
+    })
+  end
+
   it "defers a block from loading and populates with a manual type" do
     json = render(<<~PROPS)
       json.outer do

spec/extensions/fragments_spec.rb

@@ -30,6 +30,35 @@
     })
   end
 
+  it "renders with a partial and populates fragments using an inline option object" do
+    json = render(<<~PROPS)
+      json.outer do
+        fragment_opts = Props::Options.new
+          .partial('simple')
+          .fragment(:simple)
+
+        json.inner(fragment_opts)
+        json.inner2(fragment_opts)
+      end
+      json.fragments json.fragments!
+    PROPS
+
+    expect(json).to eql_json({
+      outer: {
+        inner: {
+          foo: "bar"
+        },
+        inner2: {
+          foo: "bar"
+        }
+      },
+      fragments: [
+        {id: :simple, path: "outer.inner"},
+        {id: :simple, path: "outer.inner2"}
+      ]
+    })
+  end
+
   it "renders with a partial and populates fragments even when caching" do
     render(<<~PROPS)
       json.outer do
@@ -78,15 +107,15 @@
 
     expect(json).to eql_json({
       outer: {
-        inner: {foo:"bar"}
+        inner: {foo: "bar"}
       },
       fragments: [
         {id: "simple", path: "outer.inner"}
       ],
       deferred: []
     })
   end
-  
+
   it "renders deferment and populates fragments" do
     json = render(<<~PROPS)
       json.outer do
@@ -240,10 +269,10 @@
     expect(json).to eql_json({
       data: [
         {
-          email: "joe@red.com",
+          email: "joe@red.com"
         },
         {
-          email: "foo@red.com",
+          email: "foo@red.com"
         }
       ],
       fragments: [

spec/extensions/key_extension_spec.rb

@@ -32,6 +32,36 @@
     })
   end
 
+  it "renders an array of items with id using :key as the method_name via an options object" do
+    json = render(<<~PROPS)
+      klass = Struct.new(:email, :id)
+
+      users = [
+        klass.new('joe@red.com', 1),
+        klass.new('foo@red.com', 2)
+      ]
+
+      json.data do
+        json.array! users, Props::Options.new.id_key(:id) do |person|
+          json.email person.email
+        end
+      end
+    PROPS
+
+    expect(json).to eql_json({
+      data: [
+        {
+          email: "joe@red.com",
+          id: 1
+        },
+        {
+          email: "foo@red.com",
+          id: 2
+        }
+      ]
+    })
+  end
+
   it "preserves the id option when digging is exact" do
     json = render(<<~PROPS)
       klass = Struct.new(:email, :id)