blocks 3.0.4 → 4.0.0.rc1

data/lib/blocks/builders/hook_definition.rb

@@ -1,5 +1,7 @@
+# frozen_string_literal: true
+
 module Blocks
-  class HookDefinition < OptionsSet
+  class HookDefinition < HashWithRenderStrategy
     BEFORE_ALL = :before_all
     AROUND_ALL = :around_all
     BEFORE = :before
@@ -14,12 +16,25 @@ module Blocks
              AROUND_ALL, AROUND, SURROUND,
              APPEND, AFTER, AFTER_ALL]
 
-    attr_accessor :block_definition, :hook_type
+    attr_accessor :block_definition, :hook_type, :name, :runtime_block, :block_to_render
 
-    def initialize(block_definition, hook_type, *args, &block)
+    def initialize(block_definition, hook_type, options, &block)
       self.block_definition = block_definition
       self.hook_type = hook_type
-      super "#{hook_type} #{block_definition.name} options", *args, &block
+      super &nil
+      reverse_merge! options
+      self.block_to_render = self.delete(:render) || self[RENDER_WITH_PROXY]
+      self.name = "#{block_to_render.to_s + ' block ' if block_to_render}#{hook_type} #{block_definition.name} options"
+      # name = self[:render] || "#{hook_type} #{block_definition.name} options"
+      # super name, *args, &block
+
+      if block
+        if render_strategy
+          self.runtime_block = block
+        else
+          reverse_merge! block: block
+        end
+      end
     end
   end
 end

data/lib/blocks/engine.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'rails/engine'
+require 'rails/version'
+
+module Blocks
+  class Railtie < Rails::Engine
+    if Rails::VERSION::MAJOR >= 4
+      config.eager_load_namespaces << Blocks
+    else
+      config.eager_load_paths += Blocks.autoloads.values
+    end
+  end
+end

data/lib/blocks/helpers/controller_extensions.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'action_controller'
+
+module Blocks
+  module ControllerExtensions
+    def blocks
+      @blocks ||= Blocks.builder_class.new(view_context)
+    end
+  end
+end
+
+ActionController::Base.send :include, Blocks::ControllerExtensions

data/lib/blocks/helpers/haml_capture.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# Complete hack to get around issues with Haml
+#  Haml does some hacking to ActionView's with_output_buffer and
+#  output_buffer. In doing so, they make certain assumptions about
+#  the layout and the view template. (See:
+#  https://github.com/haml/haml/blob/master/lib/haml/helpers/action_view_mods.rb#L11,
+#  and https://github.com/haml/haml/blob/master/lib/haml/helpers.rb#L389)
+#  The Blocks gem doesn't capture
+#  blocks immediately but rather stores them for later capturing.
+#  This can produce an issue if a block that is stored was defined in Haml
+#  but the Layout is in ERB. Haml will think that any blocks it
+#  captures while rendering the layout will be in ERB format. However,
+#  the block would need to be captured in Haml using a Haml buffer.
+#  This workaround accomplishes that.
+module Blocks
+  module HamlCapture
+    def initialize(view, *)
+      super
+      if defined?(::Haml) && !view.instance_variables.include?(:@haml_buffer)
+        class << view
+          include Haml::Helpers
+        end
+        view.init_haml_helpers
+      end
+    end
+
+    def capture(*)
+      old_haml_buffer = view.instance_variable_get(:@haml_buffer)
+      if old_haml_buffer
+        was_active = old_haml_buffer.active?
+        old_haml_buffer.active = false
+      else
+        haml_buffer = Haml::Buffer.new(nil, Haml::Options.new.for_buffer)
+        haml_buffer.active = false
+        view.instance_variable_set(:@haml_buffer, haml_buffer)
+      end
+      super
+    ensure
+      old_haml_buffer.active = was_active if old_haml_buffer
+      view.instance_variable_set(:@haml_buffer, old_haml_buffer)
+    end
+  end
+end

data/lib/blocks/{action_view_extensions → helpers}/view_extensions.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'action_view'
 
 module Blocks
@@ -7,20 +9,24 @@ module Blocks
     end
 
     def render_with_overrides(*args, &block)
-      options = args.extract_options!.with_indifferent_access
+      options = args.extract_options!
       partial = options.delete(:partial) || options.delete(:template) || args.first
       if builder = options.delete(:builder)
         builder.view = self
         # builder = builder.clone
         # TODO: figure out what to do here
       else
-        # TODO: options shouldn't have to be passed both here and to the render_with_overrides call below - need it to be just one place
+        # TODO: options shouldn't have to be passed both here and to the render call below - need it to be just one place
         builder = Blocks.builder_class.new(self, options)
       end
-      builder.render_with_overrides(options.merge(partial: partial), &block)
+      builder.render(options.merge(partial: partial), &block)
     end
-    alias_method :with_template, :render_with_overrides
 
+    # <b>DEPRECATED:</b> Please use <tt>render_with_overrides</tt> instead.
+    def with_template(*args, &block)
+      warn "[DEPRECATION] `with_template` is deprecated.  Please use `render_with_overrides` instead."
+      render_with_overrides(*args, &block)
+    end
   end
 end
 

data/lib/blocks/renderers/adjacent_blocks_renderer.rb

@@ -1,13 +1,15 @@
+# frozen_string_literal: true
+
 module Blocks
-  class AdjacentBlocksRenderer < AbstractRenderer
-    def render(hook, runtime_context)
-      block = block_for(runtime_context.block_name)
-      if block
-        hooks = block.hooks_for hook
+  class AdjacentBlocksRenderer
+    def self.render(hook, runtime_context)
+      hooks = runtime_context.hooks_for hook
+      if hooks.present?
+        output_buffer = runtime_context.output_buffer
         hooks = hooks.reverse if hook.to_s.index("before") == 0 || hook.to_s.index("prepend") == 0
         hooks.each do |hook_definition|
-          hook_runtime_context = runtime_context.extend_to_block_definition(hook_definition)
-          block_renderer.render(hook_runtime_context)
+          hook_runtime_context = runtime_context.extend_from_definition(hook_definition, &hook_definition.runtime_block)
+          output_buffer << BlockWithHooksRenderer.render(hook_runtime_context)
         end
       end
     end

data/lib/blocks/renderers/block_placeholder.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Blocks
   class BlockPlaceholder
     attr_accessor :block_definition

data/lib/blocks/renderers/block_renderer.rb

@@ -1,12 +1,33 @@
+# frozen_string_literal: true
+
 module Blocks
-  class BlockRenderer < AbstractRenderer
-    def render(*args, runtime_context)
+  class BlockRenderer
+    def self.render(runtime_context)
+      output_buffer = runtime_context.output_buffer
       render_item = runtime_context.render_item
+      # TODO: should convert anything that passes a runtime context back to the user to a normal hash
       if render_item.is_a?(String) || render_item.respond_to?(:to_partial_path)
-        output_buffer << partial_renderer.render(render_item, runtime_context)
+        output_buffer << PartialRenderer.render(runtime_context)
+
+        # TODO: should the same approach be utilized for Procs & Methods?
+        #  Can the capture method both invoke a method and pass a block to it?
       elsif render_item.is_a?(Proc)
-        args = args + runtime_context.runtime_args
-        output_buffer << capture(*args, runtime_context, &render_item)
+        # TODO: should the runtime_context be the first argument?
+        args = runtime_context.runtime_args + [runtime_context.to_hash]
+        if runtime_context.runtime_block && runtime_context.runtime_block != render_item
+          args = args.unshift runtime_context.runtime_block
+        end
+        output_buffer << runtime_context.capture(*args, &render_item)
+
+      elsif render_item.is_a?(Method)
+        # TODO: should the runtime_context be the first argument?
+        args = runtime_context.runtime_args + [runtime_context.to_hash]
+        if render_item.arity >= 0
+          args = args[0, render_item.arity]
+        end
+        output_buffer << runtime_context.capture do
+          render_item.call(*args, &runtime_context.runtime_block)
+        end
       end
     end
   end

data/lib/blocks/renderers/block_with_hooks_renderer.rb

@@ -1,35 +1,45 @@
+# frozen_string_literal: true
+
 module Blocks
   # TODO: Make this render order customizable
-  class BlockWithHooksRenderer < AbstractRenderer
-    def render(*args, &default_definition)
-      with_output_buffer do
-        runtime_context = RuntimeContext.new(builder, *args, &default_definition)
-        if !runtime_context.skip_completely
-          adjacent_blocks_renderer.render(HookDefinition::BEFORE_ALL, runtime_context)
-          nesting_blocks_renderer.render(HookDefinition::AROUND_ALL, runtime_context) do
-            wrapper_renderer.render(runtime_context.wrap_all, runtime_context) do
-              collection_renderer.render(runtime_context) do |runtime_context|
-                wrapper_renderer.render(runtime_context.wrap_each, runtime_context) do
-                  nesting_blocks_renderer.render(HookDefinition::AROUND, runtime_context) do
-                    adjacent_blocks_renderer.render(HookDefinition::BEFORE, runtime_context)
+  class BlockWithHooksRenderer
+    def self.render(runtime_context)
+      runtime_context.with_output_buffer do
+        if runtime_context.skip_completely
+          # noop
+        elsif runtime_context.hooks_or_wrappers_present?
+          render_hooks(HookDefinition::BEFORE_ALL, runtime_context)
+          render_hooks(HookDefinition::AROUND_ALL, runtime_context) do
+            WrapperRenderer.render(runtime_context.wrap_all, :wrap_all, runtime_context) do
+              CollectionRenderer.render(runtime_context) do |runtime_context|
+                WrapperRenderer.render(runtime_context.wrap_each, :wrap_each, runtime_context) do
+                  render_hooks(HookDefinition::AROUND, runtime_context) do
+                    render_hooks(HookDefinition::BEFORE, runtime_context)
                     if !runtime_context.skip_content
-                      wrapper_renderer.render(runtime_context.wrap_with, runtime_context) do
-                        nesting_blocks_renderer.render(HookDefinition::SURROUND, runtime_context) do
-                          adjacent_blocks_renderer.render(HookDefinition::PREPEND, runtime_context)
-                          block_renderer.render(runtime_context)
-                          adjacent_blocks_renderer.render(HookDefinition::APPEND, runtime_context)
+                      WrapperRenderer.render(runtime_context.wrap_with, :wrapper, runtime_context) do
+                        render_hooks(HookDefinition::SURROUND, runtime_context) do
+                          render_hooks(HookDefinition::PREPEND, runtime_context)
+                          BlockRenderer.render(runtime_context)
+                          render_hooks(HookDefinition::APPEND, runtime_context)
                         end
                       end
                     end
-                    adjacent_blocks_renderer.render(HookDefinition::AFTER, runtime_context)
+                    render_hooks(HookDefinition::AFTER, runtime_context)
                   end
                 end
               end
             end
           end
-          adjacent_blocks_renderer.render(HookDefinition::AFTER_ALL, runtime_context)
+          render_hooks(HookDefinition::AFTER_ALL, runtime_context)
+        elsif !runtime_context.skip_content
+          BlockRenderer.render(runtime_context)
         end
       end
     end
+
+    def self.render_hooks(hook_type, runtime_context, &block)
+      renderer_class = block ? NestingBlocksRenderer : AdjacentBlocksRenderer
+      renderer_class.render(hook_type, runtime_context, &block)
+    end
   end
 end

data/lib/blocks/renderers/collection_renderer.rb

@@ -1,14 +1,27 @@
+# frozen_string_literal: true
+
 module Blocks
-  class CollectionRenderer < AbstractRenderer
-    def render(runtime_context)
+  class CollectionRenderer
+    def self.render(runtime_context)
       collection = runtime_context.collection
       if collection
-        object_name = runtime_context.as || :object
+        original_collection_item = runtime_context.collection_item
+        original_collection_item_index = runtime_context.collection_item_index
+        original_runtime_args = runtime_context.runtime_args
         collection.each_with_index do |item, index|
-          item_runtime_context = runtime_context.merge(object_name => item, current_index: index)
-          item_runtime_context.runtime_args = [item] + item_runtime_context.runtime_args
-          yield item_runtime_context
+          runtime_context.collection_item = item
+          runtime_context.collection_item_index = index
+
+          if Blocks.collection_item_passed_to_block_as_first_arg
+            runtime_context.runtime_args = runtime_context.runtime_args.try(:clone) || []
+            runtime_context.runtime_args = [item] + Array(runtime_context.runtime_args)
+          end
+
+          yield runtime_context
         end
+        runtime_context.collection_item = original_collection_item
+        runtime_context.collection_item_index = original_collection_item_index
+        runtime_context.runtime_args = original_runtime_args
       else
         yield runtime_context
       end

data/lib/blocks/renderers/nesting_blocks_renderer.rb

@@ -1,25 +1,23 @@
+# frozen_string_literal: true
+
 module Blocks
-  class NestingBlocksRenderer < AbstractRenderer
-    def render(hook, runtime_context)
-      block = block_for(runtime_context.block_name)
-      hooks = block.try(:hooks_for, hook)
+  class NestingBlocksRenderer
+    def self.render(hook, runtime_context)
+      hooks = runtime_context.hooks_for(hook)
       if hooks.present?
-        content_block = Proc.new { with_output_buffer { yield } }
+        content_block = Proc.new { runtime_context.with_output_buffer { yield } }
 
         renderer = hooks.inject(content_block) do |inner_content, hook_definition|
-          hook_runtime_context = runtime_context.extend_to_block_definition(hook_definition)
+          hook_runtime_context = runtime_context.extend_from_definition(hook_definition, &inner_content)
           Proc.new {
-            with_output_buffer do
-              block_renderer.render(inner_content, hook_runtime_context)
-            end
+            BlockWithHooksRenderer.render(hook_runtime_context)
           }
         end
 
-        output_buffer << renderer.call
+        runtime_context.output_buffer << renderer.call
       else
         yield
       end
-
     end
   end
 end

data/lib/blocks/renderers/partial_renderer.rb

@@ -1,21 +1,23 @@
+# frozen_string_literal: true
+
 module Blocks
-  class PartialRenderer < AbstractRenderer
-    def render(partial, options={}, &block)
-      if !options.is_a?(Blocks::RuntimeContext)
-        options = RuntimeContext.new(builder, options).to_hash.with_indifferent_access
-      end
-      overrides_and_provided_content = capture(builder, options, &block) if block_given?
+  class PartialRenderer
+    def self.render(runtime_context)
+      builder = runtime_context.builder
+      view = builder.view
+      partial = runtime_context.render_item
+      partial = partial.to_partial_path if partial.respond_to?(:to_partial_path)
+      runtime_block = runtime_context.runtime_block
+
+      options = runtime_context.to_hash
+      overrides_and_provided_content = builder.capture(builder, options, &runtime_context.runtime_block) if runtime_block
+
       locals = options.merge(
-        (options[:builder_variable] || :builder) => builder,
+        (runtime_context[:builder_variable] || :builder) => builder,
       )
-      locals = if locals.respond_to?(:deep_symbolize_keys)
-        locals.deep_symbolize_keys
-      else
-        locals.symbolize_keys
-      end
-      partial = partial.to_partial_path if partial.respond_to?(:to_partial_path)
       locals[:options] = options
-      view.render(layout: partial, locals: locals) do |*args|
+
+      builder.view.render(layout: partial, locals: locals) do |*args|
         if overrides_and_provided_content
           overrides_and_provided_content.to_str.gsub(/PLACEHOLDER_FOR_([\w]+)/) do |s|
             builder.render $1, *args

data/lib/blocks/renderers/renderer.rb

@@ -1,38 +1,23 @@
+# frozen_string_literal: true
+
 module Blocks
   class Renderer
-    attr_accessor :builder
-    delegate :render, to: :block_with_hooks_renderer
-
-    def initialize(builder)
-      self.builder = builder
-    end
-
-    # TODO: this needs to be handled by a new renderer
-    def render_with_overrides(*args, &block)
+    def self.render(builder, *args, &default_definition)
       options = args.extract_options!
-      name = args.first
-      if name.is_a?(Symbol) || name.is_a?(String)
-        # TODO: block needs to be handled differently so as to provide overrides
-        block_with_hooks_renderer.render(*args, options, &block)
-      elsif options[:partial]
-        partial_renderer.render(options.delete(:partial), options, &block)
+      runtime_context = if !options.is_a?(RuntimeContext)
+        RuntimeContext.build(builder, *args, options, &default_definition)
       else
-        # TODO: handle other possible rendering methods such as a custom renderer
+        options
       end
+
+      BlockWithHooksRenderer.render(runtime_context)
     end
 
     # TODO: this needs to be handled by a new renderer
     #  TODO: also get rid of BlockPlaceholder
-    def deferred_render(*args, &block)
+    def self.deferred_render(builder, *args, &block)
       block_definition = builder.define(*args, &block)
       Blocks::BlockPlaceholder.new(block_definition)
     end
-
-    AbstractRenderer::RENDERERS.each do |klass|
-      name = klass.to_s.demodulize.underscore.to_sym
-      define_method name do
-        klass.new(self)
-      end
-    end
   end
 end

data/lib/blocks/renderers/runtime_context.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Blocks
   class RuntimeContext < HashWithRenderStrategy
     CONTROL_VARIABLES = {
@@ -8,205 +10,225 @@ module Blocks
       as: []
     }
 
-    attr_accessor(*CONTROL_VARIABLES.keys)
-    attr_accessor :block_name,
-                  :runtime_block,
-                  :builder,
-                  :render_item,
-                  :runtime_args,
-                  :render_options_set,
-                  :block_options_set,
-                  :proxy_options_set,
-                  :parent_runtime_context
-
-    delegate :skip_content, :skip_completely, to: :block_options_set, allow_nil: true
-
-    delegate :block_definitions, :block_defined?, to: :builder
-
-    delegate :runtime_options,
-             :standard_options,
-             :default_options,
-             :options_set,
-             prefix: :builder,
-             to: :builder
-
-    def initialize(builder, *runtime_args, &runtime_block)
-      super(&nil)
-
-      self.builder = builder
-      self.runtime_block = runtime_block
-      self.proxy_options_set = OptionsSet.new("Proxy Options Set")
+    PROTECTED_OPTIONS = RENDERING_STRATEGIES +
+      (CONTROL_VARIABLES.keys + CONTROL_VARIABLES.values).flatten.compact
+
+    attr_accessor *CONTROL_VARIABLES.keys,
+      :block_name,
+      :runtime_block,
+      :builder,
+      :render_item,
+      :runtime_args,
+      :merged_block_options,
+      :collection_item,
+      :collection_item_index,
+      :skip_completely,
+      :skip_content,
+      :hooks
+
+    delegate :block_defined?,
+      :block_for,
+      :output_buffer,
+      :with_output_buffer,
+      :capture,
+      to: :builder
+
+    def self.build(builder, *runtime_args, &runtime_block)
+      new.tap do |runtime_context|
+        runtime_context.builder = builder
+        runtime_context.runtime_block = runtime_block
+        runtime_context.compute(*runtime_args)
+      end
+    end
 
+    # TODO: change the method signature of this method to def compute(block_identifier, options={}, &runtime_block)
+    #  Get rid of most uses of the *
+    def compute(*runtime_args)
       render_options = runtime_args.extract_options!
-      block_name = runtime_args.shift
-
-      convert_render_options(render_options)
-      identify_block(block_name)
-
+      build_block_context(runtime_args.shift, render_options)
+      # TODO: runtime args should be specified as a reserved keyword in the hash
       self.runtime_args = runtime_args
-      merge_options_and_identify_render_item
       extract_control_options
     end
 
-    # TODO: this method needs to clone without context, i.e. with render_strategy, item, etc
-    def extend_to_block_definition(block_definition)
-      RuntimeContext.new(builder, block_definition, parent_runtime_context: self).tap do |rc|
-        rc.runtime_args = self.runtime_args
-      end
+    def extend_from_definition(definition, options={}, &runtime_block)
+      RuntimeContext.build(
+        builder,
+        definition,
+        # TODO: don't pass runtime args here?
+        *runtime_args,
+        options.merge(parent_runtime_context: self),
+        &runtime_block
+      )
     end
 
     # TODO: this method needs to be rewritten to output a proper hash
-    def to_s
-      description = []
-      if block_name
-        block_name = self.block_name.to_s
-        if block_name.include?(" ")
-          block_name = ":\"#{block_name}\""
-        else
-          block_name = ":#{block_name}"
-        end
-        description << "Block Name: #{block_name}"
-      end
+    # def to_s
+    #   description = []
+    #   if block_name
+    #     block_name = self.block_name.to_s
+    #     if block_name.include?(" ")
+    #       block_name = ":\"#{block_name}\""
+    #     else
+    #       block_name = ":#{block_name}"
+    #     end
+    #     description << "Block Name: #{block_name}"
+    #   end
+    #
+    #   if render_item.is_a?(String)
+    #     description << "Renders with partial \"#{render_item}\""
+    #   elsif render_item.is_a?(Proc)
+    #     description << "Renders with block defined at #{render_item.source_location}"
+    #   elsif render_item.is_a?(Method)
+    #     description << "Renders with method defined at #{render_item.source_location}"
+    #   end
+    #
+    #
+    #   CONTROL_VARIABLES.each do |control_variable, *|
+    #     if value = send(control_variable)
+    #       # description << "#{control_variable}: #{value} [#{callers[control_variable]}]"
+    #     end
+    #   end
+    #
+    #   description << super
+    #   description.join("\n")
+    # end
+
+    def hooks_or_wrappers_present?
+      hooks.present? || wrap_all || wrap_each || wrap_with || collection.present?
+    end
+
+    def hooks_for(hook_name)
+      hooks[hook_name] if hooks.try(:key?, hook_name)
+    end
 
-      if render_item.is_a?(String)
-        description << "Renders with partial \"#{render_item}\""
-      elsif render_item.is_a?(Proc)
-        description << "Renders with block defined at #{render_item.source_location}"
+    def to_hash
+      hash = super
+      if collection_item_index
+        object_name = as || :object
+        hash.merge!(object_name => collection_item, current_index: collection_item_index)
       end
+      hash
+    end
 
+    private
 
-      CONTROL_VARIABLES.each do |control_variable, *|
-        if value = send(control_variable)
-          description << "#{control_variable}: #{value} [#{callers[control_variable]}]"
+    def add_hooks(block_definition)
+      if block_definition.hooks.present?
+        self.hooks = Hash.new {|hash, key| hash[key] = [] } if !hooks
+        block_definition.hooks.each do |hook_name, hooks|
+          self.hooks[hook_name].concat hooks
         end
       end
-
-      description << super
-      description.join("\n")
     end
 
-    private
+    def build_block_context(identifier, render_options)
+      parent_runtime_context = render_options.delete(:parent_runtime_context)
 
-    def convert_render_options(render_options)
-      if !render_options.is_a?(HashWithIndifferentAccess)
-        render_options = render_options.with_indifferent_access
+      self.block_name = identifier if identifier.is_a?(String) || identifier.is_a?(Symbol)
+
+      # Support legacy behavior - i.e. in versions 3.1 and earlier of Blocks,
+      #  default render options were given precedence over block-level defaults
+      if !Blocks.default_render_options_take_precedence_over_block_defaults
+        default_render_options = render_options.delete(:defaults)
       end
-      self.parent_runtime_context = render_options.delete(:parent_runtime_context)
-      self.render_options_set = OptionsSet.new(
-        "Render Options",
-        defaults: render_options.delete(:defaults),
-        runtime: render_options
-      )
-    end
 
-    def identify_block(block_identifier)
-      self.block_name, self.block_options_set = if block_identifier.is_a?(OptionsSet)
-        [block_identifier.name, block_identifier]
-      elsif block_defined?(block_identifier)
-        [block_identifier, block_definitions[block_identifier]]
-      elsif block_identifier.is_a?(Proc)
-        # TODO: figure out how to do this
-      else
-        [block_identifier, nil]
+      default_options = merge_definition render_options, description: 'Render Options'
+      merge_definition identifier, default_options: default_options, merge_default_options: true
+      merge_definition default_render_options, description: 'Default Render Options', merge_default_options: true
+      merge_definition({ block: runtime_block }, description: 'Runtime Block') if runtime_block
+      if parent_runtime_context
+        merge_definition parent_runtime_context.merged_block_options, description: "Parent Runtime Context"
+        # TODO: setup a configuration to only pull in parent collection item if flag on
+        if parent_runtime_context.collection_item_index
+          object_name = parent_runtime_context.as || :object
+          merge_definition({ 
+              object_name => parent_runtime_context.collection_item,
+              current_index: parent_runtime_context.collection_item_index
+            }, description: "Parent Collection Item")
+        end
       end
+
+      # Store the options as a hash  usable in child runtime contexts.
+      #  We do this before merging builder and global options as child runtime contexts will themselves merge in builder and global options
+      self.merged_block_options = to_hash.except!(*PROTECTED_OPTIONS)
+
+      merge_definition builder.options, description: 'Builder Options', merge_default_options: true
+      merge_definition Blocks.global_options, description: 'Global Options', merge_default_options: true
     end
 
-    def add_proxy_options(proxy_block_name)
-      if block_defined?(proxy_block_name)
-        proxy_block = block_definitions[proxy_block_name]
+    def merge_definition(definition, description: nil, default_options: [], follow_recursion: false, merge_default_options: false)
+      had_render_strategy = render_strategy_item.present?
+      follow_recursion ||= !had_render_strategy
 
-        proxy_options_set.add_options(proxy_block)
+      if definition.present?
 
-        render_strategy, render_item = proxy_block.current_render_strategy_and_item
+        if definition.is_a?(Hash)
+          default_options << definition.delete(:defaults) if definition.key?(:defaults)
+          
+          self.block_name = definition.block_to_render if definition.is_a?(HookDefinition)
+          reverse_merge! description, definition
 
-        if render_strategy == RENDER_WITH_PROXY
-          add_proxy_options render_item
-        elsif render_item.nil? && builder.respond_to?(proxy_block_name)
-          Proc.new do |*args|
-            options = args.extract_options!
-            runtime_block = self.runtime_block || options[:block]
-            builder.send(proxy_block_name, *args, options, &runtime_block)
+          if follow_recursion && renders_with_proxy?
+            merge_definition(render_strategy_item, default_options: default_options, follow_recursion: true)
           end
-        else
-          render_item
-        end
 
-      elsif builder.respond_to?(proxy_block_name)
-        Proc.new do |*args|
-          options = args.extract_options!
-          runtime_block = self.runtime_block || options[:block]
-          builder.send(proxy_block_name, *args, options, &runtime_block)
-        end
-      end
-    end
+        elsif block_defined?(definition)
+          proxy_block = block_for(definition)
 
-    def merge_options_and_identify_render_item
-      determined_render_item = false
-      all_options_sets = if parent_runtime_context
-        [
-          parent_runtime_context.render_options_set.clone,
-          block_options_set,
-          parent_runtime_context.block_options_set.try(:clone),
-          # TODO: figure out how to deal with these - they don't technically belong here
-          parent_runtime_context.proxy_options_set.clone,
-          builder_options_set,
-          Blocks.global_options_set
-        ].compact
-      else
-        [
-          render_options_set,
-          block_options_set,
-          # TODO: consider having the runtime_block be merged into the
-          #  default render options set
-          OptionsSet.new("Runtime Block", block: self.runtime_block),
-          builder_options_set,
-          Blocks.global_options_set
-        ].compact
-      end
+          self.skip_content = true if proxy_block.skip_content
+          self.skip_completely = true if proxy_block.skip_completely
+
+          add_hooks proxy_block
+          reverse_merge! proxy_block
 
-      options_set_with_render_strategy_index = nil
-      all_options_sets.
-        map(&:render_strategies_and_items).
-        transpose.
-        detect do |options_for_level|
-          options_set_with_render_strategy_index = options_for_level.index(&:present?)
-          if options_set_with_render_strategy_index.present?
-            self.render_strategy, self.render_item =
-              options_for_level[options_set_with_render_strategy_index]
-            true
+          if proxy_block.default_options
+            default_options << proxy_block.default_options
           end
-        end
 
-      if self.render_strategy == RENDER_WITH_PROXY
-        self.render_item = add_proxy_options render_item
-      end
+          proxy_render_item = proxy_block.render_strategy_item
+
+          if proxy_block.renders_with_proxy?
+            merge_definition proxy_render_item, default_options: default_options, follow_recursion: true if follow_recursion
+          elsif follow_recursion
+            # reverse_merge! default_options
+            # TODO: this should be based on a configuration - whether to use methods
+            if proxy_render_item.nil? && builder.respond_to?(definition)
+              self.render_item = builder.method(definition)
 
-      [:runtime_options, :standard_options, :default_options].each do |option_level|
-        all_options_sets.each_with_index do |options_set, index|
-          options_for_level = options_set.send(option_level)
-          add_options options_for_level
+            else
+              self.render_item = proxy_render_item
+            end
 
-          if index == options_set_with_render_strategy_index
-            options_for_level = proxy_options_set.send(option_level)
-            add_options options_for_level
           end
+
+        elsif builder.respond_to?(definition)
+          # TODO: is ||= necessary here?
+          self.render_item ||= builder.method(definition)
+
         end
+
+        # TODO: is this line necessary? Should it be the else clause above
+        self.render_item ||= render_strategy_item if !renders_with_proxy?
       end
 
-      if render_item.blank?
-        self.render_item = runtime_block
+      if merge_default_options
+        default_options.each do |options|
+          merge_definition options, merge_default_options: true
+        end
       end
+
+      default_options
     end
 
     def extract_control_options
       CONTROL_VARIABLES.each do |control_variable, synonyms|
         variant = (Array(synonyms) + Array(control_variable)).detect {|variant| key?(variant)}
-        value = delete(variant)
-        callers[control_variable] = callers[variant] if value
+        value = delete(variant) if variant
         self.send("#{control_variable}=", value)
       end
 
-      RENDERING_STRATEGIES.each {|rs| delete(rs) }
+      except!(*RENDERING_STRATEGIES)
     end
   end
 end